Autenticação

As primeiras 2.500 requisições por dia a partir de um endereço não precisam de chave. A chave serve para tudo o que passar disso: ela define de qual crédito ou pacote a requisição é descontada e quais máquinas podem usá-la, e oferece um histórico de uso. As chaves são gratuitas e levam um minuto para obter.

Sem chave

Envie a requisição sem nenhuma credencial e ela é respondida. Todo endereço tem 2.500 requisições por dia dessa forma, contadas a partir das 00:00 UTC em todos os endpoints e em todos os hosts compatíveis, com os mesmos dados e as mesmas respostas de uma conta paga. Além disso, a API responde 429 quota_exceeded com um cabeçalho Retry-After até o reinício; nada é cobrado e nada fica na fila.

Duas coisas a saber. Endereços que pertencem à mesma rede compartilham uma única cota, então um escritório movimentado, um campus ou uma região de nuvem pode esgotá-la mais rápido do que uma única máquina. E uma rede e as chaves usadas a partir dela consomem a mesma cota: requisições feitas sem chave reduzem o que uma chave usada a partir dessa rede recebe hoje, e requisições gratuitas feitas com essa chave reduzem o que a rede recebe sem chave. Portanto, cadastrar-se adiciona crédito, pacotes e histórico, e não um segundo lote gratuito de 2.500 a partir do mesmo local.

Como obter uma chave

Cadastre-se em www.mygeocode.com/signup com o seu nome, um endereço de e-mail e uma senha. A sua primeira chave é mostrada uma única vez, na hora; copie-a, porque só um hash é armazenado. Crie quantas chaves adicionais quiser em Chaves de API, dê um rótulo a cada uma (uma por servidor ou por aplicação é um bom hábito) e revogue qualquer uma delas a qualquer momento.

Cada chave tem 2.500 requisições gratuitas por dia, contadas a partir das 00:00 UTC em todos os endpoints e em todos os hosts compatíveis. Além disso, as requisições são descontadas do crédito pré-pago da conta a € 0,0001 cada, a menos que a chave pertença a um pacote Unlimited.

Como enviar a chave

Qualquer uma destas formas funciona em todos os hosts. Prefira o cabeçalho: query strings acabam em logs de servidor, históricos de navegador e proxies.

$ 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"

Nos hosts compatíveis, a chave também vai onde ia a chave do provedor original: key para Google, Bing, Geocode.Farm, OpenCage, LocationIQ, TomTom e MapQuest; apiKey para HERE e Geoapify; access_token para Mapbox; api_key para Geocodio; access_key para PositionStack e ipstack; token para ipinfo. Clientes de Nominatim e Open-Elevation adicionam key= ou um cabeçalho, já que esses dois serviços não têm chave própria.

Além do parâmetro de consulta, quatro formas de enviar credenciais são aceitas em todos os hosts, então uma biblioteca cliente que autentica do jeito do provedor não precisa de nenhuma alteração: o cabeçalho X-API-Key, Authorization: Bearer, autenticação HTTP Basic com a chave como nome de usuário (o que curl -u KEY: envia, e o que os exemplos do ipinfo usam) e o cabeçalho X-Goog-Api-Key que os clientes do Google enviam. Uma chave no corpo de um formulário também é lida, nos endpoints que recebem POST. Trocar o nome do host e a chave é toda a migração.

Dois tipos de chave

Vagas de IP

Uma chave pode ser usada a partir de um número limitado de endereços IP ao mesmo tempo: dois para uma chave de pagamento por uso, três para uma chave Unlimited. A regra é móvel, por endereço:

• Na primeira vez que um endereço usa a chave, ele ocupa uma vaga e a mantém por 24 horas a partir dessa primeira requisição.
• Quando essas 24 horas terminam, a vaga é liberada sozinha, independentemente do que os outros endereços estejam fazendo. Se o mesmo endereço voltar depois, ele simplesmente ocupa uma vaga de novo.
• Uma requisição de um endereço novo enquanto todas as vagas estão ocupadas é recusada com 403 e o código key_ip_limit. A mensagem informa quando a próxima vaga será liberada. Requisições recusadas não são contadas.

Assim, se dois servidores usaram uma chave pela primeira vez às 02:00 e um terceiro às 04:00, duas vagas são liberadas às 02:00 do dia seguinte e a terceira às 04:00. O painel mostra quais endereços ocupam as vagas de uma chave e quando cada uma é liberada. Precisa de mais máquinas? Crie mais chaves de pagamento por uso ou adicione mais pacotes Unlimited; cada pacote traz a sua própria chave.

O limite existe porque chaves vazam. Com ele, uma chave que acaba num repositório público vale muito pouco para quem a encontra, e, como o crédito é pré-pago, ninguém pode gastar mais do que o saldo que você carregou.

Chaves e navegadores

Não coloque uma chave em JavaScript nem num app móvel. Qualquer pessoa consegue lê-la na página, e cada visitante é um novo endereço IP, então as vagas da chave acabam depois do segundo ou terceiro visitante. Chame a API a partir do seu próprio servidor e mantenha a chave lá. Os drop-ins de mapas em JavaScript carregam tiles e bibliotecas sem chave; só as chamadas de geocodificação precisam passar pelo seu servidor.

Revogação e rotação

Revogue uma chave no painel e ela para de funcionar em até um minuto. Crie a nova chave primeiro, implante-a e depois revogue a antiga; as duas funcionam nesse intervalo. As chaves nunca expiram sozinhas.

Recusas

Nenhuma dessas conta para a cota nem consome crédito. Nos hosts compatíveis, elas são informadas no formato do provedor original; veja compatibilidade.