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.
A Suggestions API foi atualizada para a V2. O endpoint https://api.maplink.global/geocode/v1/suggestions 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âmetro obrigatório
q– Informar o endereço ou parte dele.
Parâmetro opcionais
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 é 500.000 metros (500 Km);limit– Limita o número de resultados retornados. Por exemplo: https://api.maplink.global/geocode/v2/suggestions?limit=1
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: É recomendável descrever o endereço com o maior número de informações, ordenando os elementos de maior importância (Rua, Número, Cep, Bairro, Cidade, Estado) e sem abreviações para maior assertividade de 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– Objeto com as coordenadas geográficas do pontos:lat– Latitude;lon– 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:
{
"results": [
{
"id": "6684353bf0662a1541ff6385",
"address": {
"road": "ALAMEDA CAMPINAS",
"district": "JARDIM PAULISTA",
"zipCode": "01404100",
"city": "SÃO PAULO",
"state": {
"name": "SÃO PAULO",
"code": "SP"
},
"mainLocation": {
"lat": -23.56631144908,
"lon": -46.65360036597
}
},
"type": "ROAD",
"label": "ALAMEDA CAMPINAS, 01404100, JARDIM PAULISTA, SÃO PAULO, SP",
"score": 85.4173641545432
},
{
"id": "6684353bf0662a1541ff63a2",
"address": {
"road": "ALAMEDA CAMPINAS",
"district": "JARDIM PAULISTA",
"zipCode": "01404200",
"city": "SÃO PAULO",
"state": {
"name": "SÃO PAULO",
"code": "SP"
},
"mainLocation": {
"lat": -23.56714829171,
"lon": -46.65440337412
}
},
"type": "ROAD",
"label": "ALAMEDA CAMPINAS, 01404200, JARDIM PAULISTA, SÃO PAULO, SP",
"score": 67.51744304384503
},
{
"id": "6684353bf0662a1541ff635d",
"address": {
"road": "ALAMEDA CAMPINAS",
"district": "JARDIM PAULISTA",
"zipCode": "01404000",
"city": "SÃO PAULO",
"state": {
"name": "SÃO PAULO",
"code": "SP"
},
"mainLocation": {
"lat": -23.5663551335,
"lon": -46.65364273168
}
},
"type": "ROAD",
"label": "ALAMEDA CAMPINAS, 01404000, JARDIM PAULISTA, SÃO PAULO, SP",
"score": 67.51744304384503
},
{
"id": "6684353bf0662a1541ff63a3",
"address": {
"road": "ALAMEDA CAMPINAS 150",
"district": "JARDIM PAULISTA",
"zipCode": "01404900",
"city": "SÃO PAULO",
"state": {
"name": "SÃO PAULO",
"code": "SP"
},
"mainLocation": {
"lat": -23.56343039334,
"lon": -46.6507807755
}
},
"type": "ROAD",
"label": "ALAMEDA CAMPINAS 150, 01404900, JARDIM PAULISTA, SÃO PAULO, SP",
"score": 63.98775935173035
},
{
"id": "6684353bf0662a1541ff637b",
"address": {
"road": "ALAMEDA CAMPINAS",
"district": "JARDIM PAULISTA",
"zipCode": "01404001",
"city": "SÃO PAULO",
"state": {
"name": "SÃO PAULO",
"code": "SP"
},
"mainLocation": {
"lat": -23.56880844109,
"lon": -46.65604091167
}
},
"type": "ROAD",
"label": "ALAMEDA CAMPINAS, 01404001, JARDIM PAULISTA, SÃO PAULO, SP",
"score": 62.547320382935666
},
{
"id": "6684353bf0662a1541ff63b9",
"address": {
"road": "ALAMEDA CAMPINAS",
"district": "JARDIM PAULISTA",
"zipCode": "01404002",
"city": "SÃO PAULO",
"state": {
"name": "SÃO PAULO",
"code": "SP"
},
"mainLocation": {
"lat": -23.57150846699,
"lon": -46.65863824537
}
},
"type": "ROAD",
"label": "ALAMEDA CAMPINAS, 01404002, JARDIM PAULISTA, SÃO PAULO, SP",
"score": 62.36442055021014
},
{
"id": "6684353bf0662a1541ff637c",
"address": {
"road": "ALAMEDA CAMPINAS",
"district": "JARDIM PAULISTA",
"zipCode": "01404003",
"city": "SÃO PAULO",
"state": {
"name": "SÃO PAULO",
"code": "SP"
},
"mainLocation": {
"lat": -23.5727482959,
"lon": -46.65984093151
}
},
"type": "ROAD",
"label": "ALAMEDA CAMPINAS, 01404003, JARDIM PAULISTA, SÃO PAULO, SP",
"score": 62.36442055021014
},
{
"id": "66842f7b6969121fb9f0de4e",
"address": {
"road": "ALAMEDA CAMPINAS",
"district": "JARDIM PAULISTA",
"zipCode": "12947480",
"city": "ATIBAIA",
"state": {
"name": "SÃO PAULO",
"code": "SP"
},
"mainLocation": {
"lat": -23.141018593,
"lon": -46.557696254
}
},
"type": "ROAD",
"label": "ALAMEDA CAMPINAS, 12947480, JARDIM PAULISTA, ATIBAIA, SP",
"score": 60.32122203281947
},
{
"id": "6684353bf0662a1541ff6359",
"address": {
"road": "ALAMEDA CAMPINAS, 433",
"district": "JARDIM PAULISTA",
"zipCode": "01404901",
"city": "SÃO PAULO",
"state": {
"name": "SÃO PAULO",
"code": "SP"
},
"mainLocation": {
"lat": -23.56550964281,
"lon": -46.65281726051
}
},
"type": "ROAD",
"label": "ALAMEDA CAMPINAS, 433, 01404901, JARDIM PAULISTA, SÃO PAULO, SP",
"score": 58.74167782919748
},
{
"id": "6684343ef0662a1541f5003c",
"address": {
"road": "ALAMEDA SARUTAIÁ",
"district": "JARDIM PAULISTA",
"zipCode": "01403010",
"city": "SÃO PAULO",
"state": {
"name": "SÃO PAULO",
"code": "SP"
},
"mainLocation": {
"lat": -23.5689407,
"lon": -46.6549067
}
},
"type": "ROAD",
"label": "ALAMEDA SARUTAIÁ, 01403010, JARDIM PAULISTA, SÃO PAULO, SP",
"score": 55.39309246199472
}
],
"found": 10
}
