Geocode API
The purpose of this first endpoint is to return geographic coordinates from a full or partial address.
- List of parameters
- Example 1 – Search for coordinates from address
- Example 2 – Search for coordinates from zip code
To make a request to the Geocode API, you must send the request using the POST method to the following endpoint:
Note: Currently returning only to directions located in Brazil.
The Geocode API has been updated to V2. The endpoint https://api.maplink.global/geocode/v1/geocode will still work, but it is recommended to use the new endpoint for more accurate results and because new features will be exclusive to the new version.
List of parameters
Mandatory parameters
It is mandatory to provide at least one. It is not necessary to provide all of them. However, the more information provided, the more accurate the result will be.
road– Street name or part of it;number– Address number. DO NOT provide the additional information.city– City name;state– State;country– Country;district– District name;zipcode– Zip code;label– Complete address. It is recommended to type the text in the order “Street name, number, zip code, district, city, state”.
Optional parameters
mainLocation– Object with two parameters to limit the address search area:center– Object with the reference coordinates for the search results. The coordinates can be entered in the following formats:- Object with the
latandlonproperties that represent latitude and longitude respectively. Example:{"lat":-23.0852, "lon": -46.98020} - Array with latitude and longitude. Example:
[-23.0852, -46.98020] - Coordinates encoded as geohash. Example:
"6tr6df675"
- Object with the
radius– Search radius, in meters, from the central point defined in center. If not entered, the default value is 500,000 meters (500 km).
limit– Limits the number of results returned. It is a query param, informed in the URL itself. For example: https://api.maplink.global/geocode/v2/geocode?limit=1
Example 1 – Search for coordinates from address
In the following example, we will request the coordinates for the address “Alameda Campinas, 579, São Paulo – SP, CEP 01404-100”. The full request is below:
{
"road": "Alameda Campinas",
"number": 579,
"city": "São Paulo",
"state": "SP",
"zipcode": "01404000"
}
The query could also be made using the parameter label, as shown in the example below:
{
"label": "Alameda Campinas, 579, 01404000, São Paulo,SP ",
"city": "São Paulo",
"state": "SP",
"zipcode": "01404000"
}
The description of each field present in the response can be found in the following link: Response structure – Geocode API.
The full response can be found below:
{
"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": 100.0,
"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": 95.63067996776094,
"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": 95.63067996776094,
"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": 95.63067996776094,
"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": 95.57965960825454,
"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": 95.57965960825454,
"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": 92.4522052844475,
"precision": "ROAD_CENTROID"
},
{
"id": "6684353bf0662a1541ff635b",
"address": {
"road": "ALAMEDA CAMPINAS, 463",
"district": "JARDIM PAULISTA",
"zipCode": "01404902",
"city": "SÃO PAULO",
"state": {
"name": "SÃO PAULO",
"code": "SP"
},
"mainLocation": {
"lat": -23.56559742572,
"lon": -46.6529043066
}
},
"type": "ROAD",
"label": "ALAMEDA CAMPINAS, 463, 01404902, JARDIM PAULISTA, SÃO PAULO, SP",
"score": 84.89738503108725,
"precision": "ROAD_CENTROID"
},
{
"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": 84.89738503108725,
"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": 72.05528351949013,
"precision": "NUMBER_MEDIUM_PRECISION"
}
],
"found": 10
}
Example 2 – Search for coordinates from zip code
In this example, we will make a request informing only the zip code 01014-000:
{
"zipcode": "01014000"
}
The full response can be found below:
{
"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": "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": "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": "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": "6684345ef0662a1541f68944",
"address": {
"road": "RUA SÃO BENTO",
"district": "CENTRO",
"zipCode": "01011000",
"city": "SÃO PAULO",
"state": {
"name": "SÃO PAULO",
"code": "SP"
},
"mainLocation": {
"lat": -23.5484654,
"lon": -46.6364675
}
},
"type": "ROAD",
"label": "RUA SÃO BENTO, 01011000, CENTRO, SÃO PAULO, SP",
"score": 71.7179494374621,
"precision": "ROAD_CENTROID"
},
{
"id": "6684345af0662a1541f65d6b",
"address": {
"road": "RUA SANTO ANTÔNIO",
"district": "BELA VISTA",
"zipCode": "01314000",
"city": "SÃO PAULO",
"state": {
"name": "SÃO PAULO",
"code": "SP"
},
"mainLocation": {
"lat": -23.552029,
"lon": -46.645678
}
},
"type": "ROAD",
"label": "RUA SANTO ANTÔNIO, 01314000, BELA VISTA, SÃO PAULO, SP",
"score": 70.22344421543498,
"precision": "ROAD_CENTROID"
}
],
"found": 10
}
