Overview | 2GIS Documentation
Geocoder API

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.

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.

Click on the map to see the URL of the API request

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


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 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.


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

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

  1. Get an access key:

    1. Sign in to the Platform Manager.
    2. Create a demo key or purchase an access key for using API: see the Access keys instruction.

    To work with access keys, you can use the Platform Manager: see the Platform Manager section.

  2. Learn about the request and response formats.

  3. Check the examples of the Geocoder API requests.