Поиск по координатам (обратное геокодирование)
Для поиска объекта по координатам укажите координаты точки в параметрах lon и lat в GET-запросе к /3.0/items/geocode: см. подробнее в разделе Поиск по координатам точки. Чтобы получить в ответе адрес объекта и административные единицы, которым он принадлежит, укажите в запросе параметр fields=items.adm_div,items.address.
Также вы можете искать по координатам:
- объекты, находящиеся в радиусе вокруг точки;
- входы в здание;
- определённые типы объектов.
Поиск по координатам точки
При поиске по координатам точки радиус поиска равен нулю: возвращается адрес только той точки, которую вы указали. Если указанные координаты принадлежат зданию, в ответе будет адрес этого здания. Если координаты не попадают в границы здания, в ответе будут только административные единицы (например, район), к которым относится точка.
Чтобы получить адрес здания, указывайте точные координаты, находящиеся внутри его границ. Если вы не знаете точные координаты и хотите найти ближайшее здание к точке, используйте поиск в радиусе вокруг точки.
Чтобы получить адрес точки, отправьте GET-запрос к /3.0/items/geocode со следующими параметрами:
lon— долгота точки поиска, напримерlon=37.609256.lat— широта точки поиска, напримерlat=55.770784.fields=items.adm_div,items.address— включает в ответ поля с административными единицами и адресом объекта.
Пример запроса:
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.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
}
}
Поиск в радиусе вокруг точки
С помощью параметра radius вы можете найти все объекты в радиусе вокруг точки. Точку можно задать с помощью параметра point или пары параметров lon и lat.
Максимальный радиус — 2 000 м. Если в запросе указан адрес в виде текстового запроса (параметр q), максимальный радиус — 50 000 м: см. пример запроса для прямого геокодирования.
Чтобы указать радиус поиска, отправьте GET-запрос к /3.0/items/geocode со следующими параметрами:
lon— долгота точки поиска, напримерlon=37.609484.lat— широта точки поиска, напримерlat=55.770763.radius— радиус поиска в метрах, напримерradius=50.fields=items.adm_div,items.address— включает в ответ поля с административными единицами и адресом объекта.
Пример запроса:
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.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
}
}
Поиск входов в здание
Чтобы найти входы в здание (подъезды), ближайшее к указанной точке, отправьте GET-запрос к /3.0/items/geocode со следующими параметрами:
-
lon— долгота точки поиска, напримерlon=37.609376. -
lat— широта точки поиска, напримерlat=55.772302. -
type=building— поиск объектов с типом «здание». -
radius— радиус поиска в метрах, напримерradius=10. -
fields— список полей, которые нужно вернуть в ответе:items.adm_div— административные единицы.items.address— адрес объекта.items.links.database_entrances— координаты входов в здание (требуется дополнительное разрешение ключа).
Пример запроса:
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.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
}
}
Поиск по типу объекта
С помощью параметра type вы можете искать объекты определённого типа: здания, улицы, парковки, остановки, достопримечательности и другие. Полный список типов объектов см. в справочнике API.
Чтобы найти объекты определённого типа, отправьте GET-запрос к /3.0/items/geocode со следующими параметрами:
lon— долгота точки поиска, напримерlon=37.609484.lat— широта точки поиска, напримерlat=55.770763.type— тип объекта, напримерtype=buildingдля поиска зданий.fields=items.adm_div,items.address— включает в ответ поля с административными единицами и адресом объекта.
Пример запроса:
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.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
}
}