Search by coordinates (reverse geocoding)
To search for an object by coordinates, specify the point coordinates in the lon and lat parameters in a GET request to /3.0/items/geocode: for details, see the Search by point coordinates section. To obtain the address of the object and the administrative units it belongs to in the response, specify the fields=items.adm_div,items.address parameter in the request.
You can also search by coordinates for:
- objects within a radius around a point
- building entrances
- particular object types
Search by point coordinates
When you search by point coordinates, the search radius is zero: only the address of the point you specified is returned. If the specified coordinates belong to a building, the response will contain the address of that building. If the coordinates are outside the building's boundaries, the response will only contain the administrative units (e.g., districts) to which the point belongs.
To obtain the address of a building, specify the exact coordinates within its boundaries. If you do not know the exact coordinates and want to find the closest building to the point, use search within a radius around the point.
To obtain the point address, send a GET request to /3.0/items/geocode with the following parameters:
lon- longitude of the search point, for examplelon=37.609256.lat- latitude of the search point, for examplelat=55.770784.fields=items.adm_div,items.address- includes fields with administrative units and the object address in the response.
Request example:
https://catalog.api.2gis.com/3.0/items/geocode?lon=37.609256&lat=55.770784&fields=items.adm_div,items.address&key=API_KEY
Response example:
response.json
{
"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
}
}
Search within a radius around a point
Using the radius parameter, you can find all objects within a radius around a point. The point can be specified using the point parameter or a pair of lon and lat parameters.
The maximum radius is 2,000 m. If the address is specified in the request as a text query (q parameter), the maximum radius is 50,000 m: see the request example for direct geocoding.
To specify a search radius, send a GET request to /3.0/items/geocode with the following parameters:
lon- longitude of the search point, for examplelon=37.609484.lat- latitude of the search point, for examplelat=55.770763.radius- search radius in meters, for exampleradius=50.fields=items.adm_div,items.address- includes fields with administrative units and the object address in the response.
Request example:
https://catalog.api.2gis.com/3.0/items/geocode?lon=37.609484&lat=55.770763&radius=50&fields=items.adm_div,items.address&key=API_KEY
Response example:
response.json
{
"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"
},
{
"address": {
"building_id": "4504235282731438",
"components": [
{
"number": "3 ст1",
"street": "улица Каретный Ряд",
"street_id": "4504338361748615",
"type": "street_number"
}
],
"landmark_name": "сад Эрмитаж",
"postcode": "127006"
},
"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": "Москва, Здание театра Эрмитаж",
"id": "70030077060161708",
"name": "Здание театра Эрмитаж",
"since": "Построено в 1839 г., перестроено в 1869, 1875, 1880-х, 1890-х, 1947-1948 гг.",
"subtype": "landmark",
"subtype_name": "интересное здание",
"type": "attraction"
},
{
"color": "grey",
"full_name": "Москва, Эрмитаж и окрестности: театральная прогулка по Москве",
"id": "70030077100004517",
"name": "Эрмитаж и окрестности: театральная прогулка по Москве",
"subtype": "tourist_other",
"subtype_name": "Культурный маршрут",
"type": "road"
},
{
"color": "grey",
"full_name": "Москва, Маршрут Пробежка",
"id": "70030077124281128",
"name": "Маршрут Пробежка",
"subtype": "tourist_other",
"subtype_name": "Прогулочный маршрут",
"type": "road"
},
{
"address": {
"landmark_name": "сад Эрмитаж"
},
"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": "Москва, Сцена",
"id": "4504295434271768",
"name": "Сцена",
"subtype": "stage",
"subtype_name": "сцена",
"type": "attraction"
}
],
"total": 24
}
}
Search for building entrances
To find entrances in the building nearest to a specified point, send a GET request to /3.0/items/geocode with the following parameters:
-
lon- longitude of the search point, for examplelon=37.609376. -
lat- latitude of the search point, for examplelat=55.772302. -
type=building- search for objects with the "building" type. -
radius- search radius in meters, for exampleradius=10. -
fields- list of fields to return in the response:items.adm_div- administrative units.items.address- object address.items.links.database_entrances- coordinates of the building entrances (requires additional key permission).
Request example:
https://catalog.api.2gis.com/3.0/items/geocode?lon=37.609376&lat=55.772302&type=building&radius=10&fields=items.adm_div,items.address,items.links.database_entrances&key=API_KEY
Response example:
response.json
{
"meta": {
"api_version": "3.0.21070",
"code": 200,
"issue_date": "20260806"
},
"result": {
"items": [
{
"address": {
"building_id": "4504235282731036",
"components": [
{
"number": "5/10 ст2",
"street": "улица Каретный Ряд",
"street_id": "4504338361748615",
"type": "street_number"
},
{
"number": "10",
"street": "Садовая-Каретная улица",
"street_id": "4504338361749472",
"type": "street_number"
}
],
"postcode": "127006"
},
"address_name": "улица Каретный Ряд, 5/10 ст2 / Садовая-Каретная улица, 10",
"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": "Москва, улица Каретный Ряд, 5/10 ст2 / Садовая-Каретная улица, 10",
"id": "4504235282731036",
"links": {
"database_entrances": [
{
"entity_name": "1 подъезд",
"entity_number": "1",
"geometry": {
"points": [
"POINT(37.608825 55.772113)"
]
},
"id": "70030076156473825",
"is_primary": false
},
{
"entity_name": "2 подъезд",
"entity_number": "2",
"geometry": {
"points": [
"POINT(37.609389 55.772308)"
],
},
"id": "70030076156473891",
"is_primary": false
},
...
]
},
"name": "улица Каретный Ряд, 5/10 ст2 / Садовая-Каретная улица, 10",
"purpose_name": "Жилой дом",
"type": "building"
}
],
"total": 1
}
}
Search by object type
Using the type parameter, you can search for objects of a particular type: buildings, streets, parking lots, stops, landmarks, and others. For the full list of object types, see the API reference.
To find objects of a particular type, send a GET request to /3.0/items/geocode with the following parameters:
lon- longitude of the search point, for examplelon=37.609484.lat- latitude of the search point, for examplelat=55.770763.type- object type, for exampletype=buildingto search for buildings.fields=items.adm_div,items.address- includes fields with administrative units and the object address in the response.
Request example:
https://catalog.api.2gis.com/3.0/items/geocode?lon=37.609484&lat=55.770763&type=building&fields=items.adm_div,items.address&key=API_KEY
Response example:
response.json
{
"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"
}
],
"total": 1
}
}