Versions Compared

Version Old Version 6 New Version Current
Changes made by

Willian Silva

Willian Silva

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Table of Contents

Construindo requisições para a Suggestions API

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

Para utilizar a Suggestions API é necessário usar será necessário enviar a requisição usando o método GET /suggestions:

...

languagejson

para o seguinte endpoint:

os seguintes headers são necessários:

Code Block
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer token'

Onde Token é o access token obtido na autenticação.

Na própria URLsão enviados todos os parâmetros para obter a coordenada geográfica 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 deste documento 13/04/2021atual);

    • DISTRICT: - Bairro.

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

  • radius - Especifica o raio de buscarbusca, 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óriosNo 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

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, Na resposta, as seguintes informações são retornadas:

  • found: quantidade - Quantidade de registros encontrados.;

  • results: resultados - Resultados encontrados:

    • poi: ponto - Ponto de interesse encontrado;

      • name : nome - Nome do ponto de interesse.

    • address: endereço - Endereço:

      • road: nome - Nome da via;

      • district: bairro - Bairro;

      • zipCode: - CEP;

      • city: cidade - Cidade;

      • state: estado - Estado;

      • mainLocation: coordenadas - Coordenadas geográficas em latitude/longitude;

    • type: indica - Indica qual o melhor elemento encontrado na base cartográfica para o retorno da coordenada geográfica;

    • score: pontuação - Pontuação de referência do resultado do processo de geocodificação;

    • label: endereço - Endereço completo encontrado utilizado no processo de geocodificação.

A resposta completa pode ser conferida abaixo:

Code Block
languagejson
{
    "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"
        }
    ]
}

...

Info

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:

Code Block
languagejson
{
    "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"
        },

...

Info

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:

how-scoring-works-in-elasticsearch

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”:

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

Info

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:

Code Block
languagejson
{
    "found": 11,
    "results": [
        {
        {
            "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",
                    "addressname": {"São  Paulo"
              "road": "Alameda Campinas"},
                "districtmainLocation": {
  "Jardim Paulista",                 "zipCodelat": "01404100",-23.5658,
                    "citylon": "São Paulo", -46.65323
                }
   "state": {        },
            "codetype": "SPZIPCODE",
       
            "namescore": "São Paulo"23.845266,
            "label": "Alameda Campinas 463, Jardim }Paulista, 01404902, São Paulo, São Paulo, SP"
        }
 "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"
        },]
}

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:

Code Block
languagejson
{
    "found": 9,
    "results": [
        {
            "address": {
                "road": "Alameda Campinas",
                "district": "Jardim Paulista",
                "zipCode": "1294748001404100",
                "city": "AtibaiaSão Paulo",
                "state": {
                    "code": "SP",
                    "name": "São Paulo"
                },
                "mainLocation": {
                    "lat": -23.14101859255665,
                    "lon": -46.557696253765382
                }
            },
            "type": "ZIPCODE",
            "score": 25.78013 85.66606,
            "distance": 4162.89,
            "label": "Alameda Campinas, Jardim Paulista, 12947480, Atibaia01404100, São Paulo, SP"
        },
        {
            "address": {
                "road": "Alameda Campinas",
                "district": "Jardim Paulista",
                "zipCode": "0140400201404001",
                "city": "São Paulo",
                "state": {
                    "code": "SP",
                    "name": "São Paulo"
                },
                "mainLocation": {
                    "lat": -23.5715656767,
                    "lon": -46.6587165498
                }
            },
            }   "type": "ZIPCODE",
            "typescore": "ZIPCODE"85.66606,
            "scoredistance": 254338.73222466,
            "label": "Alameda Campinas, Jardim Paulista, 01404002, São Paulo01404001, São Paulo, SP"
        },
        {
            "address": {
                "road": "Alameda Campinas",
                "district": "Jardim Paulista",
                "zipCode": "0140420001404000",
                "city": "São Paulo",
                "state": {
                    "code": "SP",
                    "name": "São Paulo"
                },
                "mainLocation": {
                    "lat": -23.56743425665,
                    "lon": -46.6547848565382
                }
            },
            "type": "ZIPCODE",
            "score": 25.732224 84.5242,
            "distance": 4162.89,
            "label": "Alameda Campinas, Jardim Paulista, 01404200, São Paulo01404000, São Paulo, SP"
        },
        {
            "address": {
                "road": "Alameda Campinas",
                "district": "Jardim Paulista",
                "zipCode": "0140400001404200",
                "city": "São Paulo",
                "state": {
                    "code": "SP",
                    "name": "São Paulo"
                },
                "mainLocation": {
                    "lat": -23.56655674342,
                    "lon": -46.6538265478485
                }
            },
            "type": "ZIPCODE",
            "score": 84.5242,
            "distance": 254305.1371384,
            "label": "Alameda Campinas, Jardim Paulista, 01404000, São Paulo01404200, São Paulo, SP"
        },
        {
            "address": {
                "road": "Alameda Campinas",
                "district": "Jardim Paulista",
                "zipCode": "0140400101404002",
                "city": "São Paulo",
                "state": {
                    "code": "SP",
                    "name": "São Paulo"
                },
                "mainLocation": {
                    "lat": -23.5676757156,
                    "lon": -46.6549865871
                }
            },
            "type": "ZIPCODE",
            "score": 84.5242,
            "distance": 244914.9392552,
            "label": "Alameda Campinas, Jardim Paulista, 0140400101404002, 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": 84.5242,
            "distance": 245096.9392557,
            "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",
            "typescore": "ZIPCODE"84.30711,
            "scoredistance": 244064.00568873,
            "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 83.16294,
            "distance": 4064.73,
            "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 82.01029,
            "distance": 4064.73,
            "label": "Alameda Campinas, 463, Jardim Paulista, 01404902, São Paulo, São Paulo, SP"
        }
    ]
}