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: