Antes de começar
A geocodificação é o processo de converter um endereço em coordenadas de latitude e longitude usando uma API, enquanto a geocodificação reversa é a conversão de coordenadas geográficas (latitude e longitude) em um endereço legível por humanos por meio de uma API.
Assim, por exemplo, ao converter coordenadas geográficas como latitude 40,758678 e longitude 73,978798, usando a API de geocodificação reversa, você receberá o endereço exato “35 Rockefeller Plaza, New York, NY 10111, USA”.
O DistanceMatrix.ai oferece as duas soluções: API de geocodificação reversa para transformar latitude e longitude em endereço e API de geocodificação direta para converter endereços no mapa em coordenadas geográficas.
Como usar a API de geocodificação reversa
Este serviço é acessível por meio de um HTTP interface. Para solicitações de geocodificação reversa, você precisaria enviar uma consulta como coordenadas (latitude e longitude). A lista abaixo detalha os parâmetros obrigatórios e opcionais para essas solicitações.
Ao consultar, você receberá uma resposta na forma de JSON documento contendo os resultados mais pertinentes. Exemplos dessas solicitações e suas respostas correspondentes são fornecidos na documentação abaixo.
A segurança vem em primeiro lugar. É por isso que o HTTPS é altamente recomendado, especialmente para aplicativos que lidam com dados confidenciais, como a localização do usuário. A criptografia HTTPS fortalece a segurança do seu aplicativo, tornando-o mais resistente à vigilância e à modificação.
Nossa API de geocodificação reversa oferece a flexibilidade de fazer solicitações da maneira que melhor atenda às suas necessidades. As instruções detalhadas acima orientam você sobre como fazer essas solicitações usando o Postman, uma ferramenta de interação de API versátil e fácil de usar.
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 reversa:
latlng: Esse parâmetro obrigatório inclui os valores de latitude e longitude para especificar o local para o qual você deseja obter o endereço. Exemplo:
latlng=37.422387799999996,-122.08418770000002
chave: Uma chave de API exclusiva que autentica o solicitante e permite o cálculo da cota. Essa chave precisa ser incluída em cada solicitação. Anexe sua chave de API à solicitação usando o formato &chave=<your_access_token>.
Siga o
vincular para saber mais sobre a chave, sua finalidade, como obtê-la e os limites da API de geocodificação reversa.
Parâmetros opcionais em uma solicitação de geocodificação reversa:
linguagem: define o idioma dos resultados.
Mostrar a lista de idiomas
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
tipo_resultado: filtra os resultados por tipos de endereço, usando um tubo (|) para vários tipos. Ele atua como um filtro pós-pesquisa, descartando resultados que não correspondem aos tipos especificados. Os tipos suportados incluem:
tipo_localização: Filtra por tipos de localização, novamente usando um tubo (|) para múltiplos. Ele pós-filtra os resultados da pesquisa, mantendo somente aqueles que correspondem aos tipos especificados. Os tipos suportados são:
Se ambos tipo_resultado e tipo_localização filtros são usados, somente os resultados correspondentes a ambos são retornados. Se nenhuma correspondência for encontrada, a API retornará”RESULTADOS_ZERO“.
Respostas de geocodificação reversa
A solicitação fornecida usa a API de geocodificação reversa para converter as coordenadas de latitude e longitude '40.714224, -73.961452', localizadas no Brooklyn, em um endereço legível por humanos e especifica que a resposta deve estar no formato JSON.
Veja como a solicitação é estruturada:
OBTENHA:
https://api.distancematrix.ai/maps/api/geocode/json?latlng=40.714224,-73.961452&key=<your_access_token>
*Nota importante: Ao inserir o latlng parâmetro, certifique-se de que não haja espaço entre os valores de latitude e longitude.
Exemplo de resposta JSON:
BODY
{
"result": [
{
"address_components": [
{
"long_name": "290-306",
"short_name": "290-306",
"types": [
"street_number"
]
},
{
"long_name": "bedford ave",
"short_name": "bedford ave",
"types": [
"route"
]
},
{
"long_name": "brooklyn",
"short_name": "brooklyn",
"types": [
"city_district"
]
},
{
"long_name": "ny",
"short_name": "ny",
"types": [
"state"
]
},
{
"long_name": "11249",
"short_name": "11249",
"types": [
"postcode"
]
},
{
"long_name": "usa",
"short_name": "usa",
"types": [
"country"
]
}
],
"formatted_address": "290-306 Bedford Ave, Brooklyn, NY 11249, USA",
"geometry": {
"location": {
"lat": 40.714224,
"lng": -73.961452
},
"location_type": "APPROXIMATE",
"viewport": {
"northeast": {
"lat": 40.714224,
"lng": -73.961452
},
"southwest": {
"lat": 40.714224,
"lng": -73.961452
}
}
},
"place_id": "",
"plus_code": {},
"types": [
"locality",
"political"
]
}
],
"status": "OK"
}
O”endereço_formatado“Os resultados incluem várias maneiras de nomear geograficamente um local, como endereços, nomes de cidades, estados ou países, retornando qualquer um desses tipos como resultados válidos. Por exemplo, a geocodificação de um ponto em Chicago pode ser representada como endereço, cidade (Chicago), estado (Illinois) ou país (EUA). O geocodificador reverso combina entidades políticas, endereços e códigos postais.
* Nota importante: A geocodificação reversa estima a localização endereçável mais próxima dentro de uma faixa de tolerância específica, retornando zero resultados se nenhuma correspondência próxima for encontrada.
Observe que a resposta JSON tem dois elementos principais:
“status”: esse elemento fornece metadados sobre a solicitação. Consulte o
Códigos de status abaixo para obter mais detalhes.
“resultado”: Isso inclui uma matriz com detalhes de endereço geocodificados e informações de geometria.
Lembre-se de que, para extrair valores específicos desses resultados, geralmente é necessário analisar o JSON, o que, por sua vez, é um processo simples.
Códigos de status
Na resposta de geocodificação, o”statusO campo “mostra o status da solicitação e pode incluir detalhes de depuração. Os valores possíveis são:
“ESTÁ BEM”: Sem erros; o endereço foi processado e o (s) código (s) geográfico (s) retornado (s).
“RESULTADOS_ZERO”: A geocodificação foi bem-sucedida, mas nenhum resultado foi encontrado, possivelmente devido a um endereço inexistente.
“ACIMA DO LIMITE_DIÁRIO_DE_LIMITE”: pode significar uma chave de API ausente/inválida, nenhuma cobrança ativada ou um limite de uso excedido.
“EXCEDA_LIMITE_CONSULTA”: indica o uso excessivo da cota.
“SOLICITAÇÃO_NEGADA”: Sua solicitação foi negada.
“SOLICITAÇÃO_INVÁLIDA”: normalmente significa falta de detalhes da consulta (endereço, componentes ou latlng).
“ERRO_DESCONHECIDO”: um erro no servidor impediu o processamento. Uma nova tentativa pode ser bem-sucedida.
Mensagens de erro
Se o código de status do geocodificador for algo diferente de”OK,” um”mensagem_de_erro” o campo” pode aparecer na resposta. Esse campo fornece motivos detalhados para o código de status específico.
*Nota importante: O”mensagem_de_erro” o campo” nem sempre está incluído e seu conteúdo pode variar.
Resultados
Quando o geocodificador produz resultados, eles são colocados em uma matriz de resultados no formato JSON. Se nenhum resultado for encontrado, como com um endereço inexistente, a matriz será retornada vazia.
Os principais campos em um resultado típico 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”.
Tenha em mente esses pontos sobre o endereço_componentes [] matriz em resultados de geocodificação:
A matriz pode incluir mais elementos do que endereço_formatado.
Nem sempre abrange todas as entidades políticas de um endereço, apenas aquelas no endereço_formatado. Use geocodificação reversa com latitude/longitude para obter uma lista abrangente.
O formato da resposta, incluindo o número e os tipos de componentes do endereço, pode variar com cada solicitação e ao longo do tempo para o mesmo endereço. Os componentes podem mudar de posição, mudar de tipo ou estar ausentes nas respostas subsequentes.
Para usar efetivamente a resposta de geocodificação, você precisa analisar a matriz de componentes e selecionar valores conforme necessário.
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: Fornece os principais detalhes da localização:
partial_match: indica uma correspondência não exata, na qual somente parte do endereço solicitado pode ser correspondida. Isso é comum em endereços de rua inexistentes na localidade solicitada ou quando um endereço corresponde a vários locais. Por exemplo, uma solicitação com um endereço com um pequeno erro ortográfico pode retornar um endereço próximo, escrito corretamente, como uma correspondência parcial.
Tipos de endereço e tipos de componentes de endereço
O tipos [] a matriz nos resultados da geocodificação indica o tipo de endereço, que pode incluir:
endereço_rua: Um endereço específico.
rota: Uma rota nomeada como “US 101”.
interseção: Uma grande encruzilhada de duas estradas.
político: Uma entidade política, geralmente uma área da administração civil.
país: A entidade política nacional, geralmente do tipo de nível superior.
nível_da_área administrativa_2: Uma entidade civil secundária, como condados nos EUA.
nível_do_área administrativa 3 para nível_da_área administrativa_5: Divisões civis de ordem inferior.
Outros tipos compatíveis incluem:
área_coloquial: Um nome alternativo para um lugar.
localidade: Uma cidade ou vila incorporada.
sublocalidade (e níveis 1-5): Uma entidade civil dentro de uma localidade.
vizinhança: Um bairro específico.
premissa: Um edifício ou complexo nomeado.
subpremissa: Uma unidade dentro de uma premissa maior.
código_postal: O código postal.
característica_natural: Marcos naturais notáveis.
parque: Um parque com nome.
ponto_de_interesse: Entidades locais importantes, como pontos turísticos.
Uma lista de tipos vazia significa que não há tipos conhecidos para esse componente de endereço. Os tipos adicionais incluem:
estabelecimento: Lugares não classificados.
estacionamento: Áreas de estacionamento.
caixa postal: Caixas postais específicas.
cidade_postal: Áreas geográficas usadas para endereços de correspondência.
espaço: Salas específicas em um edifício.
número_da_rua: Número exato da rua.
estação de ônibus, estação de trem, estação de trânsito: Paradas de trânsito.
PERGUNTAS FREQUENTES
O que você pode fazer com a API de geocodificação reversa?
As empresas que lidam com geocodificação usam amplamente as APIs de geocodificação direta e de geocodificação reversa em software e aplicativos para localizar lojas, veículos e clientes, auxiliando no gerenciamento de transporte e no rastreamento de movimentos.
Mais do que apenas identificação/posicionamento de endereços, a geocodificação reversa é uma ferramenta versátil para mapeamento de localização, planejamento de rotas e análise de dados. Essa tecnologia pode ser benéfica para empresas de logística que precisam de detalhes precisos de localização. Há mais exemplos reais de API de geocodificação reversa em ação em nosso local na rede Internet.
Por que usar a API de geocodificação reversa?
A API de geocodificação reversa do DistanceMatrix.ai fornece dados de localização precisos de 99% do mundo em uma variedade de formatos. Para que você possa obter o endereço correto em segundos de qualquer lugar. É isso que coloca nossa ferramenta em alta demanda em vários setores. Além disso, devido à sua alta precisão, ele compete com os principais fornecedores da área. Outra coisa a se lembrar é que o processo de mudança de qualquer serviço secundário para nossa API é perfeito e sem problemas.
