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.
Divida um campo de endereço em texto livre em componentes estruturados
Um único campo de endereço em texto livre é fácil de coletar e difícil de trabalhar depois, principalmente quando você precisa filtrar por cidade ou agrupar por região. A geocodificação direta faz essa interpretação para você como efeito colateral de converter o endereço em coordenadas.
Enviando o texto livre
GET /v1/forward?q=1600 Pennsylvania Avenue, Washington, DC 20500&limit=1{
"status": "ok",
"query": "1600 Pennsylvania Avenue, Washington, DC 20500",
"results": [
{
"formatted": "1600 Pennsylvania Avenue NW, Washington, DC 20500",
"lat": 38.8977,
"lon": -77.0365,
"type": "address",
"precision": "house",
"confidence": 0.97,
"place_id": "def456",
"components": {"house_number": "1600", "street": "Pennsylvania Avenue NW", "city": "Washington", "region": "DC", "postcode": "20500", "country": "US"}
}
]
}Armazenando os componentes separadamente
Depois de obter o objeto components, grave cada campo em uma coluna própria do banco de dados, em vez de guardar apenas a string original em texto livre. Isso permite filtrar os registros de clientes por cidade ou região, gerar relatórios regionais precisos e validar se um código postal e uma cidade realmente combinam, e nada disso é prático com uma única string sem estrutura.
Um segundo exemplo: um endereço em outro formato
A estrutura de endereços não é a mesma em todo lugar. Um endereço do Reino Unido pode ser resolvido com um condado no lugar de uma região no estilo dos EUA, e um componente como house_number pode estar totalmente ausente no caso de um edifício com nome. Enviar o mesmo tipo de requisição funciona em qualquer país, mas as chaves de componentes que você realmente recebe podem variar, então construa o seu esquema de armazenamento para tolerar a ausência de um componente, em vez de presumir que todo país preenche sempre exatamente o mesmo conjunto.
Um erro comum a evitar
Não deixe fixa no código a suposição de que todo resultado terá house_number, street, city, region e postcode, tratando qualquer endereço sem um deles como erro de parsing. Um endereço perfeitamente válido, principalmente fora de uma malha urbana com numeração de casas, pode legitimamente voltar com alguns campos vazios. Montar uma validação rígida em torno do conjunto completo de componentes vai rejeitar entradas reais de clientes que o endpoint interpretou corretamente.
Guardando também o texto original
Armazene a entrada original em texto livre junto com os componentes interpretados, em vez de descartá-la. Se um componente voltar incompleto ou um cliente precisar corrigir algo depois, ter o texto original à mão torna simples uma nova interpretação ou uma correção manual.
Lidando com interpretações parciais
Nem todo endereço é resolvido com todos os componentes preenchidos. Um endereço rural pode voltar sem house_number, e uma cidade pequena pode voltar sem um valor de região próprio. Trate os campos de componentes ausentes como legitimamente vazios, e não como falha de parsing, e use a string formatada na exibição quando um componente específico que você queria não estiver presente.
Lidando com mais de uma correspondência plausível
Aumentar limit acima de 1 retorna vários resultados candidatos, ordenados pelo quanto cada um corresponde ao texto livre, o que é útil quando você quer mostrar ao cliente uma pequena lista de opções em vez de adotar silenciosamente a primeira correspondência. É um meio-termo razoável entre a análise totalmente automática e um formulário de preenchimento totalmente manual, principalmente para endereços que o seu limite de confiança marcaria como incertos.
Quanto custa
Analisar um campo de texto livre dessa forma custa uma requisição por endereço, o mesmo que qualquer outra consulta de geocodificação direta. Uma tarefa de preenchimento retroativo que limpa uma tabela existente de endereços em texto livre pode percorrer a tabela inteira como uma requisição em lote, uma requisição por linha.
Transformar texto livre em campos estruturados é um efeito colateral natural de geocodificar um endereço, não uma etapa extra. A documentação de geocodificação direta lista todos os componentes que o endpoint pode retornar.