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: