配额、额度和限制

每个密钥都有每日免费配额。超出后，请求将使用预付额度，或由 Unlimited 套餐覆盖。每个响应都会在响应头中告诉您当前的使用情况。

每日配额

键	每个 UTC 日免费	超出免费配额后	IP 名额
无密钥	每个地址 2,500 个	不收费；在重置前返回 `429 quota_exceeded` 并附带 `Retry-After`	无
按量付费	2,500	每个请求 €0.0001，从账户额度中扣除；余额为零时返回 `402 no_credits`	每滚动 24 小时 2 个
Unlimited	全部	不收费	每滚动 24 小时 3 个

带密钥的配额按密钥计算，而不是按账户计算：三个密钥意味着三倍的 2,500 个免费请求。无密钥配额按地址计算，同一网络中的地址共享这份配额。一个网络与从该网络使用的密钥共用同一份配额：不带密钥的请求会减少从同一网络使用的密钥当天可用的数量，反之亦然，因此同一地点无法两次获得 2,500 个免费请求。额度按账户计算，由超出其配额的任何密钥使用。一天指 UTC 日历日；X-Quota-Reset 给出下一次重置的精确 Unix 时间。

哪些算作请求

对任何端点的每次成功调用（200）都计为一次请求，无论是否找到结果。
批量调用中的每一项都计为一次请求：IP 批量查询中的每个地址、多点海拔或时区调用中的每个点、兼容替换主机批量端点中的每条记录。原服务商也是这样计数的。超出剩余配额的批量请求会在处理前被整体拒绝，并返回该服务商自己的限额错误，而不是只回答一部分。每个主机每次调用接受的条目数与其原服务商相同（ip-api 和 MapQuest 为 100，ipstack 为 50，Google 海拔为 512，ipinfo、Mapbox 和 Geoapify 为 1,000，Bing 和 Open-Elevation 为 1,024，Geocodio 和 TomTom 的异步批量为 10,000；原生端点为 100）。获取已存储的异步结果不计数。
被拒绝并返回 400、401、402、403 或 404 的调用不计数，也不收费。
因 500 或 503 失败的调用不计数，也不收费。
JavaScript 兼容替换中的地图瓦片、样式 JSON 和库加载不计数。

IP 名额

一个密钥同一时间可从两个 IP 地址使用（Unlimited 密钥为三个）。每个地址从其首次请求起占用名额 24 小时，然后释放。在所有名额都被占用时，来自其他地址的请求会收到 403 key_ip_limit，并附带下一个名额释放的时间。详细信息和示例请参阅身份验证页面。

突发流量

目前无论是否使用密钥，都没有固定的每秒请求数限制。看起来像失控循环或攻击的流量可能会被减速，如果您的某个密钥发生这种情况，我们会通知您。如果您有大型任务，请使用批量形式（ips、locations），而不是发送成千上万次单独调用。

读取响应头

x-quota-limit: 2500          # free per day for this key; -1 on an Unlimited key
x-quota-used: 2431           # counted today on this key, including this request
x-quota-free-remaining: 69   # free requests left today on this key
x-credits-remaining: 148200  # requests the account's credit still covers
x-key-ips-used: 1            # IP slots currently held on this key
x-key-ips-limit: 2           # slots on this key
x-quota-reset: 1789948800    # Unix time of the next 00:00 UTC
x-request-id: 2726386e38428697

处理 402 和 403

{ "status": "error", "error": { "code": "no_credits", "message": "The free allowance of 2500 requests for today is used and the account balance (€0.0000, 0 requests) does not cover this request. Add credit at https://www.mygeocode.com/dashboard or wait for the reset at 00:00 UTC." } }

不要循环重试；在充值或当天重置之前，结果都会相同。读取 X-Quota-Reset，然后选择等待、让操作失败并告知用户，或者充值。额度不足时，控制台会给您发送电子邮件。

{ "status": "error", "error": { "code": "key_ip_limit", "message": "This key is already in use from 2 IP addresses in the last 24 hours (limit 2). The next slot frees at 2026-09-21 23:06 UTC. Use another key or an additional Unlimited package for more addresses." } }

这表示一台并非该密钥当前名额持有者的机器尝试使用它。通常是新服务器或重新部署后换了新地址；请为那台机器单独配一个密钥。

减少请求

您可以无限期缓存结果，所以请这样做。地址不会移动；明天进行同样的正向地理编码会得到同样的结果。IP 地址段变化缓慢；缓存一天是安全的。一个点的时区规则很少变化，IANA 名称基本上从不变化。对于自动补全，请将输入防抖设置为约 150 毫秒，并在用户选定建议后停止发送。