正向地理编码

将文本转换为坐标。接受任何语言的完整地址、部分地址、邮政编码、地名和兴趣点。

GEThttps://api.mygeocode.com/v1/forward

参数

参数	类型	说明
`q`必填*	字符串	要进行地理编码的自由格式文本。最多 256 个字符。
`street`, `city`, `state`, `postcode`, `country`	字符串	*`q` 的结构化替代方式。当您已经将地址分字段保存时使用。如果没有 `q`，至少需要提供其中一个。这里的 `country` 是 ISO 3166-1 alpha-2 代码。
`place_id`	字符串	*来自自动补全的 `place_id`。返回该地点及其完整的地址组成部分和边界范围。优先于 `q`。
`limit`可选	整数	最大结果数，1 到 10。默认为 5。
`countries`可选	字符串	以逗号分隔的 ISO 3166-1 alpha-2 代码。只返回这些国家的结果。示例：`gb,ie`。
`bounds`可选	字符串	`south,west,north,east`，使用十进制度数。框内的结果排在前面。添加 `strict=1` 可排除框外的结果。
`proximity`可选	字符串	`lat,lon`。靠近此点的结果排在前面。
`lang`可选	字符串	响应中名称所用的 ISO 639-1 代码。默认为 `en`。
`key`可选	字符串	API 密钥（如果未通过 `X-API-Key` 请求头发送）。

示例

curlJavaScriptPython

$ curl -H "X-API-Key: YOUR_KEY" "https://api.mygeocode.com/v1/forward?q=Dam+1,+Amsterdam&countries=nl&limit=1"

const url = new URL("https://api.mygeocode.com/v1/forward");
url.searchParams.set("q", "Dam 1, Amsterdam");
url.searchParams.set("countries", "nl");
url.searchParams.set("limit", "1");

const data = await (await fetch(url, { headers: { "X-API-Key": "YOUR_KEY" } })).json();
console.log(data.results[0]);

import requests

r = requests.get("https://api.mygeocode.com/v1/forward",
                 params={"q": "Dam 1, Amsterdam", "countries": "nl", "limit": 1}, headers={"X-API-Key": "YOUR_KEY"}, timeout=10)
print(r.json()["results"][0])

响应

{
  "status": "ok",
  "query": "Dam 1, Amsterdam",
  "results": [
    {
      "formatted": "Dam 1, 1012 JS Amsterdam, Netherlands",
      "lat": 52.373119,
      "lon": 4.893604,
      "type": "address",
      "precision": "house",
      "confidence": 0.98,
      "place_id": "nl.addr.c21d40e8",
      "components": {
        "house_number": "1",
        "road": "Dam",
        "neighbourhood": "Centrum",
        "city": "Amsterdam",
        "state": "North Holland",
        "state_code": "NH",
        "postcode": "1012 JS",
        "country": "Netherlands",
        "country_code": "nl"
      },
      "bounds": { "north": 52.373519, "south": 52.372719, "east": 4.894204, "west": 4.893004 }
    }
  ]
}

响应字段

字段	类型	说明
`query`	字符串	我们解析的文本（去除首尾空白后）。
`results`	数组	匹配项，最佳匹配在前。没有匹配时为空。
`results[].formatted`	字符串	按该国家惯用格式书写的完整地址。
`results[].lat`, `lon`	数字	WGS 84 十进制度数。
`results[].type`	字符串	`address`, `street`, `postcode`, `city`, `region`, `country`, `poi`.
`results[].precision`	字符串	`house`、`street`、`postcode`、`admin`。表示该坐标点代表的对象。请参阅覆盖范围。
`results[].confidence`	数字	0 到 1。结果与查询的匹配程度。低于 0.5 表示是我们推测的。
`results[].place_id`	字符串	该地点的稳定标识符。
`results[].components`	对象	地址组成部分。见下文。
`results[].bounds`	对象	匹配要素的 `north`、`south`、`east`、`west` 边界。

组成部分键名

只包含适用的键。所有国家都使用相同的键。

键	含义
`name`	当匹配结果是兴趣点或建筑物时，为其名称。
`house_number`	可包含字母和范围：`221B`、`12-14`。
`road`	带类型的街道名称：`Baker Street`、`Avenue Anatole France`。
`neighbourhood`, `suburb`	城市以下的区域（在该国家使用的情况下）。
`city`	城市、城镇或村庄。
`county`	县或区。
`state`, `state_code`	州、省或地区，以及其 ISO 3166-2 后缀（如有）。
`postcode`	邮政编码，按邮政机构的格式书写。
`country`, `country_code`	国家名称和小写的 ISO 3166-1 alpha-2 代码。

注意事项

结果按置信度、精度和距离的综合排序。除非您要显示一个选择列表，否则应使用第一个结果。
当在已知街道上找不到门牌号时，结果为 type: street 和 precision: street，并在数据允许时对门牌号进行插值。如果这对您很重要，请检查 precision。
仅用邮政编码作为 q 也完全可以。对于只涉及邮政编码的工作负载，邮政编码端点速度更快，并返回邮政机构使用的地名。
用一种文字查询使用另一种文字的地点（例如用西里尔字母查询日本地址）是可行的，但响应所用的文字由 lang 决定。

以其他服务商格式进行的同一查询

如果您已有针对这些服务商之一编写的代码，请保留它：兼容替换主机接受相同的路径和参数，并以该服务商的响应结构作答，背后由此端点提供支持。请参阅兼容替换主机的工作原理。

服务商	主机	路径
Google Maps 平台	`gapi.mygeocode.com`	`/maps/api/geocode/json?address=...`
Bing Maps REST 服务	`bing.mygeocode.com`	`/REST/v1/Locations?q=...` `/REST/v1/Locations?countryRegion=...&locality=...&addressLine=...`
HERE 地理编码与搜索	`here.mygeocode.com`	`/v1/geocode?q=...` `/v1/geocode?qq=street=...;city=...`
Mapbox Geocoding	`mapbox.mygeocode.com`	`/geocoding/v5/mapbox.places/{query}.json` `/search/geocode/v6/forward?q=...`
Geocode.Farm	`farm.mygeocode.com`	`/forward/?addr=...` `/v3/json/forward/?addr=...`
OpenStreetMap Nominatim	`osm.mygeocode.com`	`/search?q=...&format=json` `/search?street=...&city=...&country=...&format=json`
OpenCage	`opencage.mygeocode.com`	`/geocode/v1/json?q=...` `/geocode/v1/geojson?q=...`
LocationIQ	`locationiq.mygeocode.com`	`/v1/search?q=...&format=json`
Geoapify	`geoapify.mygeocode.com`	`/v1/geocode/search?text=...`
TomTom Search	`tomtom.mygeocode.com`	`/search/2/geocode/{query}.json` `/search/2/structuredGeocode.json?countryCode=...&streetName=...`
MapQuest Geocoding	`mapquest.mygeocode.com`	`/geocoding/v1/address?location=...` `/geocoding/v1/batch?location=...&location=...`
Geocodio	`geocodio.mygeocode.com`	`/v1.7/geocode?q=...` `/v1.7/geocode (POST, JSON array)`
PositionStack	`positionstack.mygeocode.com`	`/v1/forward?query=...`

批量查询

向同一路径 POST 一个 JSON 正文，其中 queries 是最多包含 100 个地址的数组，响应会带有一个 results 数组，按发送顺序每个查询对应一条记录。每条记录计为一次请求，超出剩余配额的批量请求会被整体拒绝。

$ curl -X POST "https://api.mygeocode.com/v1/forward" -H "Content-Type: application/json" -d '{"queries": ["Brandenburg Gate, Berlin", "Bahnhofstrasse 1, Zurich"]}'

错误

当 q、结构化字段和 place_id 都未提供，limit 超出 1 到 10 的范围，或 bounds 或 proximity 格式错误时，返回 400 invalid_request。其他情况请参阅错误。