Cotas, crédito e limites

Toda chave recebe uma cota diária gratuita. Além dela, as requisições são descontadas do crédito pré-pago ou cobertas por um pacote Unlimited. Toda resposta mostra a sua situação nos cabeçalhos.

A cota diária

A cota com chave é por chave, não por conta: três chaves significam três vezes 2.500 requisições gratuitas. A cota sem chave é por endereço, e endereços da mesma rede a compartilham. Uma rede e as chaves usadas a partir dela consomem uma única cota: requisições sem chave reduzem o que uma chave usada a partir da mesma rede recebe naquele dia, e vice-versa, então as 2.500 gratuitas não podem ser obtidas duas vezes no mesmo lugar. O crédito é por conta e é consumido pela chave que passar da sua cota. O dia é o dia do calendário UTC; X-Quota-Reset traz o horário Unix exato do próximo reinício.

O que conta como requisição

• Toda chamada bem-sucedida (200) a qualquer endpoint conta como uma, tenha ela encontrado algo ou não.
• Cada item numa chamada em lote conta como uma requisição: cada endereço num lote de IP, cada ponto numa chamada de altitude ou fuso horário com vários pontos, cada entrada nos endpoints de lote dos hosts compatíveis. É assim que os provedores originais também contam. Um lote maior do que o que resta da cota é recusado por inteiro, antes de qualquer processamento, com o próprio erro de limite do provedor, em vez de ser respondido em parte. Cada host aceita tantos itens por chamada quanto o seu provedor original (100 para ip-api e MapQuest, 50 para ipstack, 512 para Google elevation, 1.000 para ipinfo, Mapbox e Geoapify, 1.024 para Bing e Open-Elevation, 10.000 para Geocodio e para o lote assíncrono da TomTom; 100 nos endpoints nativos). Buscar um resultado assíncrono armazenado não conta nada.
• Chamadas recusadas com 400, 401, 402, 403 ou 404 não contam e não custam nada.
• Chamadas que falham com 500 ou 503 não contam e não custam nada.
• Tiles de mapa, JSON de estilo e carregamentos de biblioteca dos drop-ins em JavaScript não contam.

Vagas de IP

Uma chave funciona a partir de dois endereços IP ao mesmo tempo (três para uma chave Unlimited). Cada endereço mantém a sua vaga por 24 horas a partir da sua primeira requisição e depois a libera. Uma requisição de outro endereço enquanto todas as vagas estão ocupadas recebe 403 key_ip_limit com o horário em que a próxima vaga será liberada. Os detalhes e exemplos estão na página de autenticação.

Picos

Hoje não há um limite fixo de requisições por segundo, com ou sem chave. Tráfego que pareça um loop descontrolado ou um ataque pode ser desacelerado, e avisaremos você se isso acontecer com uma das suas chaves. Se você tiver um trabalho grande, use as formas em lote (ips, locations) em vez de milhares de chamadas individuais.

Como ler os cabeçalhos

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

Como tratar 402 e 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." } }

Não tente de novo em loop; a resposta será a mesma até que crédito seja adicionado ou o dia reinicie. Leia X-Quota-Reset e aguarde, falhe a operação e avise o usuário, ou recarregue. O painel envia um e-mail quando o crédito está acabando.

{ "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." } }

Isso significa que uma máquina que não é uma das atuais ocupantes das vagas da chave tentou usá-la. Normalmente é um servidor novo ou uma nova implantação com um endereço novo; dê a essa máquina uma chave própria.

Como reduzir requisições

Você pode armazenar resultados em cache indefinidamente, então faça isso. Endereços não se movem; a mesma geocodificação direta amanhã dá a mesma resposta. Blocos de IP mudam devagar; um dia é um tempo de cache seguro. As regras de fuso horário de um ponto raramente mudam, e o nome IANA praticamente nunca. No preenchimento automático, aplique debounce na entrada de cerca de 150 ms e pare de enviar assim que o usuário escolher uma sugestão.