Geocode

Suggestions API

O objetivo desse terceiro endpoint, Suggestions, é retornar as coordenadas geográficas a partir de um endereço fornecido na própria URL

Para realizar a requisição para a Suggestions é necessário enviar a requisição usando o método GET para o seguinte endpoint: 

Na própria URL serão enviados todos os parâmetros para obter a coordenada geográfica e sugestões de endereços.

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/suggestions?globalSearch=true

Lista de parâmetros

Parâmetro obrigatório

  • q – Informar o endereço ou parte dele.

Parâmetro opcionais

  • globalSearch – Define se pesquisa será global ou apenas no Brasil. Valores possíveis: true ou false
  • 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.
  • center – Coordenadas de referência para a busca de resultados. Formato: center=-23.552088765,-46.6341653162;
  • radius – Especifica o 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 sugestões a partir de texto livre

Nesse exemplo, queremos obter sugestões para o texto “Alameda Campinas, 01404100, Jardim Paulista”. A requisição encontra-se abaixo:

https://api.maplink.global/geocode/v1/suggestions?q=Alameda%20Campinas,%2001404100,%20Jardim%20Paulista

Nota: Ao utilizar o texto livre para busca de sugestões em que nenhum type é informado, é recomendável descrever o endereço com o maior número de informações, ordenando os elementos de maior importância, e sem abreviações para que a API consiga comparar melhor o texto procurado com os resultados. 

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 pode ser conferida abaixo:

{
    "found": 11,
    "results": [
        {
            "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": 37.228725,
            "label": "Alameda Campinas, Jardim Paulista, 01404100, São Paulo, São Paulo, SP"
        },
        {
            "address": {
                "road": "Alameda Campinas",
                "district": "Jardim Paulista",
                "zipCode": "12947480",
                "city": "Atibaia",
                "state": {
                    "code": "SP",
                    "name": "São Paulo"
                },
                "mainLocation": {
                    "lat": -23.1410185925,
                    "lon": -46.5576962537
                }
            },
            "type": "ZIPCODE",
            "score": 25.78013,
            "label": "Alameda Campinas, Jardim Paulista, 12947480, Atibaia, São Paulo, SP"
        },
        {
            "address": {
                "road": "Alameda Campinas",
                "district": "Jardim Paulista",
                "zipCode": "01404002",
                "city": "São Paulo",
                "state": {
                    "code": "SP",
                    "name": "São Paulo"
                },
                "mainLocation": {
                    "lat": -23.57156,
                    "lon": -46.65871
                }
            },
            "type": "ZIPCODE",
            "score": 25.732224,
            "label": "Alameda Campinas, Jardim Paulista, 01404002, São Paulo, São Paulo, SP"
        },
        {
            "address": {
                "road": "Alameda Campinas",
                "district": "Jardim Paulista",
                "zipCode": "01404200",
                "city": "São Paulo",
                "state": {
                    "code": "SP",
                    "name": "São Paulo"
                },
                "mainLocation": {
                    "lat": -23.5674342,
                    "lon": -46.65478485
                }
            },
            "type": "ZIPCODE",
            "score": 25.732224,
            "label": "Alameda Campinas, Jardim Paulista, 01404200, São Paulo, São Paulo, SP"
        },
        {
            "address": {
                "road": "Alameda Campinas",
                "district": "Jardim Paulista",
                "zipCode": "01404000",
                "city": "São Paulo",
                "state": {
                    "code": "SP",
                    "name": "São Paulo"
                },
                "mainLocation": {
                    "lat": -23.5665,
                    "lon": -46.65382
                }
            },
            "type": "ZIPCODE",
            "score": 25.13713,
            "label": "Alameda Campinas, Jardim Paulista, 01404000, São Paulo, São Paulo, SP"
        },
        {
            "address": {
                "road": "Alameda Campinas",
                "district": "Jardim Paulista",
                "zipCode": "01404001",
                "city": "São Paulo",
                "state": {
                    "code": "SP",
                    "name": "São Paulo"
                },
                "mainLocation": {
                    "lat": -23.56767,
                    "lon": -46.65498
                }
            },
            "type": "ZIPCODE",
            "score": 24.93925,
            "label": "Alameda Campinas, Jardim Paulista, 01404001, São Paulo, São Paulo, SP"
        },
        {
            "address": {
                "road": "Alameda Campinas",
                "district": "Jardim Paulista",
                "zipCode": "01404003",
                "city": "São Paulo",
                "state": {
                    "code": "SP",
                    "name": "São Paulo"
                },
                "mainLocation": {
                    "lat": -23.5727386,
                    "lon": -46.65995255
                }
            },
            "type": "ZIPCODE",
            "score": 24.93925,
            "label": "Alameda Campinas, Jardim Paulista, 01404003, São Paulo, São Paulo, SP"
        },
        {
            "address": {
                "road": "Alameda Campinas 150",
                "district": "Jardim Paulista",
                "zipCode": "01404900",
                "city": "São Paulo",
                "state": {
                    "code": "SP",
                    "name": "São Paulo"
                },
                "mainLocation": {
                    "lat": -23.5658,
                    "lon": -46.65323
                }
            },
            "type": "ZIPCODE",
            "score": 24.005688,
            "label": "Alameda Campinas 150, Jardim Paulista, 01404900, São Paulo, São Paulo, SP"
        },
        {
            "address": {
                "road": "Alameda Campinas 433",
                "district": "Jardim Paulista",
                "zipCode": "01404901",
                "city": "São Paulo",
                "state": {
                    "code": "SP",
                    "name": "São Paulo"
                },
                "mainLocation": {
                    "lat": -23.5658,
                    "lon": -46.65323
                }
            },
            "type": "ZIPCODE",
            "score": 24.005688,
            "label": "Alameda Campinas 433, Jardim Paulista, 01404901, São Paulo, São Paulo, SP"
        }
    ]
}