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 da coordenada a partir de endereço
• Exemplo 2 – Busca da coordenada a partir do CEP
• Exemplo 3 – Busca de endereço internacional

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/v1/geocode – POST

Para endereços fora do Brasil, será necessário adicionar o query param globalSearch na URL, da seguinte forma: https://api.maplink.global/geocode/v1/geocode?globalSearch=true

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.

Parâmetro opcional

• type – Limita o tipo da pesquisa. Apenas para endereços no Brasil e caso o parâmetro globalSearch não seja informado. Valores possíveis:
  • ZIPCODE – CEP;
  • STATE – Estado;
  • CITY – Cidade;
  • DISTRICT – Bairro.

Nota: 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 requisição completa 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 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 – 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 encontra-se 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 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 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:

{
    "found": 1,
    "results": [
        {
            "address": {
                "road": "Rua Boa Vista",
                "district": "Centro",
                "zipCode": "01014000",
                "city": "São Paulo",
                "state": {
                    "code": "SP",
                    "name": "São Paulo"
                },
                "mainLocation": {
                    "lat": -23.6424087754,
                    "lon": -46.5619422622
                }
            },
            "type": "ZIPCODE",
            "score": 24.653545,
            "label": "Rua Boa Vista, Centro, 01014000, São Paulo, São Paulo, SP"
        }
    ]
}

Exemplo 3 – Busca de endereço internacional

Para buscar endereços de outros países, será necessário adicionar o parâmetro globalSearch na URL, da seguinte forma:  https://api.maplink.global/geocode/v1/geocode?globalSearch=true

Abaixo temos uma requisição para o endereço "Av. Córdoba 5869, CABA, Argentina":

{
    "road": "Av. Córdoba",
    "number": 5869,
    "city": "CABA",
    "country":"Argentina"
}

A resposta completa pode ser conferida abaixo:

{
    "found": 1
    "results": [
        {
            "address": {
                "road": "Avenida Córdoba",
                "district": "Palermo",
                "zipCode": "C1188AAQ",
                "city": "Buenos Aires",
                "state": {
                    "code": "",
                    "name": "Ciudad Autónoma de Buenos Aires"
                },
                "country": "Argentina",
                "mainLocation": {
                    "lat": -34.5977459,
                    "lon": -58.4198975
                }
            },
            "score": 26.520788,
         "label": "Avenida Córdoba, Palermo, Buenos Aires, Argentina"
        }
   ],
}