Construindo requisições para Suggestions API
Para realizar a requisição para a Suggestions API é necessário usar o método GET/suggestions:
https://api.maplink.global/geocode/v1/suggestions
os seguintes headers são necessários:
--header 'Content-Type: application/json' \ --header 'Authorization: Bearer token'
Onde Token é o access token obtido na autenticação.
Na própria URL são enviados todos os parâmetros para obter a coordenada geográfica e sugestões de endereços.
Body e Parâmetros da Request
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 deste documento 13/04/2021);DISTRICT:Bairro.
center- Coordenadas de referência para a busca de resultados. Formato:center=-23.552088765,-46.6341653162radius- 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
Exemplo de Request com parâmetros obrigatórios:
https://api.maplink.global/geocode/v1/suggestions?q=CAJAMAR&type=POI
https://api.maplink.global/geocode/v1/suggestions?q=Avenida%20Santos%20Dumont,%2007220000,%20Cumbica%20Guarulhos%20center=-23.46742411032163,-46.53359478248584
https://api.maplink.global/geocode/v1/suggestions?q=Alameda%20Campinas,%2001404100,%20 Jardim%20Paulista%center=-23.5665,-46.65382%radius=10000000
Exemplo de Response, 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.
{
"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"
}
]
}
{
"found": 10000,
"results": [
{
"address": {
"road": "Avenida Santos Dumont",
"district": "Cumbica",
"zipCode": "07180270",
"city": "Guarulhos",
"state": {
"code": "SP",
"name": "São Paulo"
},
"mainLocation": {
"lat": -23.452312325,
"lon": -46.474739639
}
},
"type": "ZIPCODE",
"score": 88.74078,
"label": "Avenida Santos Dumont, Cumbica, 07180270, Guarulhos, SP"
},
{
"found": 10000,
"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": 84.92031,
"label": "Alameda Campinas, Jardim Paulista, 01404100, São Paulo, SP"
},
Nota: Verifique o score para verificar a pontuação alcançada a partir dos elementos usados nos parâmetros. 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 request possuir somente CEP, a pontuação será menor.
Para informações detalhadas de como funciona o score do elasticsearch, consulte o link:
Exemplo 2 - Busca de sugestões a partir de texto livre
Exemplo de Request para obter sugestões para o texto “Alameda Campinas, 01404100, Jardim Paulista”:
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.
Exemplo da Response:
{
"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"
}
]
}