6.2. Geocode
Construindo requisições para a Geocode API
O objetivo desse primeiro endpoint é retornar as coordenadas geográficas a partir de um endereço, completo ou parcial.
Para realizar a requisição para a Geocode API é necessário enviar a requisição usando o método POST para o seguinte endpoint:
Parâmetros da requisição
Parâmetros obrigatórios
É obrigatório informar ao menos um, não é necessário informar todos. No entanto, quanto mais informações forem fornecidas, mais preciso será o resultado.
road- Nome da rua ou parte dele;number- Número do logradouro. NÃO informar os dados do complemento.city- Nome da cidade;state- Estado;district- Nome do bairro;zipcode- CEP.
Parâmetro opcional
type - Limita o tipo da pesquisa. Valores possíveis:ZIPCODE - CEP;STATE - Estado;CITY - Cidade;POI - Pedágios (Até a data deste documento 10/02/2023);DISTRICT - Bairro.
Há o limite de 200 pontos para o envio em uma mesma requisição
Exemplo 1 - Busca da coordenada a partir de endereço
No exemplo a seguir, vamos requisitar as coordenadas para o endereço “Alameda Campinas, 579, São Paulo - SP, CEP 01404-100”. A request encontra-se abaixo:
{
"road": "Alameda Campinas",
"number": 579,
"city": "São Paulo",
"state": "SP",
"zipcode": "01404100"
}
Na resposta, as seguintes informações são retornadas:
found- Quantidade de registros encontrados.results- Resultados encontrados:id- Identificador do processamento;address- Endereço:road- Nome da via;district- Bairro;zipCode- CEP;city- Cidade;state- Estado;mainLocation- Coordenadas geográficas em latitude/longitude;
type- Indica qual o melhor elemento encontrado na base cartográfica para o retorno da coordenada geográfica;score- Pontuação de referência do resultado do processo de geocodificação;label- Endereço completo encontrado utilizado no processo de geocodificação.
A resposta completa pode ser conferida abaixo:
{
"found": 1,
"results": [
{
"id": "2342cca0-f4bf-44fb-89da-fae4632d7ff6",
"address": {
"road": "Alameda Campinas",
"district": "Jardim Paulista",
"zipCode": "01404100",
"city": "São Paulo",
"state": {
"code": "SP",
"name": "São Paulo"
},
"mainLocation": {
"lat": -23.5665,
"lon": -46.65382
}
},
"type": "ZIPCODE",
"score": 66.25707,
"label": "Alameda Campinas, Jardim Paulista, 01404100, São Paulo, São Paulo, SP"
}
]
}
Nota: Quanto maior o score, maior sera a relevância do resultado para o endereço solicitado. Por exemplo, se a request possui todos os elementos de endereço preenchidos e os mesmos foram encontrados na base cartográfica, se espera uma pontuação maior. Se a request possuir somente CEP, a pontuação será menor.
Exemplo 2 - Busca da coordenada a partir do CEP
Nesse exemplo, vamos realizar uma requisição informando apenas o CEP 01014-000:
{
"zipcode": "01014000"
}
A resposta completa pode ser conferida abaixo: