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 falsetype– Limita o tipo da pesquisa. Apenas para endereços no Brasil e caso o parâmetroglobalSearchnã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 emcenter. 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:
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 emlatitude/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.
Nota: Quanto maior o score, maior será a relevância do resultado para o endereço solicitado.
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"
}
]
}
