The purpose of this first endpoint is to return the geographical coordinates from a full or partial address.

• List of parameters
• Example 1 – Coordinate search from address
• Example 2 – Coordinate search from the zip code
• Example 3 – International address search

To make the request to the Geocode API you need to send the request using the POST method to the following endpoint:

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

For addresses outside Brazil, you will need to add the query param globalSearch in the URL, as follows: https://api.maplink.global/geocode/v1/geocode?globalSearch=true

List of parameters

Mandatory parameters

It is mandatory to inform at least one. It is not necessary to inform everyone. However, the more information you provide, the more accurate the result will be.

• road – Name of the street or part of it;
• number – Street number. DO NOT enter the complement data.
• city – Name of city;
• state – State;
• country – Country;
• district – Name of the neighborhood;
• zipcode – Zip code;

Optional parameter

• type – Limits the type of research. Only for addresses in Brazil and if the parameter globalSearch is not entered. Possible values:
  • ZIPCODE – Zip code;
  • STATE – State;
  • CITY – City;
  • DISTRICT – Neighborhood.

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

Example 1 – Coordinate search 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 can be found below:

{    
    "road": "Alameda Campinas",
    "number": 579,
    "city": "São Paulo",
    "state": "SP",   
    "zipcode": "01404100" 
}

In the response, the following information is returned:

• found – Number of records returned.
• results – Array of objects with all the results found:
  • id – Identifier of the address entered in the request;
  • address – Object with address information:
    • road – Route name;
    • district – Neighborhood;
    • zipCode – Zip code;
    • city – City;
    • state – State;
    • mainLocation – Geographical coordinates at latitude/longitude;
  • type – Indicates the best element found in the map base for returning the geographic coordinate;
  • score – Reference score for 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": "2342cca0-f4bf-44fb-89da-fae4632d7ff6",
            "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": 66.25707,
            "label": "Alameda Campinas, Jardim Paulista, 01404100, São Paulo, São Paulo, SP"
        }
    ]
}

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

Example 2 – Coordinate search from the zip code

In this example, we’re going to make a request using only the zip code 01014-000:

{
    "zipcode": "01014000"
}

The full response can be found below:

{
    "found": 1,
    "results": [
        {
            "address": {
                "road": "Rua Boa Vista",
                "district": "Centro",
                "zipCode": "01014000",
                "city": "São Paulo",
                "state": {
                    "code": "SP",
                    "name": "São Paulo"
                },
                "mainLocation": {
                    "lat": -23.6424087754,
                    "lon": -46.5619422622
                }
            },
            "type": "ZIPCODE",
            "score": 24.653545,
            "label": "Rua Boa Vista, Centro, 01014000, São Paulo, São Paulo, SP"
        }
    ]
}

Example 3 – International address search

To search for addresses from other countries, you will need to add the parameter globalSearch to the URL, as follows: https://api.maplink.global/geocode/v1/geocode?globalSearch=true

Below we have a request for the address "Av. Córdoba 5869, CABA, Argentina":

{
    "road": "Av. Córdoba",
    "number": 5869,
    "city": "CABA",
    "country":"Argentina"
}

The full response can be found below:

{
    "found": 1
    "results": [
        {
            "address": {
                "road": "Avenida Córdoba",
                "district": "Palermo",
                "zipCode": "C1188AAQ",
                "city": "Buenos Aires",
                "state": {
                    "code": "",
                    "name": "Ciudad Autónoma de Buenos Aires"
                },
                "country": "Argentina",
                "mainLocation": {
                    "lat": -34.5977459,
                    "lon": -58.4198975
                }
            },
            "score": 26.520788,
         "label": "Avenida Córdoba, Palermo, Buenos Aires, Argentina"
        }
   ],
}