Overview
The Geocoder API allows you to convert object coordinates to an address and vice versa, an address to coordinates.
Usage example
Click the map to find out an object address.
Click on the map to see the URL of the API request
You can also work with the Geocoder API in the playground inside your account (no authorization required).
Main features
You can use:
- Direct geocoding: determine an object coordinates by its address. For example, you can specify a delivery address on the map and get the object's coordinates: the query
Moskva, ulitsa Karetny Ryad, 3, st1will return the coordinates55.770784, 37.609256. - Reverse geocoding: determine an object address by its coordinates. For example, you can specify a point on the map and get the address of the building closest to that point: the query
55.770784, 37.609256will return the addressMoskva, ulitsa Karetny Ryad, 3, st1.
You can also handle search results: sort them, obtain the required page, etc. For details about each parameter, see the API Reference and the Examples section.
Learn about features of other search APIs to enrich your scenarios of working with objects on the map. For example, to provide suggestions when searching for objects, use the Suggest API. 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
Obtaining certain information about objects is only available on demand and for an extra cost. To purchase access to the methods and fields below, contact the 2GIS sales team.
Fields (specified using the fields parameter):
items.contact_groups- organization contactsitems.floors- number of floorsitems.floor_plans- floor plansitems.links.database_entrances.apartments_info- information about apartments in the buildingitems.employees_org_count- number of employees in the organizationitems.itin- individual taxpayer identification numberitems.trade_license- branch trade licenseitems.fias_code- code of streets or administrative territories in the Federal Information Address Systemitems.address.components.fias_code- code of buildings in the Federal Information Address Systemitems.fns_code- Federal Tax Service code of administrative territoriesitems.okato- code of streets and administrative territories in the National Classifier of Administrative Territorial Entitiesitems.address.components.okato- code of buildings in the National Classifier of Administrative Territorial Entitiesitems.oktmo- code of streets and administrative territories in the National Classification of Territories of Municipal Formationsitems.address.components.oktmo- code of buildings in the National Classification of Territories of Municipal Formationsitems.structure_info.material- building material dataitems.structure_info.apartments_count- number of apartments in the buildingitems.structure_info.porch_count- number of entrances in the buildingitems.structure_info.floor_type- floor type in the buildingitems.structure_info.gas_type- type of gas supply in the buildingitems.structure_info.year_of_construction- year of building constructionitems.structure_info.elevators_count- number of elevators in the buildingitems.structure_info.is_in_emergency_state- whether the building is considered to be in emergency stateitems.structure_info.project_type- series or a project of building constructionitems.structure_info.chs_name- name of the cultural heritage siteitems.structure_info.chs_category- category of the cultural heritage site
Getting started
Follow the steps below to become familiar with Geocoder API features and send requests to search for objects by address and coordinates.
Getting access key
-
Sign in to the Platform Manager.
-
Create a demo key or purchase a subscription for using API. For details on service prices, see the Tariffs section.
Data on demandTo obtain certain information about objects, an additional permission is required. Check the list of methods and fields for obtaining additional information on demand.
For more information on working with access keys and subscriptions, see the account documentation.
Use the 2GIS MCP server to access geodata when working with AI agents.
Request example
Direct geocoding
A request to the Geocoder API for direct geocoding must contain:
- The address of the object to obtain the coordinates. To improve search accuracy, specify a locality or region in the text query or other georestriction. For more information, see the Search by address instruction.
- The
fields=items.point,items.geometry.centroidfield to obtain the object coordinates in the response. - Your API key.
To obtain coordinates for an object by its address, send a GET request to /3.0/items/geocode:
https://catalog.api.2gis.com/3.0/items/geocode?q=Moskva, ulitsa Karetny Ryad, 3&fields=items.point,items.geometry.centroid&key=API_KEY
In the request, specify:
q=Moskva, ulitsa Karetny Ryad, 3- text query for searching for an object by address.fields=items.point,items.geometry.centroid- includes fields with object coordinates in the response.key=API_KEY- API key value.
Reverse geocoding
A request to the Geocoder API for reverse geocoding must contain:
- The coordinates of the point to obtain the address.
- The
fields=items.adm_div,items.addressfield to obtain the object address and the administrative units it belongs to in the response. - Your API key.
To obtain the address of an object by its coordinates, send a GET request to /3.0/items/geocode:
https://catalog.api.2gis.com/3.0/items/geocode?lon=37.609484&lat=55.770763&fields=items.adm_div,items.address&key=API_KEY
In the request, specify:
lon=37.609484- point longitude.lat=55.770763- point latitude.fields=items.adm_div,items.address- includes fields with administrative units and the object address in the response.key=API_KEY- API key value.
Response example
Responses to requests are returned in JSON format.
Direct geocoding
Response example:
{
"meta": {
"api_version": "3.0.21070",
"code": 200,
"issue_date": "20260806"
},
"result": {
"items": [
{
"address_name": "улица Каретный Ряд, 3 ст1",
"full_name": "Москва, улица Каретный Ряд, 3 ст1",
"geometry": {
"centroid": "POINT(37.609256 55.770784)"
},
"id": "4504235282731438",
"name": "улица Каретный Ряд, 3 ст1",
"point": {
"lat": 55.770784,
"lon": 37.609256
},
"purpose_name": "Культурно-развлекательный комплекс",
"type": "building"
}
],
"total": 1
}
}
Where:
-
result.items- array of objects matching the query. Each object contains:address_name- object address.full_name- full name of the object.geometry.centroid- coordinates of the object's center.id- object ID.name- object name.point- object coordinates.purpose_name- object purpose.type- object type.
-
result.total- total number of objects matching the query.
To receive additional fields in the response, specify them in the fields request parameter. For details about each parameter, see the API Reference.
Reverse geocoding
Response example:
{
"meta": {
"api_version": "3.0.21070",
"code": 200,
"issue_date": "20260806"
},
"result": {
"items": [
{
"address": {
"building_id": "4504235282731438",
"components": [
{
"number": "3 ст1",
"street": "улица Каретный Ряд",
"street_id": "4504338361748615",
"type": "street_number"
}
],
"landmark_name": "сад Эрмитаж",
"postcode": "127006"
},
"address_name": "улица Каретный Ряд, 3 ст1",
"adm_div": [
{
"id": "1",
"name": "Россия",
"type": "country"
},
{
"id": "5349042514588558",
"name": "Москва",
"type": "region"
},
{
"city_alias": "moscow",
"flags": {
"is_default": true,
"is_region_center": true
},
"id": "4504222397630173",
"is_default": true,
"name": "Москва",
"type": "city"
},
{
"id": "4504209512726536",
"name": "Тверской",
"type": "district"
}
],
"full_name": "Москва, улица Каретный Ряд, 3 ст1",
"id": "4504235282731438",
"name": "улица Каретный Ряд, 3 ст1",
"purpose_name": "Культурно-развлекательный комплекс",
"type": "building"
},
{
"adm_div": [
{
"id": "1",
"name": "Россия",
"type": "country"
},
{
"id": "5349042514588558",
"name": "Москва",
"type": "region"
},
{
"city_alias": "moscow",
"flags": {
"is_default": true,
"is_region_center": true
},
"id": "4504222397630173",
"is_default": true,
"name": "Москва",
"type": "city"
}
],
"full_name": "Москва, Сад Эрмитаж",
"id": "4504286822140845",
"name": "Сад Эрмитаж",
"subtype": "place",
"type": "adm_div"
},
{
"adm_div": [
{
"id": "1",
"name": "Россия",
"type": "country"
},
{
"id": "5349042514588558",
"name": "Москва",
"type": "region"
},
{
"city_alias": "moscow",
"flags": {
"is_default": true,
"is_region_center": true
},
"id": "4504222397630173",
"is_default": true,
"name": "Москва",
"type": "city"
}
],
"full_name": "Москва, Тверской",
"id": "4504209512726536",
"name": "Тверской",
"subtype": "district",
"type": "adm_div"
},
{
"adm_div": [
{
"id": "1",
"name": "Россия",
"type": "country"
},
{
"id": "5349042514588558",
"name": "Москва",
"type": "region"
},
{
"city_alias": "moscow",
"flags": {
"is_default": true,
"is_region_center": true
},
"id": "4504222397630173",
"is_default": true,
"name": "Москва",
"type": "city"
}
],
"full_name": "Москва, Центральный административный округ",
"id": "4504647599390721",
"name": "Центральный административный округ",
"subtype": "division",
"type": "adm_div"
},
{
"adm_div": [
{
"id": "1",
"name": "Россия",
"type": "country"
},
{
"id": "5349042514588558",
"name": "Москва",
"type": "region"
}
],
"full_name": "Москва",
"id": "4504222397630173",
"name": "Москва",
"subtype": "city",
"type": "adm_div"
},
{
"full_name": "Москва город федерального значения",
"id": "5349042514588558",
"name": "Москва город федерального значения",
"subtype": "region",
"type": "adm_div"
}
],
"total": 6
}
}
Where:
-
result.items- array of objects matching the query. Each object contains:-
address- object address:building_id- building ID.components- array of object address components.landmark_name- name of landmarks located near the object.postcode- object postal code.
-
address_name- object address. -
adm_div- administrative units the object address belongs to. -
full_name- full name of the object. -
id- object ID. -
name- object name. -
purpose_name- object purpose. -
subtype- object subtype. -
type- object type.
-
-
result.total- total number of objects matching the query.
To receive additional fields in the response, specify them in the fields request parameter. For details about each parameter, see the API Reference.
Tariffs and limits
-
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.codefield of the response. Example:{
"meta": {
"api_version": "3.0.17799",
"code": 200,
"issue_date": "20240524"
},
...
} -
For demo keys and keys created in a subscription, service usage limits apply.
-
See current prices and limits in the Prices instruction.
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 the AI assistant (in the lower-right corner of the 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.
What's next?
- Examples of using Geocoder API.
- API Reference.