Reverse Geocoding API

Mapcat Reverse Geocoding API is used to retrieve information about the address and the objects at a specific geo-location.

You can find a detailed description of the request parameters and the response scheme of the API point in our swagger documentation.

To access this API, you will need to use your Search API key.

Example

Here is a simple javascript example below showing how to use our Search API from browser:

var req = new XMLHttpRequest();

var reqListener = function(e) {
    console.log(req.response); // logging the reverse geocoded result to console
};
req.addEventListener('load', reqListener);
req.open('GET', 'https://api.mapcat.com/location/invgeocode?lat=46.062330862&lng=11.122249671', true);
req.setRequestHeader('X-Api-Key', '< Your MAPCAT Search API key >');
req.send(null);

Parameters

  • lat and lng parameters are mandatory. They represent the latitude and longitude of the geo-coordinate of the reverse geocoded request.
  • lang: this optional string parameter is the two-letter ISO 639-1 code of the language we want to retrieve the reverse geocoded results in. Examples:

    • "en": English
    • "de": German
    • "zh": Chinese

      When not present, the values would be returned in the default language of the found map elements.

  • osmidx: this parameter is also optional. It is used for making an reverse geocoding request with the OSM identifier of a specific POI (point-of-interest). If the reverse geocode engine finds the specified object close to the given lat and lng geo-location, it returns extra data about that specific POI in the poiattr field of the result (see response description below). This parameter is useful when there are a lot of POIs close to each other and you would like to select one to get detailed information about.

Response

The response is a json object. It contains meta and result fields. The meta field has version, status_code and message values. Field version represents the version of the Reverse Geocoding API engine, the status_code is equal to the http status code of the response, and the message string field contains a detailed error message if any.

When there was no error during the reverse geocode request, field result is specified. It is an object having the following fields:

  • address is an object. It contains the full address at the result as a formed text field, as well as the address parts of the found address in a categorized way (e.g.: country, state, city, district...). For a full list of address parts, look up our swagger documentation.
  • poi in case there is a POI close to the geo-location of the reverse geocoded point, then the name, OSM id (osmidx) and geolocation (pos) of the POI are given in this field.
  • pois: this field is an array, holding information about the POIs nearby in the same way as the poi field does. POIs closer to the reverse geocoded point comes earlier in the list.
  • shapes is an array containing the names of the shapes at the reverse geocoded location. It can contain the name of parks, woods, lakes, etc.
  • The poiattr parameter is only present, if the osmidx query parameter was supplied (see above). This field contains every attribute available (from OSM) of the specified POI. These are:
    • "name": the name of the POI
    • "stname": the name of the street the POI belongs to
    • "hnum": the house number of the POI
    • "postcode": the postal code of the POI
    • "telnum": the telephone number of the POI
    • "email": the email address of the POI
    • "url": the url of the website of the POI