O objetivo desse primeiro endpoint é retornar as coordenadas geográficas a partir de um endereço completo ou parcial.  

• Lista de parâmetros
• Exemplo 1 – Busca de coordenadas a partir de endereço
• Exemplo 2 – Busca de coordenadas a partir do CEP

Para realizar a requisição para a Geocode API é necessário enviar a requisição usando o método POST para o seguinte endpoint: 

• https://api.maplink.global/geocode/v2/geocode – POST

A Geocode API foi atualizada para a V2. O endpoint https://api.maplink.global/geocode/v1/geocode ainda continuará funcionando, mas é recomendável utilizar o novo endpoint para maior assertividade de resultados e porque novos recursos serão exclusivos para a nova versão.

Lista de parâmetros

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;
• country – País;
• district – Nome do bairro;
• zipcode – CEP;
• label – Endereço completo. Recomenda-se montar o texto na ordem “Nome da rua, número, bairro, cidade, estado”.

Nota: Há o limite de 200 pontos para o envio em uma mesma requisição.

Parâmetros opcionais

• mainLocation – Objeto com dois parâmetros para limitar a área de busca do endereço:
  • center – Objeto com as coordenadas de referência para a busca de resultados. As coordenadas podem ser informadas nos seguintes formatos:
    • Objeto com as propriedades lat e lon que representam latitude e longitude respectivamente. Exemplo: {"lat":-23.0852, "lon": -46.98020}
    • Array com latitude e longitude. Exemplo: [-23.0852,  -46.98020]
    • Coordenadas codificadas como geohash. Exemplo: "6tr6df675"
  • radius – Raio de busca, em metros, a partir do ponto central definido em center. Caso não seja informado, o valor padrão é 5.000.000 metros (5.000 Km).

Exemplo 1 – Busca de coordenadas 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 requisição completa encontra-se abaixo:

{
    "road": "Alameda Campinas",
    "number": 579,
    "city": "São Paulo",
    "state": "SP",
    "zipcode": "01404000"
}

A consulta também poderia ser feita utilizando o parâmetro label, conforme exemplo abaixo:

{
    "label": "Alameda Campinas, 579, 01404000, São Paulo,SP ",
    "city": "São Paulo",
    "state": "SP",
    "zipcode": "01404000"
}

Em ambos os casos, as seguintes informações são retornadas na resposta:

• found – Quantidade de registros retornados.
• results – Array de objetos com todos os resultados encontrados:
  • id – Identificador do endereço informado na requisição;
  • address – Objeto com informações do endereço:
    • road – Nome da via;
    • district – Bairro;
    • zipCode – CEP;
    • city – Cidade;
    • state – Estado;
    • mainLocation – Objeto com as coordenadas geográficas do ponto:
      • lat – Latitude;
      • lon – Longitude;
    • numberAsInteger – Número do endereço, mas retornado como número inteiro ao invés de string;
  • 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 encontra-se abaixo:

{
    "found": 1,
    "results": [
        {
            "id": "6684353bf0662a1541ff635d",
            "address": {
                "road": "ALAMEDA CAMPINAS",
                "number": "579",
                "district": "JARDIM PAULISTA",
                "zipCode": "01404000",
                "city": "SÃO PAULO",
                "state": {
                    "name": "SÃO PAULO",
                    "code": "SP"
                },
                "mainLocation": {
                    "lat": -23.566329468025202,
                    "lon": -46.653621381930805
                },
                "numberAsInteger": 579
            },
            "type": "ROAD",
            "label": "ALAMEDA CAMPINAS, 01404000, JARDIM PAULISTA, SÃO PAULO, SP",
            "score": 100.0
        }
    ]

Nota: Quanto maior o score, maior será 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 requisição possuir somente CEP, por exemplo, a pontuação será menor.

Exemplo 2 – Busca de coordenadas 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:

{
    "found": 1,
    "results": [
        {
            "id": "66843498f0662a1541f9c308",
            "address": {
                "road": "RUA BOA VISTA",
                "district": "CENTRO",
                "zipCode": "01014000",
                "city": "SÃO PAULO",
                "state": {
                    "name": "SÃO PAULO",
                    "code": "SP"
                },
                "mainLocation": {
                    "lat": -23.54685803583,
                    "lon": -46.63338712495
                }
            },
            "type": "ROAD",
            "label": "RUA BOA VISTA, 01014000, CENTRO, SÃO PAULO, SP",
            "score": 100.0
        }
    ]
}