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: 

• https://api.maplink.global/geocode/v2/geocode – POST

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, district, city, state”.

Note: There is a limit of 200 points for sending in a single request.

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 lat and lon properties 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"
  • radius – Search radius, in meters, from the central point defined in center. If not entered, the default value is 5,000,000 meters (5,000 km).

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"
}

In both cases, the following information is returned in the response:

• found – Number of records returned.
• results – Array of objects with all the results found:
  • id – Address identifier provided in the request;
  • address – Object with address information:
    • road – Name of the road;
    • district – District;
    • zipCode – Zipcode;
    • city – City;
    • state – State;
    • mainLocation – Object with the geographic coordinates of the point:
      • lat – Latitude;
      • lon – Longitude;
    • numberAsInteger – Address number, but returned as an integer instead of a string;
  • type – Indicates the best element found in the cartographic database for returning the geographic coordinate;
  • score – Reference score of the result of the geocoding process;
  • label – Complete address found used in the geocoding process.

The full response can be found below:

{
    "found": 1,
    "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.566329468025202,
                    "lon": -46.653621381930805
                },
                "numberAsInteger": 579
            },
            "type": "ROAD",
            "label": "ALAMEDA CAMPINAS, 01404000, JARDIM PAULISTA, SÃO PAULO, SP",
            "score": 100.0
        }
    ]

Note: The higher the score, the greater the relevance of the result for the requested address. For example, if the request has all the address elements filled in and they were found in the cartographic database, a higher score is expected. If the request only has a zip code, for example, the score will be lower.

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:

{
    "found": 1,
    "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
        }
    ]
}