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.

Learn about features of other search APIs to enrich your scenarios of working with objects on the map.

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.

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

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.

Getting started

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

To get certain information about objects, an additional permission is required. Check the list of fields for getting additional information on demand.

To work with access keys, you can use the Platform Manager: for details, see the account documentation.
Learn about the request and response formats.
Check the examples of the Geocoder API requests.

Additional information on demand

Getting certain information about objects is only available on demand and for an extra cost. Contact the Urbi sales team to purchase access to the fields below.

The fields are specified in the field parameter.

List

items.contact_groups - detailed contact information of the organization
items.floors - number of floors
items.floor_plans - floor plans
items.links.database_entrances.apartments_info - information about apartments in the building
items.employees_org_count - number of employees of the organization
items.itin - individual tax identification number
items.trade_license - trade license
items.fias_code - code of streets or administrative territories in the Federal Information Address System
items.address.components.fias_code - code of buildings in the Federal Information Address System
items.fns_code - Federal Tax Service code of administrative territories
items.okato - code of streets and administrative territories in the National Classifier of Administrative Territorial Entities
items.address.components.okato - code of buildings in the National Classifier of Administrative Territorial Entities
items.oktmo - code of streets and administrative territories in the National Classification of Territories of Municipal Formations
items.address.components.oktmo - code of buildings in the National Classification of Territories of Municipal Formations
items.structure_info.material - information about the building material
items.structure_info.apartments_count - number of apartments in the building
items.structure_info.porch_count - number of entrances in the building
items.structure_info.floor_type - floor type in the building
items.structure_info.gas_type - type of gas supply in the building
items.structure_info.year_of_construction - year of building construction
items.structure_info.elevators_count - number of elevators in the building
items.structure_info.is_in_emergency_state - whether the building is considered to be in emergency state
items.structure_info.project_type - series or a project of building construction
items.structure_info.chs_name - name of the cultural heritage site
items.structure_info.chs_category - category of the cultural heritage site

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