Antes de começar
A geocodificação converte um endereço em coordenadas geográficas que são úteis para colocar marcadores em mapas ou localizar endereços. Por exemplo, converter “Rockefeller Center, NY, EUA” resulta em latitude 40,7587402 e longitude 73,9786736.
Da mesma forma, a geocodificação reversa converte as coordenadas geográficas em um endereço legível.
Como usar a API de geocodificação
O serviço de geocodificação Distancematrix.ai está disponível por meio de um Interface HTTP para uma variedade de aplicativos, incluindo navegadores da Web, Postman e integração direta de aplicativos. Os usuários podem enviar solicitações de geocodificação padrão com um endereço ou solicitações de geocodificação reversa com coordenadas (latitude e longitude). O serviço permite que você configure ainda mais as solicitações especificando parâmetros adicionais com opções de personalização.
Depois de enviar sua solicitação, o serviço responde com um Formatado em JSON documento contendo os resultados mais relevantes, idealmente estruturado para uso direto e integração com várias plataformas — de navegadores da Web a diferentes tipos de aplicativos.
A segurança é importante e o HTTPS é recomendado sempre que possível, especialmente para aplicativos que incluem dados confidenciais do usuário, como a localização do usuário, nas solicitações. O uso da criptografia HTTPS torna seu aplicativo mais seguro e mais resistente a espionagem ou adulteração.
Abaixo, você encontrará exemplos que mostram como fazer solicitações e interpretar respostas, ilustrando o processo para diferentes plataformas e métodos, incluindo navegadores, Postman e codificação baseada em aplicativos.
Como usar a API de geocodificação por meio do Postman
Nossa API é um serviço HTTP versátil, adequado para vários casos de uso e cenários de integração. Ele pode ser usado de qualquer forma que atenda às suas necessidades, incluindo solicitações diretas do navegador, codificação em diferentes linguagens de programação ou integração com aplicativos e sistemas.
Uma das maneiras mais fáceis e eficientes de começar a interagir e integrar nossa API em seus projetos é usar
Carteiro, conhecida por sua interface amigável e recursos poderosos.
Veja como fazer isso:
Para começar a usar o Postman, instale-o em seu computador ou acesse uma versão web do navegador.
Importe nossa coleção de API pré-configurada:
Ao importar, o Postman adicionará automaticamente a coleção ao seu espaço de trabalho.
Para usuários da versão on-line do Postman, você pode abrir diretamente o link da coleção e criar um fork. Faça isso clicando nos três pontos ao lado do nome da coleção.
Configure seu ambiente no Postman, vá para a seção Variáveis e adicione seu token de autenticação no campo “Token de autorização da API”.
Não se esqueça de salvar essas alterações.
Faça sua primeira solicitação: selecione um endpoint de nossa coleção, configure seus parâmetros de solicitação e clique em enviar para ver a resposta.
-min.webp)
Observe que você pode obter seu token individual no painel de administração. Leia como fazer isso em
o artigo.
-min.webp)
Não se esqueça de salvar essas alterações.
-min.webp)
Em nossa coleção Postman, você encontrará todos os endpoints, tipos de solicitações e parâmetros disponíveis. Em geral, recomendamos o uso de solicitações síncronas. No entanto, para situações em que você precisa processar solicitações em massa com um grande número de locais de uma só vez, as solicitações assíncronas também estão disponíveis e podem ser eficazes. Para trabalhar com eles, clique em Distancematrix Accurate → Solicitações em massa → Enviar um trabalho → Corpo, comece a trabalhar!
-min.webp)
Na coleção Postman, você encontra todos os parâmetros necessários para configurar suas solicitações. Se você tiver alguma dúvida, não hesite em
entre em contato conosco.
Quando estiver confortável com o básico, você poderá explorar os recursos mais avançados da nossa API. Nossa documentação detalhada abaixo o guiará pelas funcionalidades específicas de nossa API.
Parâmetros necessários em uma solicitação de geocodificação:
endereço: Aqui você precisa mencionar o endereço para geocodificação. Ele deve ser formatado de acordo com os padrões nacionais de serviço postal do país relevante, excluindo elementos como nomes comerciais ou números de unidades/ternos/andar. Use espaços (URL com escape) como %20) para separar elementos de endereço, por exemplo:
abordar=100% 20Rainhas% 20estacionar% 20Toronto%20 EM onde “100 Queens Park, Toronto, ON” é o endereço do Museu Real de Ontário
chave: esse parâmetro exige seu token de autorização de API exclusivo, necessário para verificar a identidade e as permissões do cliente que está fazendo a solicitação, garantindo acesso seguro e monitoramento preciso de sua cota de uso.
Mais detalhes sobre a chave, sua finalidade, o processo de obtenção e os limites da API de geocodificação aplicados à chave podem ser encontrados no
vincular.
Respostas de geocodificação
Nossa API Geo converte endereços em coordenadas (latitude e longitude). Ele retorna respostas no formato especificado na solicitação de URL, como JSON. No exemplo abaixo, uma solicitação de “1600 Amphitheatre Parkway, Mountain View, CA” usa o formato JSON para sua resposta, conforme indicado pelo sinalizador de saída JSON na solicitação:
OBTENHA:
https://api-v2.distancematrix.ai/maps/api/geocode/json?address=1600+Amphitheatre+Parkway,+Mountain+View,+CA&key=<your_access_token>
O exemplo de resposta JSON:
CORPO
{
"result": [
{
"address_components": [
{
"long_name": "United States",
"short_name": "US",
"types": [
"country",
"political"
]
},
{
"long_name": "Mountain View",
"short_name": "Mountain View",
"types": [
"administrative_area_level_3",
"political"
]
},
{
"long_name": "94043",
"short_name": "94043",
"types": [
"postal_code"
]
},
{
"long_name": "1600",
"short_name": "1600",
"types": [
"street_number"
]
},
{
"long_name": "Amphitheatre Parkway",
"short_name": "Amphitheatre Parkway",
"types": [
"route"
]
},
{
"long_name": "Google Headquarters",
"short_name": "Google Headquarters",
"types": [
"name"
]
},
{
"long_name": "CA",
"short_name": "CA",
"types": [
"state",
"administrative_area_level_1",
"political"
]
}
],
"formatted_address": "1600 Amphitheatre Parkway, Mountain View 94043, United States",
"geometry": {
"location": {
"lat": 37.4217636,
"lng": -122.084614
},
"location_type": "APPROXIMATE",
"viewport": {
"northeast": {
"lat": 37.4217636,
"lng": -122.084614
},
"southwest": {
"lat": 37.4217636,
"lng": -122.084614
}
}
},
"place_id": "2192620021",
"plus_code": {},
"types": [
"street_address"
]
}
],
"status": "OK"
}
Observe que a resposta JSON contém dois elementos raiz:
“resultados” contém uma matriz de informações de endereço geocodificadas e informações de geometria.
Geralmente, somente uma entrada na matriz “resultados” é retornada para pesquisas de endereço, embora o geocodificador possa retornar vários resultados quando as consultas de endereço são ambíguas.
Observe que esses resultados geralmente precisam ser analisados se você quiser extrair valores dos resultados.
Códigos de status
O campo “status” na resposta de Geocodificação fornece o status da solicitação e as informações de depuração para ajudar a diagnosticar problemas. Os valores de status possíveis incluem:
“OK”: A solicitação foi bem-sucedida e os dados de geocodificação foram retornados.
“ZERO_RESULTS”: A geocodificação foi bem-sucedida, mas não produziu resultados, possivelmente devido a um endereço inexistente.
“OVER_DAILY_LIMIT”: isso pode significar uma chave de API inválida ou ausente, nenhuma cobrança na conta ou um limite de uso excedido.
“OVER_QUERY_LIMIT”: Seu uso excedeu a cota.
“REQUEST_DENIED”: A solicitação foi rejeitada.
“INVALID_REQUEST”: geralmente significa uma consulta ausente (endereço, componentes ou latlng).
“UNKNOWN_ERROR”: Ocorreu um erro no servidor; uma nova tentativa pode ser bem-sucedida.
Mensagens de erro
Se o código de status retornado pelo Geocodificador não for “OK”, um campo opcional “error_message” poderá aparecer na resposta. Esse campo fornece mais detalhes sobre o motivo pelo qual esse código de status específico foi retornado.
*Nota: O campo “error_message” pode nem sempre estar disponível e seu conteúdo pode mudar.
Resultados
Quando o geocodificador retorna resultados, eles são colocados em uma matriz de resultados no formato JSON. Se nenhum resultado for encontrado (como para um endereço inexistente), a matriz ficará vazia.
Os campos típicos em um resultado incluem:
matriz de tipos []: Especifica o tipo de resultado, com tags como “localidade” para cidades ou “político” para entidades políticas. Por exemplo, “Chicago” pode ser marcado como ambos.
endereço_formatado: Uma sequência de endereços legível por humanos, geralmente semelhante a um endereço postal. No entanto, em alguns lugares, como no Reino Unido, os endereços postais verdadeiros podem não ser distribuíveis. Esse endereço é composto por componentes como número da rua, rota, cidade e estado. Em vez de analisar esse endereço, use os componentes de endereço separados que também são fornecidos na resposta.
endereço_componentes []: Uma matriz dos componentes do endereço.
Cada componente de endereço normalmente contém os seguintes campos:
tipos []: Especifica o tipo de cada componente de endereço.
nome_longo: Fornece a descrição em texto completo ou o nome do componente de endereço, conforme fornecido pelo Geocodificador.
nome_curto: Aplica-se ao nome do componente de endereço com uma versão abreviada disponível do nome do componente de endereço. Vamos pegar o estado do Alasca como exemplo: a nome_curto de “AK”, que é sua abreviatura postal de 2 letras e um nome_longo de “Alaska”.
Aqui estão mais alguns fatos sobre o endereço_componentes [] matriz para ter em mente:
O endereço_componentes [] Uma matriz em uma resposta de geocodificação pode ter mais elementos do que o endereço_formatado.
Nem sempre inclui todas as entidades políticas que contêm o endereço, exceto aquelas no endereço_formatado. Para obter uma lista completa, use a geocodificação reversa com a latitude/longitude do endereço.
O formato da resposta, incluindo o número e os tipos de componentes do endereço, pode variar entre solicitações e ao longo do tempo para o mesmo endereço. Os componentes podem mudar de posição, tipo ou podem ser omitidos nas respostas subsequentes.
Para usar efetivamente a resposta do geocodificador, você precisa analisar a matriz de componentes:
postcode_localities []: Essa matriz lista todas as localidades dentro de um código postal. Ele aparece apenas para códigos postais que abrangem várias localidades.
geometria: Inclui informações importantes, como:
partial_match: indica uma correspondência não exata para a solicitação, útil para identificar possíveis problemas, como erros ortográficos ou endereços incompletos. As correspondências parciais geralmente ocorrem para endereços inexistentes ou quando um endereço corresponde a vários locais na mesma área. Por exemplo, um endereço com ortografia incorreta (que seja “21 Henry St, Bristol, Reino Unido”) pode retornar uma rua com som semelhante como uma correspondência parcial (“Henry Street” e “Henrietta Street”).
Tipos de endereço e tipos de componentes de endereço
O tipos [] A matriz no resultado da geocodificação especifica o tipo de endereço, como endereço, país ou entidade política. Há também um tipos [] matriz dentro endereço_componentes [] que especifica o tipo de cada parte do endereço, como número da rua ou país. Os endereços podem ter vários tipos, funcionando como 'tags'. Por exemplo, as cidades geralmente têm tags como “política” e “localidade”.
O geocodificador suporta e retorna vários tipos em matrizes de tipo de endereço e tipo de componente:
endereço_rua: Um endereço preciso.
rota: Uma rota nomeada como “US 101".
interseção: Um grande cruzamento de duas estradas principais.
político: Uma entidade política, geralmente indicando um polígono da administração civil.
país: A entidade política nacional, geralmente o tipo de ordem mais alta.
nível_da_área administrativa 1: Uma entidade civil primária abaixo do nível do país, como estados nos EUA. Eles geralmente se alinham às subdivisões da ISO 3166-2.
nível_da_área administrativa_2: Uma entidade civil secundária, como condados nos EUA.
nível_área_administrativo_3/nível_área_administrativa_4/área_nível_administrativo_5: Entidades civis de ordem inferior, representando divisões menores.
área_coloquial: Um nome alternativo comumente usado para a entidade.
localidade: Uma cidade ou vila incorporada.
sublocalidade (e níveis 1-5: sublocality_level_1 a sublocality_level_5): entidades de menor ordem dentro de uma localidade. Quanto menor a área geográfica, maiores os números.
vizinhança: Um bairro nomeado.
premissa: Um local nomeado, normalmente um edifício ou complexo.
subpremissa: Parte de uma premissa maior, como um prédio dentro de um complexo.
código postal: Um código postal usado no país.
característica_natural: Uma característica natural significativa.
parque: Um parque com nome.
ponto de interesse: Uma entidade proeminente como “Empire State Building” ou “Torre Eiffel”.
Se a lista de tipos de um componente de endereço estiver vazia, isso significa que nenhum tipo específico é conhecido para esse componente, como um 'Lieu-dit' na França. Além disso, os componentes do endereço podem incluir:
piso: O número do andar de um prédio.
estabelecimento: Um lugar ainda não categorizado.
ponto de interesse: Um ponto de interesse nomeado.
estacionamento: Um estacionamento ou estrutura.
caixa postal: Uma caixa postal específica.
cidade_postal: Um agrupamento de áreas geográficas usado para endereços de correspondência em alguns países.
sala: Um quarto em um prédio.
número_da_rua: O número exato da rua.
estação_de_ônibus, estação_de_trem, estação_de_trânsito: Localizações de paradas de ônibus, trem ou transporte público.
PERGUNTAS FREQUENTES
O que diferencia essa API de outras APIs de geocodificação?
A API de geocodificação Distancematrix.ai tem vários fatores que a diferenciam de outras APIs de geocodificação:
Alta precisão: A API de geocodificação do Distancematrix.ai usa algoritmos e fontes de dados avançados para fornecer resultados de geocodificação precisos e confiáveis. A API também tem uma alta taxa de sucesso na correspondência de endereços, o que significa que ela pode lidar com uma grande variedade de formatos e variações de endereço.
Cobertura global: a API abrange uma ampla variedade de países e regiões, incluindo lugares de difícil acesso, como áreas rurais, ilhas e países em desenvolvimento. Isso significa que os usuários podem confiar na API para fornecer resultados precisos, independentemente da origem dos dados.
Velocidade e escalabilidade: A API foi projetada para lidar com grandes volumes de solicitações de geocodificação de forma rápida e eficiente.
Econômico: a API oferece um modelo de preços simples e transparente, sem taxas ocultas ou custos iniciais. A API oferece um plano gratuito e um plano de crescimento com modelo de preços pré-pago.
Posso usar essa API como um endereço de conversão para uma API de longa duração?
Sim, você pode usar a API de geocodificação Distancematrix.ai para converter endereços em coordenadas de latitude-longitude. Na verdade, essa é uma das principais funções de um endereço para uma API duradoura como esta.
Para usar a API para geocodificação, você enviaria uma solicitação à API com um parâmetro de endereço, e a API responderia com as coordenadas lat-long correspondentes para esse endereço.
A API de geocodificação Distancematrix.ai foi projetada como uma API de obtenção de latitude e longitude do endereço que é fácil de usar. Ele pode ser integrado a uma ampla variedade de aplicativos e plataformas. A API oferece suporte a uma variedade de linguagens e estruturas de programação, incluindo Python, JavaScript e PHP, entre outras.
Posso usar essa API como um conversor de API de latitude e longitude para endereços legíveis por humanos?
Sim, você pode usar a API de geocodificação Distancematrix.ai para converter coordenadas de latitude-longitude (lat-long) em endereços legíveis por humanos. Esse processo também é conhecido como geocodificação reversa e os desenvolvedores geralmente pesquisam por uma API de latitude e longitude ou por coordenadas de agentes da API de endereço.
Para usar a API para geocodificação reversa, você enviaria uma solicitação à API com os parâmetros de latitude e longitude, e a API responderia com o endereço correspondente legível por humanos para essas coordenadas.
Se você tiver alguma dúvida ou precisar de mais ajuda para usar a API para suas necessidades de geocodificação reversa, a equipe do Distancematrix.ai fornece documentação detalhada e suporte ao cliente para ajudá-lo a começar.
O que você pode fazer com a API de geocodificação?
Muitas empresas e empreendimentos usam software e aplicativos para localizar lojas, armazéns, veículos e clientes, para controlar o transporte e os movimentos que lidam com a geocodificação. Mas, atualmente, sua definição não se limita às pesquisas de endereços. É uma ferramenta bastante universal que permite aplicá-la ao mercado geral, desde a localização precisa e o mapeamento de rotas até a análise de dados do cliente e o reconhecimento de padrões geográficos.
Essa solução é útil, por exemplo, entre motoristas de táxi, caso não tenham dados precisos sobre os endereços de destino dos clientes. Além disso, esse serviço é conveniente para entregadores de comida em suas rotinas diárias. Você pode ler outros exemplos de API de geocodificação bem-sucedidos usando nosso local na rede Internet.
Por que usar a API de geocodificação?
As APIs Distancematrix.ai oferecem a melhor precisão da categoria que rivaliza com os gigantes do setor, mas a um preço muito mais acessível, maior escalabilidade e uma equipe de suporte humano amigável e real, sempre disponível para ajudá-lo com suas dúvidas. Um benefício adicional é a facilidade de transição de outros fornecedores, garantindo um processo de troca tranquilo.
Além disso, o Distancematrix.ai permite que os usuários testem o serviço sem a necessidade de anexar um cartão de crédito/débito antes de tomar uma decisão final. Isso é feito para que os usuários possam verificar a qualidade e o valor dos resultados obtidos. Sinta-se à vontade para tentar garantir que o Distancematrix.ai seja uma solução de alta qualidade, rápida e econômica. Além disso, mesmo durante o período de teste, os usuários podem entrar em contato com o suporte ao vivo disponível para qualquer dúvida.
