Geocode

Reverse Geocode API

The purpose of this second endpoint, Reverse Geocode, is to return information about the address from its coordinates.

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

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

List of parameters

Mandatory parameters

  • lat – Latitude;
  • lon – Longitude.

Optional parameters

  • id – Text with the identifier of the searched address;
  • distance – Maximum distance in meters for the address search.

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

Example 1 – Searching for the address from the coordinate

[
    {
        "lat": -23.566617861455924, 
        "lon": -46.65362331449377
    }
]

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;
    • distance – Distance in meters from the coordinate sent;
    • label – Complete address found used in the geocoding process.

Note: The higher the score, the greater the relevance of the result to the requested address.

The full response can be found below:

{
    "found": 1,
    "results": [
        {
            "id": "1034bf0c-8d7a-474c-8eb1-6a0108882054",
            "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": 9976.046,
            "distance": 23.95446729752212,
            "label": "Alameda Campinas, Jardim Paulista, 01404000, São Paulo, São Paulo, SP"
        }
    ]
}

Example 2 – Searching for an address from more than one coordinate

In this example, we will search for results for two different coordinates. To do this, we need to identify them with the parameter id. The first point will be "L1" and the second "L2".

The point "L1" must return results within a radius of 25 meters. For this we use the parameter distance.

The full request can be found below:

{
    "found": 2,
    "results": [
        {
            "id": "L1",
            "address": {
                "road": "Rua Leopoldo Hess",
                "district": "São João",
                "zipCode": "88304260",
                "city": "Itajaí",
                "state": {
                    "code": "SC",
                    "name": "Santa Catarina"
                },
                "mainLocation": {
                    "lat": -26.90309606687984,
                    "lon": -48.68019337952068
                },
                "geometry": [
                    {
                        "lat": -26.90371956910269,
                        "lon": -48.6800353812277
                    },
                    {
                        "lat": -26.90247256465699,
                        "lon": -48.68035137781368
                    }
                ],
                "leftZipCode": "88304260",
                "rightZipCode": "88304260",
                "leftFirstNumber": 2,
                "leftLastNumber": 244,
                "rightFirstNumber": 1,
                "rightLastNumber": 161
            },
            "type": "ROAD",
            "score": 9994.67,
            "distance": 5.329992775797795,
            "label": "Rua Leopoldo Hess, São João, 88304260, Itajaí, Santa Catarina, SC"
        },
        {
            "id": "L2",
            "address": {
                "road": "Avenida Gov. Adolfo Konder",
                "district": "Cidade Nova",
                "zipCode": "88308001",
                "city": "Itajaí",
                "state": {
                    "code": "SC",
                    "name": "Santa Catarina"
                },
                "mainLocation": {
                    "lat": -26.908718086920004,
                    "lon": -48.67877389320046
                },
                "geometry": [
                    {
                        "lat": -26.908539588131305,
                        "lon": -48.67824538861362
                    },
                    {
                        "lat": -26.908896585708703,
                        "lon": -48.679302397787296
                    }
                ],
                "leftZipCode": "88308001",
                "rightZipCode": "88308000",
                "leftFirstNumber": 231,
                "leftLastNumber": 531,
                "rightFirstNumber": 232,
                "rightLastNumber": 532
            },
            "type": "ROAD",
            "score": 9969.358,
            "distance": 30.641980035785615,
            "label": "Avenida Gov. Adolfo Konder, Cidade Nova, 88308001, Itajaí, Santa Catarina, SC"
        }
    ]
}