身份验证

每个地址每天前 2,500 个请求无需密钥。超出部分都需要密钥：密钥决定请求使用谁的额度或套餐、哪些机器可以使用它，并为您提供使用记录。密钥免费，一分钟即可获取。

不使用密钥

发送不带任何凭据的请求，也会得到响应。每个地址每天可通过这种方式发送 2,500 个请求，从 UTC 00:00 开始计算，涵盖所有端点和所有兼容替换主机，数据和响应与付费账户完全相同。超出后，API 会返回 429 quota_exceeded 并附带 Retry-After 响应头，直到重置为止；不会收取任何费用，也不会排队。

有两点需要了解。属于同一网络的地址共享同一份配额，因此繁忙的办公室、校园或同一个云区域可能比单台机器更快用完。此外，一个网络与从该网络使用的密钥共用同一份配额：不带密钥发出的请求会减少从该网络使用的密钥当天可用的数量，而使用该密钥发出的免费请求也会减少该网络不带密钥时可用的数量。因此，注册会带来额度、套餐和使用记录，而不是从同一地点再获得一份 2,500 个免费请求。

获取密钥

在 www.mygeocode.com/signup 使用您的姓名、电子邮件地址和密码注册。您的第一个密钥会当场显示一次；请复制保存，因为我们只存储其哈希值。您可以在 API 密钥页面下创建任意数量的其他密钥，为每个密钥添加标签（每台服务器或每个应用一个是个好习惯），并随时撤销其中任何一个。

每个密钥每天有 2,500 个免费请求，从 UTC 00:00 开始计算，涵盖所有端点和所有兼容替换主机。超出后，请求将以每个 €0.0001 的价格使用账户的预付额度，除非该密钥属于 Unlimited 套餐。

发送密钥

以下任何一种方式在所有主机上都有效。建议使用请求头：查询字符串会出现在服务器日志、浏览器历史记录和代理中。

$ curl -H "X-API-Key: mg_7f3c2a19e04b...d1" "https://api.mygeocode.com/v1/reverse?lat=51.5&lon=-0.12"

$ curl -H "Authorization: Bearer mg_7f3c2a19e04b...d1" "https://api.mygeocode.com/v1/reverse?lat=51.5&lon=-0.12"

$ curl "https://api.mygeocode.com/v1/reverse?lat=51.5&lon=-0.12&key=mg_7f3c2a19e04b...d1"

$ curl -u "mg_7f3c2a19e04b...d1:" "https://api.mygeocode.com/v1/reverse?lat=51.5&lon=-0.12"

在兼容替换主机上，密钥也可以放在原服务商密钥所在的位置：Google、Bing、Geocode.Farm、OpenCage、LocationIQ、TomTom 和 MapQuest 使用 key；HERE 和 Geoapify 使用 apiKey；Mapbox 使用 access_token；Geocodio 使用 api_key；PositionStack 和 ipstack 使用 access_key；ipinfo 使用 token。Nominatim 和 Open-Elevation 客户端需添加 key= 或请求头，因为这两项服务本身没有密钥。

除查询参数外，所有主机还接受四种发送凭据的方式，因此按服务商方式进行身份验证的客户端库无需任何修改：X-API-Key 请求头、Authorization: Bearer、以密钥作为用户名的 HTTP Basic 身份验证（即 curl -u KEY: 发送的内容，也是 ipinfo 示例所用的方式），以及 Google 客户端发送的 X-Goog-Api-Key 请求头。对于通过 POST 提交的端点，表单正文中的密钥也会被读取。更改主机名和密钥就是全部的迁移工作。

两种密钥

	按量付费密钥	Unlimited 密钥
获取方式	在控制台中免费创建	随每个 Unlimited 套餐提供（每月 €50）
免费请求	每天 2,500 个	全部免费
超出免费配额后	每个 €0.0001，从账户额度中扣除；余额为零时返回 `402`	不收费
IP 名额（滚动 24 小时）	2	3
套餐到期后		密钥继续作为按量付费密钥使用

IP 名额

一个密钥同一时间只能从有限数量的 IP 地址使用：按量付费密钥两个，Unlimited 密钥三个。该规则按地址滚动计算：

某个地址首次使用该密钥时会占用一个名额，并从首次请求起保留 24 小时。
这 24 小时结束后，名额会自动释放，与其他地址的情况无关。如果同一地址之后再次使用，它只需重新占用一个名额。
所有名额都被占用时，来自新地址的请求会被拒绝，返回 403 和代码 key_ip_limit。消息会说明下一个名额何时释放。被拒绝的请求不计数。

因此，如果两台服务器在 02:00 首次使用某个密钥，第三台在 04:00 首次使用，那么两个名额会在次日 02:00 释放，第三个在 04:00 释放。控制台会显示哪些地址占用了密钥的名额，以及每个名额何时释放。需要更多机器？请创建更多按量付费密钥，或添加更多 Unlimited 套餐；每个套餐都带有自己的密钥。

设置此限制是因为密钥会泄露。有了它，流入公开代码仓库的密钥对发现者几乎没有价值；而且由于额度是预付的，任何人都无法花费超过您充值的余额。

密钥与浏览器

不要把密钥放在 JavaScript 或移动应用中。任何人都可以从页面中读取它，而且每个访客都是一个新的 IP 地址，因此在第二或第三个访客之后，密钥的名额就会用完。请从您自己的服务器调用 API，并将密钥保存在服务器上。JavaScript 地图兼容替换无需密钥即可加载瓦片和库；只有其地理编码调用需要经过您的服务器。

撤销与轮换

在控制台中撤销密钥后，它会在一分钟内失效。请先创建新密钥并部署，然后再撤销旧密钥；在此期间两者都可使用。密钥永远不会自行过期。

拒绝情况

HTTP	`code`	含义
401	`missing_key`	未发送密钥，且此服务器已关闭无密钥访问（默认开启）。
429	`quota_exceeded`	该地址当天的无密钥免费配额已用完；`Retry-After` 说明距离重置还有多长时间。
401	`invalid_key`	密钥不存在。
401	`key_revoked`	密钥已被撤销。
402	`no_credits`	当天的免费配额已用完，且账户余额为零。
403	`key_ip_limit`	该密钥的所有 IP 名额都已被其他地址占用。
403	`account_suspended`	账户已被暂停；请联系支持。

以上情况均不计入配额，也不消耗额度。在兼容替换主机上，它们以原服务商的格式返回；请参阅兼容性。