文档

所有调用都是向 https://api.mygeocode.com/v1/ 发送带查询参数的 GET 请求，并以 JSON 返回。本页介绍所有端点共通的部分。各端点页面介绍每个端点的参数和字段。

您的第一个请求

每个地址每天前 2,500 个请求无需密钥。在任何机器上都可以运行：

$ curl "https://api.mygeocode.com/v1/forward?q=Brandenburg+Gate,+Berlin&limit=1"

{
  "status": "ok",
  "query": "Brandenburg Gate, Berlin",
  "results": [
    {
      "formatted": "Brandenburger Tor, Pariser Platz, 10117 Berlin, Germany",
      "lat": 52.516275,
      "lon": 13.377704,
      "type": "poi",
      "precision": "house",
      "confidence": 0.99,
      "components": {
        "name": "Brandenburger Tor",
        "road": "Pariser Platz",
        "suburb": "Mitte",
        "city": "Berlin",
        "state": "Berlin",
        "postcode": "10117",
        "country": "Germany",
        "country_code": "de"
      },
      "bounds": { "north": 52.516441, "south": 52.516107, "east": 13.377862, "west": 13.377538 }
    }
  ]
}

这个请求计为您的地址今天 2,500 个免费请求中的 1 个。如果使用密钥，它将改为计入该密钥，响应头还会加上您的额度和 IP 名额数据。响应头会告诉您当前的使用情况：

HTTP/2 200
content-type: application/json; charset=utf-8
x-quota-limit: 2500
x-quota-used: 1
x-quota-free-remaining: 2499
x-quota-reset: 1756339200
x-request-id: 2726386e38428697

从其他服务商迁移过来？

您可能不需要阅读本页其余内容。如果您的代码已经在调用 Google Maps、Bing Maps、HERE、Mapbox、Geocode.Farm、Nominatim、OpenCage、LocationIQ、Geoapify、TomTom、MapQuest、Geocodio、PositionStack、ip-api、ipinfo、ipstack 或 Open-Elevation，我们运行着一个使用该服务商请求和响应格式的主机，背后是我们的数据。只需更改主机名，把您的密钥放在原来密钥的位置，解析代码保持不变即可。Google Maps JavaScript API、Bing Maps V8、HERE Maps for JavaScript、MapQuest.js 以及 MapLibre、Mapbox GL 和 Leaflet 的地理编码插件也同样适用。

兼容替换主机的工作原理：完整的主机对照表、密钥对应、错误对应以及迁移清单。

基础 URL 和端点

端点	路径	必填参数
正向地理编码	`GET /v1/forward`	`q`（或结构化字段）
逆地理编码	`GET /v1/reverse`	`lat`, `lon`
地址自动补全	`GET /v1/autocomplete`	`q`
IPv4 查询	`GET /v1/ipv4`	无（`ip` 可选）
IPv6 查询	`GET /v1/ipv6`	无（`ip` 可选）
IP 查询，两种版本均可	`GET /v1/ip`	无（`ip` 可选）
时区查询	`GET /v1/timezone`	`lat`, `lon`
海拔查询	`GET /v1/elevation`	`lat`、`lon` 或 `locations`
邮政编码查询	`GET /v1/postcode`	`code`

仅提供 HTTPS 服务。普通 HTTP 请求会被拒绝并返回 400，而不是重定向，以免密钥被意外以明文发送。支持 HTTP/2 和 HTTP/3。当客户端接受 gzip 或 br 时，响应会被压缩。

响应结构

每个响应都是一个 JSON 对象，其 status 为 ok 或 error。

为 ok 时，后面跟着数据：可能返回多个匹配项的端点返回 results（数组），逆地理编码返回 result（对象或 null），IP 和时区查询则返回扁平字段。
为 error 时，会有一个 error 对象，包含 code 字符串、message 说明语句，以及在相关时导致错误的 param。HTTP 状态码与之对应。请参阅错误。

有效但没有任何匹配的查询会返回 ok，并带有空的 results 数组或值为 null 的 result。这不是错误，并且计为一次请求。

所有端点都接受的参数

参数	说明
`key`	您的 API 密钥，如果您更喜欢用查询参数而不是 `X-API-Key` 请求头。请求头更好，因为查询字符串会出现在日志中。
`lang`	地名所用的 ISO 639-1 语言代码（在我们有相应数据的情况下）。默认为 `en`。地址格式始终遵循该国家的惯例。
`pretty`	设为 `1` 可缩进 JSON。在浏览器中很方便；在代码中请不要使用。

参数名区分大小写，且为小写。未知参数会被忽略，空参数视为未提供，因此 HTML 表单可以将可选字段留空提交。坐标使用十进制度数；lat 范围为 -90 到 90，lon 范围为 -180 到 180。文本使用 UTF-8，并应进行 URL 编码。

一段话讲清身份验证

密钥是可选的：每个地址无需密钥每天即可获得 2,500 个免费请求。密钥可通过 X-API-Key 请求头、Authorization: Bearer 令牌或 key 参数发送；密钥免费，注册账户只需您的姓名、电子邮件地址和密码。每个密钥每天有各自的 2,500 个免费请求；超出后，请求将以每个 €0.0001 的价格使用账户的预付额度，若密钥属于 Unlimited 套餐（每月 €50）则免费。来自同一网络的无密钥请求和带密钥请求共享同一份每日配额。按量付费密钥在每滚动 24 小时内可从两个 IP 地址使用，Unlimited 密钥可从三个 IP 地址使用。完整规则请参阅身份验证页面。

配额响应头

响应头	含义
`X-Quota-Limit`	此密钥每天的免费请求数，未发送密钥时则为此地址的免费请求数：2,500。Unlimited 密钥为 `-1`。
`X-Quota-Used`	此密钥今天已计数的请求数，包括本次请求。
`X-Quota-Free-Remaining`	此密钥今天剩余的免费请求数。Unlimited 密钥为 `-1`。
`X-Credits-Remaining`	账户额度还能支付多少个付费请求。
`X-Key-IPs-Used`, `X-Key-IPs-Limit`	此密钥当前占用的 IP 名额数，以及它拥有的名额总数。
`X-Quota-Reset`	下一个 UTC 00:00 的 Unix 时间，即每日计数器重置的时间。
`X-Request-Id`	请求的唯一 ID。联系支持时请提供此 ID。

从浏览器调用

所有端点都启用了 CORS，并且公开了配额响应头，但放在网页源代码中的密钥是公开的，并且在几个访客之后就会用尽其 IP 名额。请从您的服务器发起调用；请参阅密钥与浏览器。

版本控制

路径前缀 /v1/ 就是版本。在同一版本内，我们会新增字段和参数，但绝不删除或重命名，也绝不改变现有字段的含义。如果将来确实需要做不兼容的改动，它会放在 /v2/ 中，而 /v1/ 在公告发布后至少继续运行六个月。新增内容会在博客的新闻栏目中公布。

您的 JSON 解析器应忽略它不认识的字段。这是唯一的向前兼容要求。