Поиск по адресу (прямое геокодирование)

Для поиска объекта по адресу укажите адрес в параметре q в GET-запросе к /3.0/items/geocode: см. подробнее в разделе Поиск по адресу в текстовом запросе. Чтобы получить в ответе координаты объекта, укажите в запросе параметр fields=items.point,items.geometry.centroid.

Также вы можете искать по адресу:

объекты с указанием геоограничения (необходимо, если населённый пункт не указан в параметре q);
координаты входа в здание;
определённые типы объектов.

Поиск по адресу в текстовом запросе

Вы можете указать в параметре q адрес с названием населённого пункта: города, посёлка и т. д. Например, «улица Каретный ряд, 3, Москва», «Проспект Мира, 26 ст1, Москва» и т. д.

Если вы не указываете населённый пункт, для ограничения области поиска укажите геоограничение. В противном случае поиск может не дать результатов, даже если объект с указанным адресом существует.

Для небольших населённых пунктов (например, деревень) рекомендуется указывать название вместе с названием области и другими объединениями, к которым он относится (например, сельским или городским поселением).

Чтобы получить координаты объекта, отправьте GET-запрос к /3.0/items/geocode со следующими параметрами:

q — текстовый запрос с адресом, который содержит населённый пункт, например «улица Каретный ряд, 3, Москва».
fields=items.point,items.geometry.centroid — включает в ответ поля с координатами объекта.

Пример запроса:

https://catalog.api.2gis.com/3.0/items/geocode?q=улица Каретный ряд, 3, Москва&fields=items.point,items.geometry.centroid&key=API_KEY

Пример ответа:

response.json

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

Поиск с геоограничением

Вы можете указать геоограничение поиска в виде:

координат точки поиска;
радиуса вокруг точки;
прямоугольной области;
произвольной области;
области видимости;
региона;
города;
территории;
станции метро, рядом с которой выполнится поиск.

Одновременно нельзя указывать геоограничения по радиусу, произвольной области и прямоугольной области (параметры point, polygon, point1/point2).

Координаты точки

С помощью параметра location вы можете задать ограничение поиска по координатам точки. В ответе первыми будут выведены наиболее близкие к точке объекты. Населённый пункт в текстовом запросе при этом можно не указывать.

Чтобы указать точку в качестве области поиска, отправьте GET-запрос к /3.0/items/geocode со следующими параметрами:

q — текстовый запрос с адресом, например «улица Каретный ряд, 3».
location — координаты точки поиска в формате долгота,широта, например location=37.623056,55.752344.
fields=items.point,items.geometry.centroid — включает в ответ поля с координатами объекта.

Пример запроса:

https://catalog.api.2gis.com/3.0/items/geocode?q=улица Каретный ряд, 3&location=37.623056,55.752344&fields=items.point,items.geometry.centroid&key=API_KEY

Пример ответа:

response.json

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

Радиус вокруг точки

С помощью параметра radius вы можете ограничить результаты поиска радиусом вокруг точки. Точку можно задать с помощью параметра point или пары параметров lon и lat. Населённый пункт в текстовом запросе при этом можно не указывать.

Максимальный радиус — 2 000 м. Если в запросе указан адрес в виде текстового запроса (параметр q), максимальный радиус — 50 000 м (см. пример запроса для обратного геокодирования).

Чтобы указать радиус поиска, отправьте GET-запрос к /3.0/items/geocode со следующими параметрами:

q — текстовый запрос с адресом, например «улица Каретный ряд, 3».
point — координаты центра точки поиска в формате долгота,широта, например point=37.623056,55.752344.
radius — радиус поиска в метрах, например radius=10000.
fields=items.point,items.geometry.centroid — включает в ответ поля с координатами объекта.

Пример запроса:

https://catalog.api.2gis.com/3.0/items/geocode?q=улица Каретный ряд, 3&point=37.623056,55.752344&radius=10000&fields=items.point,items.geometry.centroid&key=API_KEY

Пример ответа:

response.json

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

Прямоугольная область

С помощью параметров point1 и point2 вы можете ограничить результаты поиска прямоугольной областью, задав координаты левого верхнего и правого нижнего углов области. Максимальное расстояние между точками — два километра. Населённый пункт в текстовом запросе при этом можно не указывать.

Чтобы указать прямоугольную область поиска, отправьте GET-запрос к /3.0/items/geocode со следующими параметрами:

q — текстовый запрос с адресом, например «улица Каретный ряд, 3».
point1 — координаты левого верхнего угла прямоугольной области в формате долгота,широта, например 37.606789,55.771235.
point2 — координаты правого нижнего угла прямоугольной области в формате долгота,широта, например 37.611516,55.769179.
fields=items.point,items.geometry.centroid — включает в ответ поля с координатами объекта.

Пример запроса:

https://catalog.api.2gis.com/3.0/items/geocode?q=улица Каретный ряд, 3&point1=37.606789,55.771235&point2=37.611516,55.769179&fields=items.point,items.geometry.centroid&key=API_KEY

Пример ответа:

response.json

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

Произвольная область

С помощью параметра polygon вы можете ограничить результаты поиска произвольной областью, задав координаты вершин полигона. Населённый пункт в текстовом запросе при этом можно не указывать.

Чтобы указать произвольную область поиска (полигон), отправьте GET-запрос к /3.0/items/geocode со следующими параметрами:

q — текстовый запрос с адресом, например «улица Каретный ряд, 3».
polygon — координаты вершин полигона в формате WKT.
fields=items.point,items.geometry.centroid — включает в ответ поля с координатами объекта.

Пример запроса:

https://catalog.api.2gis.com/3.0/items/geocode?q=улица Каретный ряд, 3&polygon=POLYGON((37.604943 55.772081, 37.609896 55.773073, 37.612378 55.770239, 37.605307 55.76913, 37.604943 55.772081))&fields=items.point,items.geometry.centroid&key=API_KEY

Пример ответа:

response.json

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

Область видимости

С помощью параметров viewpoint1 и viewpoint2 вы можете ограничить результаты поиска областью видимости (прямоугольной областью карты). В отличие от геоограничения прямоугольной областью, область видимости влияет на ранжирование результатов, но не ограничивает поиск строго заданными границами. Населённый пункт в текстовом запросе при этом можно не указывать.

Чтобы указать область видимости, отправьте GET-запрос к /3.0/items/geocode со следующими параметрами:

q — текстовый запрос с адресом, например «улица Каретный ряд, 3».
viewpoint1 — координаты левого верхнего угла прямоугольной области в формате долгота,широта, например 37.606789,55.771235.
viewpoint2 — координаты правого нижнего угла прямоугольной области в формате долгота,широта, например 37.611516,55.769179.
fields=items.point,items.geometry.centroid — включает в ответ поля с координатами объекта.

Пример запроса:

https://catalog.api.2gis.com/3.0/items/geocode?q=улица Каретный ряд, 3&viewpoint1=37.606789,55.771235&viewpoint2=37.611516,55.769179&fields=items.point,items.geometry.centroid&key=API_KEY

Пример ответа:

response.json

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

Регион

С помощью параметра region_id вы можете ограничить результаты поиска регионом, задав его идентификатор. Максимальное количество регионов в запросе — 50. Населённый пункт в текстовом запросе при этом можно не указывать.

Чтобы указать регион в качестве области поиска, отправьте GET-запрос к /3.0/items/geocode со следующими параметрами:

q — текстовый запрос с адресом, например «улица Каретный ряд, 3».
region_id — ID региона, например region_id=32. ID регионов не связаны с кодами субъектов РФ. Подробнее о получении ID см. в разделе ID региона.
fields=items.point,items.geometry.centroid — включает в ответ поля с координатами объекта.

Пример запроса:

https://catalog.api.2gis.com/3.0/items/geocode?q=улица Каретный ряд, 3&region_id=32&fields=items.point,items.geometry.centroid&key=API_KEY

Пример ответа:

response.json

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

Город

С помощью параметра city_id вы можете ограничить результаты поиска городом, задав его идентификатор. Максимальное количество городов в запросе — 50. Населённый пункт в текстовом запросе при этом можно не указывать.

Чтобы указать город в качестве области поиска, отправьте GET-запрос к /3.0/items/geocode со следующими параметрами:

q — текстовый запрос с адресом, например «улица Каретный ряд, 3».
city_id — ID города, например city_id=4504222397630173. Можно использовать несколько ID, разделённых запятыми, например city_id=4504222397630173,4504222397630174. Подробнее о получении ID см. в разделе ID города.
fields=items.point,items.geometry.centroid — включает в ответ поля с координатами объекта.

Пример запроса:

https://catalog.api.2gis.com/3.0/items/geocode?q=улица Каретный ряд, 3&city_id=4504222397630173&fields=items.point,items.geometry.centroid&key=API_KEY

Пример ответа:

response.json

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

Территория

С помощью параметра place_id вы можете ограничить результаты поиска территорией, задав её идентификатор. Территории — это площадные объекты: парки, пляжи, базы отдыха, озёра и прочие места. Максимальное количество территорий в запросе — 50. Населённый пункт в текстовом запросе при этом можно не указывать.

Чтобы указать территорию в качестве области поиска, отправьте GET-запрос к /3.0/items/geocode со следующими параметрами:

q — текстовый запрос с адресом, например «Проспект Мира, 119 ст23».
place_id — ID территории, например place_id=4504286822138302. Можно использовать несколько ID, разделённых запятыми, например place_id=4504286822138302,4504127908543952. Подробнее о получении ID см. в разделе ID территории.
location — координаты точки поиска в формате долгота,широта, например location=37.637635,55.826241.
fields=items.point,items.geometry.centroid — включает в ответ поля с координатами объекта.

Пример запроса:

https://catalog.api.2gis.com/3.0/items/geocode?q=​Проспект Мира, 119 ст23&place_id=4504286822138302&location=37.637635,55.826241&fields=items.point,items.geometry.centroid&key=API_KEY

Пример ответа:

response.json

{
    "meta": {
        "api_version": "3.0.21070",
        "code": 200,
        "issue_date": "20260806"
    },
    "result": {
        "items": [
            {
                "address_name": "проспект Мира, 119 ст23",
                "building_name": "Москвариум, центр океанографии и морской биологии",
                "full_name": "Москва, Москвариум, центр океанографии и морской биологии",
                "geometry": {
                    "centroid": "POINT(37.618523 55.832969)"
                },
                "id": "4504235290763063",
                "name": "Москвариум, центр океанографии и морской биологии",
                "point": {
                    "lat": 55.832969,
                    "lon": 37.618523
                },
                "purpose_name": "Культурно-развлекательный комплекс",
                "type": "building"
            }
        ],
        "total": 1
    }
}

Станция метро

С помощью параметра subway вы можете задать ограничение поиска по станции метро. Максимальное количество станций в запросе — 50. Населённый пункт в текстовом запросе при этом можно не указывать.

Чтобы указать станцию метро, рядом с которой будет выполняться поиск, отправьте GET-запрос к /3.0/items/geocode со следующими параметрами:

q — текстовый запрос с адресом, например «улица Каретный ряд, 3».
subway — ID станции метро, например subway=4504385606388578. Можно использовать несколько ID, разделённых запятыми, например subway=4504385606388578,4504385606390686. Подробнее о получении ID см. в разделе ID станции метро.
location — координаты точки поиска в формате долгота,широта, например location=37.623056,55.752344. Например, вы можете указать координаты любой точки в городе.
fields=items.point,items.geometry.centroid — включает в ответ поля с координатами объекта.

Пример запроса:

https://catalog.api.2gis.com/3.0/items/geocode?q=улица Каретный ряд, 3&subway=4504385606388578&location=37.623056,55.752344&fields=items.point,items.geometry.centroid&key=API_KEY

Пример ответа:

response.json

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

Поиск входа в здание

Чтобы получить координаты входа в здание (подъезда), отправьте GET-запрос к /3.0/items/geocode со следующими параметрами:

q — текстовый запрос с адресом и подъездом, например «Москва, Садовая-Каретная улица, 10, 2 подъезд».
fields — список полей, которые нужно вернуть в ответе:
- items.context — ID входа в здание (подъезда).
- items.point,items.geometry.centroid — координаты объекта.
- items.links.database_entrances — координаты входа в здание (требуется дополнительное разрешение ключа).

Пример запроса:

https://catalog.api.2gis.com/3.0/items/geocode?q=Москва, Садовая-Каретная улица, 10, 2 подъезд&fields=items.context,items.point,items.geometry.centroid,items.links.database_entrances&key=API_KEY

Пример ответа:

response.json

{
    "meta": {
        "api_version": "3.0.21070",
        "code": 200,
        "issue_date": "20260805"
    },
    "result": {
        "items": [
            {
                "address_name": "улица Каретный Ряд, 5/10 ст2 / Садовая-Каретная улица, 10",
                "context": {
                    "entrance_id": "70030076156473891"
                },
                "full_name": "Москва, улица Каретный Ряд, 5/10 ст2 / Садовая-Каретная улица, 10",
                "geometry": {
                    "centroid": "POINT(37.609082 55.772469)"
                },
                "id": "4504235282731036",
                "links": {
                    "database_entrances": [
                        {
                           "entity_name": "2 подъезд",
                           "entity_number": "2",
                           "geometry": {
                              "points": [
                                 "POINT(37.609389 55.772308)"
                              ],
                           },
                           "id": "70030076156473891",
                           "is_primary": false,
                        }
                    ]
                },
                "name": "улица Каретный Ряд, 5/10 ст2 / Садовая-Каретная улица, 10",
                "point": {
                    "lat": 55.772469,
                    "lon": 37.609082
                },
                "purpose_name": "Жилой дом",
                "type": "building"
            }
        ],
        "total": 1
    }
}

Поиск по типу объекта

С помощью параметра type вы можете искать объекты определённого типа: здания, улицы, парковки, остановки, достопримечательности и другие. Полный список типов объектов см. в справочнике API.

Чтобы найти объекты определённого типа, отправьте GET-запрос к /3.0/items/geocode со следующими параметрами:

q — текстовый запрос с адресом, например «Москва, улица Каретный ряд, 3». Вместо населённого пункта в текстовом запросе вы можете указать геоограничение: подробнее см. в разделе Поиск с геоограничением.
type — тип объекта, например type=street для поиска улиц.
fields=items.point,items.geometry.centroid — включает в ответ поля с координатами объекта.

Пример запроса:

https://catalog.api.2gis.com/3.0/items/geocode?q=Москва, улица Каретный ряд, 3&type=street&fields=items.point,items.geometry.centroid&key=API_KEY

Пример ответа:

response.json

{
    "meta": {
        "api_version": "3.0.21070",
        "code": 200,
        "issue_date": "20260806"
    },
    "result": {
        "items": [
            {
                "full_name": "Москва, улица Каретный Ряд",
                "geometry": {
                    "centroid": "POINT(37.610131 55.771827)"
                },
                "id": "4504338361748615",
                "name": "улица Каретный Ряд",
                "point": {
                    "lat": 55.771827,
                    "lon": 37.610131
                },
                "type": "street"
            }
        ],
        "total": 1
    }
}

Поиск по адресу в текстовом запросе​

Поиск с геоограничением​

Координаты точки​

Радиус вокруг точки​

Прямоугольная область​

Произвольная область​

Область видимости​

Регион​

Город​

Территория​

Станция метро​

Поиск входа в здание​

Поиск по типу объекта​

Поиск по адресу в текстовом запросе

Поиск с геоограничением

Координаты точки

Радиус вокруг точки

Прямоугольная область

Произвольная область

Область видимости

Регион

Город

Территория

Станция метро

Поиск входа в здание

Поиск по типу объекта