Geocode API
O objetivo desse primeiro endpoint é retornar as coordenadas geográficas a partir de um endereço completo ou parcial.
- Lista de parâmetros
- Exemplo 1 – Busca de coordenadas a partir de endereço
- Exemplo 2 – Busca de coordenadas a partir do CEP
Para realizar a requisição para a Geocode API é necessário enviar a requisição usando o método POST para o seguinte endpoint:
A Geocode API foi atualizada para a V2. O endpoint https://api.maplink.global/geocode/v1/geocode 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âmetros obrigatórios
É obrigatório informar ao menos um. Não é necessário informar todos. No entanto, quanto mais informações forem fornecidas, mais preciso será o resultado.
road– Nome da rua ou parte dele;number– Número do logradouro. NÃO informar os dados do complemento.city– Nome da cidade;state– Estado;country– País;district– Nome do bairro;zipcode– CEP;label– Endereço completo. Recomenda-se montar o texto na ordem “Nome da rua, número, CEP, bairro, cidade, estado”.
Nota: Há o limite de 200 pontos para o envio em uma mesma requisição.
Parâmetros opcionais
mainLocation– Objeto com dois parâmetros para limitar a área de busca do endereço:center– Objeto com as coordenadas de referência para a busca de resultados. As coordenadas podem ser informadas nos seguintes formatos:- Objeto com as propriedades
latelonque representam latitude e longitude respectivamente. Exemplo:{"lat":-23.0852, "lon": -46.98020} - Array com latitude e longitude. Exemplo:
[-23.0852, -46.98020] - Coordenadas codificadas como geohash. Exemplo:
"6tr6df675"
- Objeto com as propriedades
radius– 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. É um query param, informado na propria URL. Por exemplo: https://api.maplink.global/geocode/v2/geocode?limit=1
Exemplo 1 – Busca de coordenadas a partir de endereço
No exemplo a seguir, vamos requisitar as coordenadas para o endereço “Alameda Campinas, 579, São Paulo – SP, CEP 01404-100”. A requisição completa encontra-se abaixo:
{
"road": "Alameda Campinas",
"number": 579,
"city": "São Paulo",
"state": "SP",
"zipcode": "01404000"
}
A consulta também poderia ser feita utilizando o parâmetro label, conforme exemplo abaixo:
{
"label": "Alameda Campinas, 579, 01404000, São Paulo,SP ",
"city": "São Paulo",
"state": "SP",
"zipcode": "01404000"
}
A descrição de cada campo presente na resposta pode ser conferida no link a seguir: Estrutura de resposta – Geocode API.
A resposta completa encontra-se abaixo:
{
"results": [
{
"id": "6684353bf0662a1541ff635d",
"address": {
"road": "ALAMEDA CAMPINAS",
"number": "579",
"district": "JARDIM PAULISTA",
"zipCode": "01404000",
"city": "SÃO PAULO",
"state": {
"name": "SÃO PAULO",
"code": "SP"
},
"mainLocation": {
"lat": -23.566287789653508,
"lon": -46.6537028592172
},
"numberAsInteger": 579
},
"type": "ROAD",
"label": "ALAMEDA CAMPINAS, 01404000, JARDIM PAULISTA, SÃO PAULO, SP",
"score": 98.81773828023887,
"precision": "NUMBER_MEDIUM_PRECISION"
},
{
"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": 92.9419580012093,
"precision": "ROAD_CENTROID"
},
{
"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": 92.9419580012093,
"precision": "ROAD_CENTROID"
},
{
"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": 92.9419580012093,
"precision": "ROAD_CENTROID"
},
{
"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": 92.78814049548771,
"precision": "ROAD_CENTROID"
},
{
"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": 92.78814049548771,
"precision": "ROAD_CENTROID"
},
{
"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": 91.48049238291864,
"precision": "ROAD_CENTROID"
},
{
"id": "6684344df0662a1541f5baee",
"address": {
"road": "RUA HAITI",
"district": "JARDIM PAULISTA",
"zipCode": "01404010",
"city": "SÃO PAULO",
"state": {
"name": "SÃO PAULO",
"code": "SP"
},
"mainLocation": {
"lat": -23.571433,
"lon": -46.6607828
}
},
"type": "ROAD",
"label": "RUA HAITI, 01404010, JARDIM PAULISTA, SÃO PAULO, SP",
"score": 84.24055564325018,
"precision": "ROAD_CENTROID"
},
{
"id": "6684342ef0662a1541f41a70",
"address": {
"road": "ALAMEDA LORENA",
"number": "579",
"district": "JARDIM PAULISTA",
"zipCode": "01424000",
"city": "SÃO PAULO",
"state": {
"name": "SÃO PAULO",
"code": "SP"
},
"mainLocation": {
"lat": -23.56994038386821,
"lon": -46.65933806789288
},
"numberAsInteger": 579
},
"type": "ROAD",
"label": "ALAMEDA LORENA, 01424000, JARDIM PAULISTA, SÃO PAULO, SP",
"score": 84.15016434701576,
"precision": "NUMBER_MEDIUM_PRECISION"
},
{
"id": "66843453f0662a1541f60988",
"address": {
"road": "ALAMEDA CASA BRANCA",
"number": "579",
"district": "JARDIM PAULISTA",
"zipCode": "01408000",
"city": "SÃO PAULO",
"state": {
"name": "SÃO PAULO",
"code": "SP"
},
"mainLocation": {
"lat": -23.565856915927288,
"lon": -46.659742464053295
},
"numberAsInteger": 579
},
"type": "ROAD",
"label": "ALAMEDA CASA BRANCA, 01408000, JARDIM PAULISTA, SÃO PAULO, SP",
"score": 84.01280084636662,
"precision": "NUMBER_MEDIUM_PRECISION"
}
],
"found": 10
}
Exemplo 2 – Busca de coordenadas a partir do CEP
Nesse exemplo, vamos realizar uma requisição informando apenas o CEP 01014-000:
{
"zipcode": "01014000"
}
A resposta completa pode ser conferida abaixo:
{
"results": [
{
"id": "66843498f0662a1541f9c308",
"address": {
"road": "RUA BOA VISTA",
"district": "CENTRO",
"zipCode": "01014000",
"city": "SÃO PAULO",
"state": {
"name": "SÃO PAULO",
"code": "SP"
},
"mainLocation": {
"lat": -23.54685803583,
"lon": -46.63338712495
}
},
"type": "ROAD",
"label": "RUA BOA VISTA, 01014000, CENTRO, SÃO PAULO, SP",
"score": 100.0,
"precision": "ROAD_CENTROID"
},
{
"id": "6684343cf0662a1541f4ea76",
"address": {
"road": "RUA BOA VISTA",
"district": "CENTRO",
"zipCode": "01014001",
"city": "SÃO PAULO",
"state": {
"name": "SÃO PAULO",
"code": "SP"
},
"mainLocation": {
"lat": -23.5468007,
"lon": -46.633395
}
},
"type": "ROAD",
"label": "RUA BOA VISTA, 01014001, CENTRO, SÃO PAULO, SP",
"score": 93.37499945930055,
"precision": "ROAD_CENTROID"
},
{
"id": "6684343ef0662a1541f501cf",
"address": {
"road": "RUA TRÊS DE DEZEMBRO",
"district": "CENTRO",
"zipCode": "01014020",
"city": "SÃO PAULO",
"state": {
"name": "SÃO PAULO",
"code": "SP"
},
"mainLocation": {
"lat": -23.5464096,
"lon": -46.6338955
}
},
"type": "ROAD",
"label": "RUA TRÊS DE DEZEMBRO, 01014020, CENTRO, SÃO PAULO, SP",
"score": 93.24999957850984,
"precision": "ROAD_CENTROID"
},
{
"id": "66843464f0662a1541f6dfc7",
"address": {
"road": "RUA JOÃO BRÍCOLA",
"district": "CENTRO",
"zipCode": "01014010",
"city": "SÃO PAULO",
"state": {
"name": "SÃO PAULO",
"code": "SP"
},
"mainLocation": {
"lat": -23.5454833,
"lon": -46.6339965
}
},
"type": "ROAD",
"label": "RUA JOÃO BRÍCOLA, 01014010, CENTRO, SÃO PAULO, SP",
"score": 93.24999957850984,
"precision": "ROAD_CENTROID"
},
{
"id": "66843492f0662a1541f96cc3",
"address": {
"road": "RUA JOÃO BRÍCOLA 24",
"district": "CENTRO",
"zipCode": "01014900",
"city": "SÃO PAULO",
"state": {
"name": "SÃO PAULO",
"code": "SP"
},
"mainLocation": {
"lat": -23.5456536,
"lon": -46.6341742
}
},
"type": "ROAD",
"label": "RUA JOÃO BRÍCOLA 24, 01014900, CENTRO, SÃO PAULO, SP",
"score": 93.12499969771913,
"precision": "ROAD_CENTROID"
},
{
"id": "66843491f0662a1541f96a2d",
"address": {
"road": "RUA BOA VISTA, 84",
"district": "CENTRO",
"zipCode": "01014901",
"city": "SÃO PAULO",
"state": {
"name": "SÃO PAULO",
"code": "SP"
},
"mainLocation": {
"lat": -23.5469951,
"lon": -46.6333665
}
},
"type": "ROAD",
"label": "RUA BOA VISTA, 84, 01014901, CENTRO, SÃO PAULO, SP",
"score": 76.42857070419251,
"precision": "ROAD_CENTROID"
},
{
"id": "66843491f0662a1541f96bb6",
"address": {
"road": "RUA BOA VISTA, 162",
"district": "CENTRO",
"zipCode": "01014902",
"city": "SÃO PAULO",
"state": {
"name": "SÃO PAULO",
"code": "SP"
},
"mainLocation": {
"lat": -23.5463321,
"lon": -46.6334634
}
},
"type": "ROAD",
"label": "RUA BOA VISTA, 162, 01014902, CENTRO, SÃO PAULO, SP",
"score": 76.42857070419251,
"precision": "ROAD_CENTROID"
},
{
"id": "66843499f0662a1541f9c677",
"address": {
"road": "RUA BOA VISTA, 200",
"district": "CENTRO",
"zipCode": "01014903",
"city": "SÃO PAULO",
"state": {
"name": "SÃO PAULO",
"code": "SP"
},
"mainLocation": {
"lat": -23.5459389,
"lon": -46.6335149
}
},
"type": "ROAD",
"label": "RUA BOA VISTA, 200, 01014903, CENTRO, SÃO PAULO, SP",
"score": 76.42857070419251,
"precision": "ROAD_CENTROID"
},
{
"id": "6684345ef0662a1541f691de",
"address": {
"road": "RUA GENERAL CARNEIRO",
"district": "CENTRO",
"zipCode": "01015000",
"city": "SÃO PAULO",
"state": {
"name": "SÃO PAULO",
"code": "SP"
},
"mainLocation": {
"lat": -23.5463825,
"lon": -46.632325
}
},
"type": "ROAD",
"label": "RUA GENERAL CARNEIRO, 01015000, CENTRO, SÃO PAULO, SP",
"score": 72.01709473660739,
"precision": "ROAD_CENTROID"
},
{
"id": "66843498f0662a1541f9c2b1",
"address": {
"road": "RUA ANTÔNIO DE GODÓI",
"district": "CENTRO",
"zipCode": "01034000",
"city": "SÃO PAULO",
"state": {
"name": "SÃO PAULO",
"code": "SP"
},
"mainLocation": {
"lat": -23.5420724,
"lon": -46.63730905
}
},
"type": "ROAD",
"label": "RUA ANTÔNIO DE GODÓI, 01034000, CENTRO, SÃO PAULO, SP",
"score": 71.29380425752609,
"precision": "ROAD_CENTROID"
}
],
"found": 10
}
