Compatibilidade drop-in

Você não precisa aprender esta API para usá-la. Para dezessete outras APIs de geocodificação e consulta de IP, mantemos um host que aceita o formato de requisição desse provedor e responde no formato de resposta desse provedor, com os nossos dados por trás. O mesmo vale para as bibliotecas de mapas em JavaScript que esses provedores distribuem. A migração é uma troca de nome de host.

Como funciona

Cada host compatível é uma implementação completa da interface HTTP pública de um provedor: os mesmos caminhos, os mesmos parâmetros de consulta, os mesmos nomes de campos JSON, aninhamento e tipos, o mesmo vocabulário de status e os mesmos formatos de erro. Os valores são nossos. O seu código cliente, o seu código de parsing e o seu tratamento de erros não mudam.

1. Troque o host. maps.googleapis.com vira gapi.mygeocode.com, dev.virtualearth.net vira bing.mygeocode.com, e assim por diante. A tabela abaixo tem todos os pares.
2. Troque a chave, ou deixe-a de lado. Coloque a sua chave do My Geocode no parâmetro que a chave antiga usava (key, apiKey, access_token, token...). Qualquer endereço tem 2.500 requisições gratuitas por dia sem chave, e cada chave vem com 2.500 próprias, então migrar e testar não custa nada.
3. Compare. Execute uma amostra de requisições reais nos dois hosts. As coordenadas vão diferir um pouco porque os dados são diferentes; os nomes dos campos, não.

$ curl "https://maps.googleapis.com/maps/api/geocode/json?address=10+Downing+St+London&key=GOOGLE_KEY"

$ curl "https://gapi.mygeocode.com/maps/api/geocode/json?address=10+Downing+St+London&key=MYGEOCODE_KEY"

Todos os hosts compatíveis

Todos os hosts rodam na mesma infraestrutura, com os mesmos dados, a mesma cota gratuita e os mesmos preços de api.mygeocode.com. Clique em um provedor para ver a lista de endpoints, uma resposta de exemplo e as diferenças conhecidas.

Bibliotecas de mapas JavaScript

Trocar de provedor dói mais no navegador, onde o mapa, o widget de geocodificação e a cobrança estão emaranhados. Para as bibliotecas abaixo, a própria biblioteca é carregada do nosso host (ou, no caso de MapLibre, Mapbox GL e Leaflet, apontada para o nosso host por configuração) e mantém a sua API pública: google.maps.Map, Microsoft.Maps.Map, H.Map e o resto. Tiles, geocodificação, preenchimento automático e altitude vêm de nós. Carregamentos de mapa e tiles são gratuitos; chamadas de geocodificação contam normalmente.

A página de drop-ins em JavaScript tem os trechos de código de antes e depois, a lista do que está e do que não está incluído em cada biblioteca, e as URLs de tiles e estilos.

Onde vai a chave

Cada host aceita a chave no lugar em que o provedor original a espera, e também no cabeçalho X-API-Key. A chave é opcional: 2.500 requisições por dia por endereço não precisam de chave. Uma chave gratuita leva um minuto para obter e adiciona crédito, pacotes e um histórico de uso. Uma chave de pagamento por uso pode ser usada a partir de dois endereços IP a cada 24 horas móveis, e uma chave Unlimited a partir de três; use mais chaves ou pacotes para mais endereços (veja autenticação).

Cota e erros nos hosts compatíveis

A cota diária é a mesma de todos os outros lugares e é contada por chave, ou por endereço quando nenhuma chave é enviada, em api.mygeocode.com e em todos os hosts compatíveis: 2.500 gratuitas por dia, depois crédito ou uma chave Unlimited. Os cabeçalhos X-Quota-* e X-Key-IPs-* são enviados em todos os hosts, então você pode ler o estado real nos cabeçalhos, qualquer que seja o formato do corpo. No corpo, os limites são informados do jeito que o provedor os informa:

O que é igual e o que não é

Checklist de migração

1. Procure o nome de host do provedor no seu código e na sua configuração. Muitas vezes ele está em mais de um lugar: código do servidor, apps móveis, uma regra de CDN, uma configuração em cache.
2. Troque-o pelo host compatível da tabela acima. Mantenha o caminho.
3. Substitua a chave por uma chave do My Geocode. Use uma chave por servidor ou, no máximo, por dois; uma chave de pagamento por uso aceita dois endereços IP a cada 24 horas móveis, uma chave Unlimited aceita três.
4. Execute a sua suíte de testes existente. Ela deve passar sem alterações. Se faltar um campo do qual você depende, consulte a página do host para ver as lacunas conhecidas e nos avise.
5. Repita algumas centenas de requisições reais nos dois hosts e compare as coordenadas e os campos que você exibe. Observe a precision onde o host compatível a expõe (como location_type, accuracy, resultType e assim por diante).
6. Acompanhe o X-Quota-Used por um dia para dimensionar o seu plano: crédito abaixo de cerca de 19.000 requisições por dia, uma chave Unlimited acima disso.
7. Cancele a cobrança antiga.

SDKs dos provedores

A maioria das bibliotecas cliente oficiais aceita uma URL base personalizada, então elas também funcionam com os hosts compatíveis: os clientes do Google Maps Services (googlemaps para Python, @googlemaps/google-maps-services-js), os SDKs do Mapbox (opção origin), os clientes REST da HERE, as bibliotecas do ipinfo e wrappers do Nominatim como o geopy (domain=). Aponte-os para o host da tabela e passe a sua chave do My Geocode onde ficava a chave do provedor.

Um provedor que não está na lista

Adicionar um host leva alguns dias de trabalho quando o formato do provedor é documentado. Se você usa um serviço que não está aqui, diga qual é e, aproximadamente, quantas requisições por dia você envia. As adições recentes foram todas pedidos de usuários.