Geocoder API

The Geocoder API allows you to determine coordinates and get information about an object on the map by its address (direct geocoding) and vice versa, to determine the address of an object on the map by its coordinates (reverse geocoding).

Requests are made using the GET method, all required parameters should be passed in the query string. The responses are generated in the JSON format.

How it works

Click on the map to find out the address.

If a request specifies the address of an object, the Geocoder API returns its geographical coordinates.

Conversely, if you specify the geographic coordinates of the object in the request, then the Geocoder API will return its address.

You can also work with Geocoder API in the playground (no authorization needed).

---

Types of geocoding

Direct geocoding

It is used to determine coordinates of an object by its name or address. For example: the user specifies an address, the address is converted into the coordinates.

Reverse geocoding

Reverse geocoding is used to determine the address of an object by its coordinates. For example: you can select the house closest to the point on the map and get its address.

---

Request and response examples

Direct geocoding request and response (search by address)

An example of a direct geocoding request:

https://catalog.api.2gis.com/3.0/items/geocode?q=Moscow, Sadovnicheskaya, 25&fields=items.point&key=YOUR_KEY

The request takes the following parameters:

• q=Moscow, Sadovnicheskaya, 25 — the address of the building whose coordinates you want to get
• key=YOUR_KEY — your API key

The response includes the desired object and its coordinates.

A sample response in JSON format:

{
    "meta": {
        "api_version": "3.0.426762",
        "code": 200,
        "issue_date": "20200506"
    },
    "result": {
        "items": [
            {
                "address_name": "Sadovnicheskaya, 25",
                "full_name": "Moscow, Sadovnicheskaya, 25",
                "id": "4504235282713264_byBBk7792J2H4609HHH1twkm2H3I62G4163B3843vgfpq72C45J4I1JJ2IH8d4ukD178B744355374H2HJJHGJ268",
                "name": "Sadovnicheskaya 25",
                "point": {
                    "lat": 55.746397,
                    "lon": 37.634369
                },
                "purpose_name": "Residential building with administrative premises",
                "type": "building"
            }
        ],
        "total": 1
    }
}

Reverse geocoding request and response (search by coordinates)

An example of a reverse geocoding request:

https://catalog.api.2gis.com/3.0/items/geocode?lat=55.751508&lon=37.615666&fields=items.point&key=YOUR_KEY

The request takes the following parameters:

• lat=55.75150 — the latitude of the point
• lon=37.615666 — the longitude of the point
• key=YOUR_KEY — your API key

The response includes the object at the point and the coordinates.

A sample response in JSON format:

{
    "meta": {
        "api_version": "3.0.427735",
        "code": 200,
        "issue_date": "20200506"
    },
    "result": {
        "items": [
            {
                "address_name": "Kremlin, 1x",
                "building_name": "State Kremlin Palace",
                "full_name": "Moscow, State Kremlin Palace",
                "id": "4504235282815753_mA8z1A239J66052JH1HHs43phH3I63G74BHB26A5ogfpq7473CJ1I0JJI5AGps16E17941372854H0H2HJJH24d",
                "name": "State Kremlin Palace",
                "point": {
                    "lat": 55.75142,
                    "lon": 37.615606
                },
                "purpose_name": "Cultural institution",
                "type": "building"
            }
        ],
        "total": 1
    }
}

---

Getting Started

1. Get your API key:

   1. Sign in to the Platform Manager.
   2. Create a demo key (if you have not used Urbi products before) or request a production key: follow the link to contact a manager on the API Keys tab.

   In the Platform Manager, you can also:

   • See information on your current keys: which services are enabled, which limit is set for each, when a key will be deactivated, and more.
   • Set restrictions for a key by HTTP headers or by IP and subnet.
   • Check the statistics of request distribution for each key.
   • Test determination of object coordinates in the playground.

2. Learn about the request and response formats.

3. Check the examples of the Geocoder API requests.