Como utilizar a Suggestions API (Autocomplete)?

A Suggestions API consegue geocodificar um endereço a partir de um texto livre, fornecido na própria URL.

O objetivo da Suggestions API é retornar as coordenadas geográficas a partir de um endereço em texto livre fornecido na própria URL

Para utilizar a Suggestions API será 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 as coordenadas geográficas e sugestões de endereços.

Parâmetros da requisição

Parâmetro obrigatório

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

Parâmetros opcionais

  • type - Limita o tipo da pesquisa. Valores possíveis:

    • ZIPCODE - CEP;

    • STATE - Estado;

    • CITY - Cidade;

    • POI - Pedágios (Até a data atual);

    • DISTRICT - Bairro.

  • center - Coordenadas de referência para a busca de resultados. Formato: center=-23.552088765,-46.6341653162;

  • radius - Especifica o raio de buscar, em metros, a partir do ponto central. Caso não seja informado, o valor padrão é 5.000.000 metros (5.000 Km).

Exemplo 1 - Sugestões de pedágios a partir de nome parcial

No exemplo abaixo, vamos buscar por pontos de interesse (POI) que contenham a palavra “CAJAMAR”. A requisição encontra-se abaixo:

https://api.maplink.global/geocode/v1/suggestions?q=CAJAMAR&type=POI

Na resposta, as seguintes informações são retornadas:

  • found - Quantidade de registros encontrados;

  • results - Resultados encontrados:

    • poi - Ponto de interesse encontrado;

      • name - Nome do ponto de interesse.

    • 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": 2,
"results": [
{
"poi": {
"name": "Pedágio - Caieiras"
},
"address": {
"road": "SP 348 - Rod. dos Bandeirantes - Km 36",
"city": "Cajamar",
"state": {
"code": "SP",
"name": "São Paulo"
},
"type": "EXPRESSA",
"mainLocation": {
"lat": -23.3473844208,
"lon": -46.813413247
}
},
"type": "POI",
"score": 1.0,
"label": "Pedágio - Caieiras, SP 348 - Rod. dos Bandeirantes - Km 36, Cajamar, São Paulo, SP"
},
{
"poi": {
"name": "Pedágio - Campo Limpo"
},
"address": {
"road": "SP 348 - Rod. dos Bandeirantes - Km 39",
"city": "Cajamar",
"state": {
"code": "SP",
"name": "São Paulo"
},
"type": "EXPRESSA",
"mainLocation": {
"lat": -23.3229009122,
"lon": -46.8232457157
}
},
"type": "POI",
"score": 1.0,
"label": "Pedágio - Campo Limpo, SP 348 - Rod. dos Bandeirantes - Km 39, Cajamar, São Paulo, SP"
}
]
}

Nota: Quanto maior o score, maior será a relevância do resultado para o endereço solicitado.

Exemplo 2 - 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

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"
},
{
"address": {
"road": "Alameda Campinas 463",
"district": "Jardim Paulista",
"zipCode": "01404902",
"city": "São Paulo",
"state": {
"code": "SP",
"name": "São Paulo"
},
"mainLocation": {
"lat": -23.5658,
"lon": -46.65323
}
},
"type": "ZIPCODE",
"score": 23.845266,
"label": "Alameda Campinas 463, Jardim Paulista, 01404902, São Paulo, São Paulo, SP"
}
]
}

Exemplo 3 - Busca de endereço definindo um raio de busca

Nesse exemplo vamos usar o mesmo endereço do exemplo anterior, “Alameda Campinas, 01404100, Jardim Paulista”, mas dessa vez vamos definir um ponto central e um raio de busca para melhorar a precisão dos resultados.

Para isso vamos informar os seguintes parâmetros:

  • q - Texto com o endereço que queremos buscar, “Alameda Campinas, 01404100, Jardim Paulista;

  • center - Ponto central do nosso raio, no caso serão as coordenadas -23.538379,-46.62686 que correspondem ao centro da cidade de São Paulo;

  • radius - Tamanho do raio de busca, no caso será 10000 metros, ou 10 quilômetros.

https://api.maplink.global/geocode/v1/suggestions?q=Alameda%20Campinas,%2001404100,%20 Jardim%20Paulista%center=-23.5665,-46.65382%radius=10000000

Na resposta, podemos observar que a quantidade de endereços retornados diminui de 11 para 9, restringindo os resultados apenas para a cidade de São Paulo:

{
"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"
},
{
"address": {
"road": "Alameda Campinas 463",
"district": "Jardim Paulista",
"zipCode": "01404902",
"city": "São Paulo",
"state": {
"code": "SP",
"name": "São Paulo"
},
"mainLocation": {
"lat": -23.5658,
"lon": -46.65323
}
},
"type": "ZIPCODE",
"score": 23.845266,
"label": "Alameda Campinas 463, Jardim Paulista, 01404902, São Paulo, São Paulo, SP"
}
]
}

Exemplo 3 - Busca de endereço definindo um raio de busca

Nesse exemplo vamos usar o mesmo endereço do exemplo anterior, “Alameda Campinas, 01404100, Jardim Paulista”, mas dessa vez vamos definir um ponto central e um raio de busca para melhorar a precisão dos resultados.

Para isso vamos informar os seguintes parâmetros:

  • q - Texto com o endereço que queremos buscar, “Alameda Campinas, 01404100, Jardim Paulista;

  • center - Ponto central do nosso raio, no caso serão as coordenadas -23.538379,-46.62686 que correspondem ao centro da cidade de São Paulo;

  • radius - Tamanho do raio de busca, no caso será 10000 metros, ou 10 quilômetros.

https://api.maplink.global/geocode/v1/suggestions?q=Alameda%20Campinas,%2001404100,%20 Jardim%20Paulista%center=-23.5665,-46.65382%radius=10000000

Na resposta, podemos observar que a quantidade de endereços retornados diminui de 11 para 9, restringindo os resultados apenas para a cidade de São Paulo:

{
"found": 9,
"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": 85.66606,
"distance": 4162.89,
"label": "Alameda Campinas, Jardim Paulista, 01404100, 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": 85.66606,
"distance": 4338.66,
"label": "Alameda Campinas, Jardim Paulista, 01404001, 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": 84.5242,
"distance": 4162.89,
"label": "Alameda Campinas, Jardim Paulista, 01404000, 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": 84.5242,
"distance": 4305.84,
"label": "Alameda Campinas, Jardim Paulista, 01404200, 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": 84.5242,
"distance": 4914.52,
"label": "Alameda Campinas, Jardim Paulista, 01404002, 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": 84.5242,
"distance": 5096.57,
"label": "Alameda Campinas, Jardim Paulista, 01404003, 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": 84.30711,
"distance": 4064.73,
"label": "Alameda Campinas 150, Jardim Paulista, 01404900, 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": 83.16294,
"distance": 4064.73,
"label": "Alameda Campinas, 433, Jardim Paulista, 01404901, São Paulo, SP"
},
{
"address": {
"road": "Alameda Campinas, 463",
"district": "Jardim Paulista",
"zipCode": "01404902",
"city": "São Paulo",
"state": {
"code": "SP",
"name": "São Paulo"
},
"mainLocation": {
"lat": -23.5658,
"lon": -46.65323
}
},
"type": "ZIPCODE",
"score": 82.01029,
"distance": 4064.73,
"label": "Alameda Campinas, 463, Jardim Paulista, 01404902, São Paulo, SP"
}
]
}