API de geocodificação precisa | Documentação e exemplos

Guia do desenvolvedor de geocodificação

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ê encontra exemplos e instruções sobre nossas solicitações de API HTTPS, adequadas para uma ampla variedade de abordagens, seja por meio de um navegador da Web, de qualquer plataforma ou aplicativo de sua escolha ou de sistemas como o Postman. Essa orientação inclui descrições abrangentes sobre como formar solicitações e interpretar respostas em diferentes ambientes.

Como usar a API de geocodificação por meio do Postman

Bem-vindo à nossa documentação da API de geocodificação! 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.
Observe que você pode obter seu token individual no painel de administração. Leia como fazer isso em o artigo.
Não se esqueça de salvar essas alterações.
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.

Guia do desenvolvedor de geocodificação direta

Abaixo, você pode ler como obter latitude e longitude a partir da API de endereço. Você descobrirá quais parâmetros obrigatórios e opcionais você deve usar e qual resposta de geocodificação você obtém. Além disso, mostraremos um exemplo de resposta JSON com base no sinalizador de saída.

Formato de solicitação de API

A solicitação da API de geocodificação foi projetada especificamente para se assemelhar ao formato de solicitação comumente usado para facilitar a transição de serviços alternativos.
Uma solicitação da API de geocodificação tem a seguinte aparência:
OBTENHA:
  • URL base: No serviço de geocodificação DistanceMatrix.ai, as solicitações são estruturadas como URLs com parâmetros obrigatórios e opcionais, separados pelo caractere comercial (&). Use criptografia HTTPS para segurança: https://.
  • Domínio: O domínio preciso da API DistanceMatrix.ai é api.distancematrix.ai
  • URL da solicitação: Para geocodificação, é /mapas/api/geocodificar/json.
  • Parâmetros: os parâmetros são informações adicionais que são adicionadas ao URL da solicitação para fornecer detalhes específicos à API. Esses parâmetros podem ser categorizados em dois tipos: obrigatórios e opcionais.
    • Parâmetros necessários são obrigatórios para que a API processe a solicitação com êxito, pois fornecem informações essenciais sem as quais a API não pode realizar a operação pretendida. Assim, em uma solicitação da API de geocodificação, o endereço para o qual você precisa das coordenadas geográficas é um parâmetro obrigatório. Sem esse endereço, a API não saberia em qual local geocodificar. Por exemplo, para um local de interesse como a Casa de Anne Frank ? endereço=Westermarkt+20, +1016+GV+Amsterdã, +Holanda especifica o endereço para a geocodificação padrão.
    • Parâmetros opcionais não são obrigatórios, mas podem ser incluídos para refinar ou personalizar a resposta da API. Os parâmetros opcionais podem fornecer controle adicional sobre o formato da resposta da API, o idioma no qual os dados são retornados ou outras especificações relevantes à solicitação. Por exemplo, em uma solicitação de geocodificação, um parâmetro opcional pode ser o idioma no qual você deseja que os resultados sejam retornados, como &linguagem= reino unido para especificar uma preferência de idioma. A inclusão desse parâmetro não é necessária para a função de geocodificação em si, mas pode melhorar a usabilidade dos dados.
  • Token de autorização: Inclua seu token de acesso exclusivo como &chave=<your_access_token> para autenticar a solicitação.
O exemplo de resposta JSON:
https://api.distancematrix.ai/maps/api/geocode/json?address=Westermarkt%2020,%201016%20GV%20Amsterdam,%20Netherlands&key=<your_access_token>
Copiado!
A próxima seção da página detalha a solicitação de geocodificação.

Parâmetros opcionais em uma solicitação de geocodificação:

linguagem — O idioma no qual retornar os resultados.
  • Veja a lista de idiomas compatíveis.
  • O geocodificador assume como padrão o idioma especificado no cabeçalho Accept-Language ou o idioma nativo do domínio da solicitação se nenhum idioma for fornecido.
  • Para garantir a legibilidade, o geocodificador retorna endereços no idioma local, usando transliteração quando necessário, com base no idioma preferido do usuário. Todos os componentes do endereço são entregues no mesmo idioma, determinado pelo idioma do primeiro componente.
  • Se um nome de endereço não estiver disponível no idioma preferido, o geocodificador seleciona a correspondência mais próxima disponível.
  • O idioma preferido influencia sutilmente a seleção e a ordem dos resultados, pois o geocodificador interpreta abreviações e sinônimos de forma diferente entre os idiomas. Por exemplo, “utca” e “tér” em húngaro correspondem a “rua” e “praça”.
Mostrar idiomas
Ocultar idiomas
Código do idioma
Idioma
Código do idioma
Idioma
de
afrikaans
sim
japonesa
sq
albanesa
kn
canarês
sou
Amárico
kk
cazaque
sou
árabe
quilômetro
Khmer
por que
armênio
ko
coreana
az
azerbaijano
chave
Quirguiz
eu
Basco
lo
laosiano
ser
Bielorrusso
lv
letão
bn
bengali
lt
lituano
b)
bósnio
mk
Macedônio
por
búlgaro
ms
malaio
meu
birmanês
ml
Malaiala
ca
catalão
sr.
Marathi
zh
chinês
homem
mongol
zh-CN
Chinês (simplificado)
um
Nepalês
Zh-HK
Chinês (Hong Kong)
não
norueguês
Zh-TW
Chinês (tradicional)
pl
polonês
hr
croata
pt
portuguesa
cs
Tcheco
pt-BR
Português (Brasil)
da
dinamarquês
pt-PT
Português (Portugal)
nl
holandês
pa
punjabi
en
Inglês
ou
romeno
pt-BR
Inglês (australiano)
ru
russa
pt-BR
Inglês (Grã-Bretanha)
sr.
sérvio
et
estoniano
é
Cingalês
fa
Farsi
perguntar
eslovaca
se
finlandês
sl
esloveno
arquivo
Filipino
Sim
espanhol
fr
francês
es-419
Espanhol (América Latina)
fr-CA
Francês (Canadá)
sw
suaíli
gl
galego
sv
sueca
ka
georgiano
chá
tâmil
de
alemã
o
Télugo
el
grego
o
tailandês
arma
Gujarati
tentar
turca
é
hebreu
reino unido
ucraniano
oi
hindi
ur
urdu
hu
húngaro
uz
Uzbeque
é
islandês
vi
vietnamita
id
indonésio
zu
zulu
isso
italiano


região — especificado como um valor de ccTLD (“domínio de nível superior”) de dois caracteres, esse parâmetro influencia, mas não limita estritamente, os resultados do geocodificador.

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.distancematrix.ai/maps/api/geocode/json?address=1600+Amphitheatre+Parkway,+Mountain+View,+CA&key=<your_access_token>
Copiado!
O exemplo de resposta JSON:
CORPO
{
    "result": [
        {
            "address_components": [
                {
                    "long_name": "1600",
                    "short_name": "1600",
                    "types": [
                        "street_number"
                    ]
                },
                {
                    "long_name": "amphitheatre parkway",
                    "short_name": "amphitheatre parkway",
                    "types": [
                        "route"
                    ]
                },
                {
                    "long_name": "mountain view",
                    "short_name": "mountain view",
                    "types": [
                        "locality"
                    ]
                },
                {
                    "long_name": "ca",
                    "short_name": "ca",
                    "types": [
                        "state"
                    ]
                }
            ],
            "formatted_address": "1600 Amphitheatre Parkway, Mountain View, CA",
            "geometry": {
                "location": {
                    "lat": 37.422387799999996,
                    "lng": -122.08418770000002
                },
                "location_type": "APPROXIMATE",
                "viewport": {
                    "northeast": {
                        "lat": 37.422387799999996,
                        "lng": -122.08418770000002
                    },
                    "southwest": {
                        "lat": 37.422387799999996,
                        "lng": -122.08418770000002
                    }
                }
            },
            "place_id": "",
            "plus_code": {
                "compound_code": "CWC8+R9 Mountain View, California, United States",
                "global_code": "849VCWC8+R9"
            },
            "types": [
                "locality",
                "political"
            ]
        }
    ],
    "status": "OK"
}
Copiado!
Observe que a resposta JSON contém dois elementos raiz:
“status” contém metadados sobre a solicitação. Veja Códigos de status abaixo.
“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 negada.
“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:
  • localização: contém latitude e longitude. Normalmente, é crucial para pesquisas de endereço padrão.
  • location_type: fornece detalhes adicionais sobre a localização, com valores como:
    • “TELHADO”: Um código geográfico preciso com precisão de endereço de rua.
    • “INTERVALO_INTERPOLADO”: Um resultado aproximado entre dois pontos precisos, geralmente usado quando os dados do telhado não estão disponíveis.
    • “CENTRO_GEOMÉTRICO”: O centro geométrico de uma linha ou área.
    • “APROXIMADO”: Uma localização aproximada.
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.
aeroporto: Um aeroporto.
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.

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.
Observe que você pode obter seu token individual no painel de administração. Leia como fazer isso em o artigo.
Não se esqueça de salvar essas alterações.
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!
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.

Guia do desenvolvedor de geocodificação direta

Abaixo, você pode ler como obter latitude e longitude a partir da API de endereço. Você descobrirá quais parâmetros obrigatórios e opcionais você deve usar e qual resposta de geocodificação você obtém. Além disso, mostraremos um exemplo de resposta JSON com base no sinalizador de saída.

Formato de solicitação de API

A solicitação da API de geocodificação foi projetada especificamente para se assemelhar ao formato de solicitação comumente usado para facilitar a transição de serviços alternativos.
Uma solicitação da API de geocodificação tem a seguinte aparência:
OBTENHA:
  • URL base: No serviço de geocodificação DistanceMatrix.ai, as solicitações são estruturadas como URLs com parâmetros obrigatórios e opcionais, separados pelo caractere comercial (&). Use criptografia HTTPS para segurança: https://.
  • Domínio: O domínio preciso da API DistanceMatrix.ai é api-v2.distancematrix.ai
  • URL da solicitação: Para geocodificação, é /mapas/api/geocodificar/json.
  • Parâmetros: os parâmetros são informações adicionais que são adicionadas ao URL da solicitação para fornecer detalhes específicos à API. Esses parâmetros podem ser categorizados em dois tipos: obrigatórios e opcionais.
    • Parâmetros necessários são obrigatórios para que a API processe a solicitação com êxito, pois fornecem informações essenciais sem as quais a API não pode realizar a operação pretendida. Assim, em uma solicitação da API de geocodificação, o endereço para o qual você precisa das coordenadas geográficas é um parâmetro obrigatório. Sem esse endereço, a API não saberia em qual local geocodificar. Por exemplo, para um local de interesse como a Casa de Anne Frank ? endereço=Westermarkt+20, +1016+GV+Amsterdã, +Holanda especifica o endereço para a geocodificação padrão.
    • Parâmetros opcionais não são obrigatórios, mas podem ser incluídos para refinar ou personalizar a resposta da API. Os parâmetros opcionais podem fornecer controle adicional sobre o formato da resposta da API, o idioma no qual os dados são retornados ou outras especificações relevantes à solicitação. Por exemplo, em uma solicitação de geocodificação, um parâmetro opcional pode ser o idioma no qual você deseja que os resultados sejam retornados, como &linguagem= reino unido para especificar uma preferência de idioma. A inclusão desse parâmetro não é necessária para a função de geocodificação em si, mas pode melhorar a usabilidade dos dados.
  • Token de autorização: Inclua seu token de acesso exclusivo como &chave=<your_access_token> para autenticar a solicitação.
Um exemplo de uma solicitação completa pode ter a seguinte aparência:
https://api-v2.distancematrix.ai/maps/api/geocode/json?address=Westermarkt%2020,%201016%20GV%20Amsterdam,%20Netherlands&key=<your_access_token>
Copiado!

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>
Copiado!
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"
}
Copiado!
Observe que a resposta JSON contém dois elementos raiz:
“status” contém metadados sobre a solicitação. Veja Códigos de status abaixo.
“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:
  • localização: contém latitude e longitude. Normalmente, é crucial para pesquisas de endereço padrão.
  • location_type: fornece detalhes adicionais sobre a localização, com valores como:
    • “TELHADO”: Um código geográfico preciso com precisão de endereço de rua.
    • “INTERVALO_INTERPOLADO”: Um resultado aproximado entre dois pontos precisos, geralmente usado quando os dados do telhado não estão disponíveis.
    • “CENTRO_GEOMÉTRICO”: O centro geométrico de uma linha ou área.
    • “APROXIMADO”: Uma localização aproximada.
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.
aeroporto: Um aeroporto.
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.

Nenhum pré-pagamento é necessário.
Comece gratuitamente e tenha acesso instantâneo a todos os produtos e recursos do Distancematrix.ai