Monitore o uso da sua chave antes de atingir um limite
Acompanhar seus cabeçalhos de cota ao longo do caminho mostra quando um limite está se aproximando, bem antes de uma requisição ser realmente rejeitada.
Combine código postal e país para consultas mais rápidas
A geocodificação direta foi feita para lidar com texto livre bagunçado, o que significa que ela trabalha nos bastidores para descobrir que tipo de entrada está analisando. Se você já sabe que tem um código postal limpo e um país, existe um caminho mais direto.
Indo direto ao endpoint de código postal
Em vez de montar uma string de texto livre e enviá-la para /v1/forward, envie o código e o país diretamente para /v1/postcode.
GET /v1/postcode?code=90210&country=US{
"status": "ok",
"postcode": "90210",
"country_code": "US",
"results": [
{"lat": 34.0901, "lon": -118.4065, "components": {"city": "Beverly Hills", "region": "CA", "country": "US"}}
]
}Por que esta é a opção mais adequada
Um par de código postal e país já é uma entrada totalmente estruturada, então não há ambiguidade para o endpoint resolver, como pode haver com uma string de texto livre que talvez corresponda a vários lugares com nomes parecidos. Usar o endpoint feito exatamente para esse formato de entrada gera uma correspondência mais limpa, com menos risco de um resultado inesperado.
Um segundo exemplo: um código postal alfanumérico
A mesma chamada funciona da mesma forma para um país que usa letras e números juntos, em vez de apenas dígitos.
GET /v1/postcode?code=K1A 0B1&country=CAPassar o parâmetro de país é o que torna isso confiável, já que uma string de código sozinha nem sempre é única entre países, e é o parâmetro de país que informa ao endpoint com base em qual sistema postal ela deve ser interpretada.
Quando você ainda precisa da geocodificação direta
Se você precisa de uma correspondência específica no nível da rua, e não da área geral que um código postal cobre, a geocodificação direta com o endereço completo continua sendo a ferramenta certa, já que uma consulta de código postal resolve para a área que o código cobre, e não para um prédio específico dentro dela. Use /v1/postcode para consultas no nível de área, como validar uma zona de entrega, e /v1/forward quando precisar de precisão no nível do imóvel.
Um erro comum a evitar
Não presuma que um código postal sempre corresponde a exatamente um ponto que representa com precisão todos os endereços dentro dele. As coordenadas retornadas por /v1/postcode representam a área coberta pelo código, que pode ser um único quarteirão ou, em alguns países, uma zona muito maior. Tratar esse ponto retornado como se fosse a localização exata do prédio de um cliente específico, em vez de um ponto representativo de todo o código, vai introduzir erro em qualquer coisa sensível a distância construída em cima dele.
Combinando os dois em um fluxo de trabalho
Um padrão comum é validar primeiro o par de código postal e país com /v1/postcode e, depois que ele passar, enviar o endereço completo para /v1/forward para obter as coordenadas exatas. São duas requisições por envio, uma para cada etapa, em vez de tentar forçar um único endpoint a fazer os dois trabalhos.
Um caso extremo: um código que não retorna resultados
Um array de resultados vazio significa que o código não foi reconhecido para o país informado, o que é uma situação diferente de uma resposta de erro. Trate isso como trataria qualquer outra entrada não reconhecida, pedindo ao cliente que confira o que digitou, em vez de exibir como um erro do sistema.
Quanto custa
Cada consulta de código postal é uma requisição, o mesmo custo de uma consulta de geocodificação direta. Escolher o endpoint certo para uma entrada estruturada não muda o custo, muda o quão diretamente você chega a um resultado correto.
Recorrer ao endpoint de código postal quando você já tem uma entrada limpa e estruturada evita a ambiguidade extra de reconstruir uma string de texto livre só para desmontá-la de novo na interpretação. Todos os detalhes estão na documentação da consulta de código postal.