Overview

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.

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. It is used to determine the address of an object by its coordinates. For example, you can select the building closest to the point on the map and get its address.

Additional features

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

Example usage

Click the map to find out the address.

If you specify the address of an object in the request, the Geocoder API returns its geographical coordinates. If you specify the geographic coordinates of the object in the request, the Geocoder API returns its address.

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

Playground

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

Getting started

Get an access key:
1. Sign in to the Platform Manager.
2. Create a demo key or purchase a subscription for using API. For details on service prices, see the Tariffs section.
Data on demand
To get certain information about objects, an additional permission is required. Check the list of fields for getting additional information on demand.

For more information on working with access keys and subscriptions, see the account documentation.
Study the request and response formats.
Study the examples of requests to the Geocoder API and the full API reference.

If you want to create a search widget on the map, check out the ready-made example of integrating search APIs into a web application.

Additional information on demand

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

The fields are specified in the fields parameter:

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 formats

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 - address of the building whose coordinates you want to get.
key=YOUR_KEY - your API key.

The response is returned in the JSON format and contains the required object and its coordinates:

{
    "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.751508 - latitude of the point.
lon=37.615666 - longitude of the point.
key=YOUR_KEY - your API key.

The response is returned in the JSON format and contains the object at the point and the coordinates:

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

Tariffs

The service fee is calculated based on the number of successful requests per month. A successful API request is a request that returns an HTTP code of 200 in the meta.code field of the response. Example:

{
    "meta": {
        "api_version": "2.0.448950",
        "code": 200,
        "issue_date": "20200629"
    },
    ...
}

See current prices and rate limits in the Prices section.

Deployment options

Cloud-based: all current Geocoder API methods are available through public 2GIS endpoints.
On-Premise: when the 2GIS API platform is installed in a private network, all current Geocoder API methods are available except for geocoding by IP address (/3.0/items/geocode/byip). For more information, see the API Platform for server.

Methods labeled as deprecated are not supported in any deployment options.

Support

If you have any questions while working with the API, ask AI assistant (in the lower-right corner of website), use the documentation search, or send an email to api@2gis.com.
If you would like to discuss the capabilities of the API or its integration with your product, please contact a manager.

Example usage​

Getting started​

Additional information on demand​

Request and response formats​

Direct geocoding request and response (search by address)​

Reverse geocoding request and response (search by coordinates)​

Tariffs​

Deployment options​

Support​