Решение частых проблем поиска
При использовании Places API вы можете не найти интересующий вас объект, а также получить неточные или слишком широкие результаты. В инструкции собраны частые проблемы поиска и возможные пути их решения.
Коды ошибок
Сервер будет возвращать код 200, даже если в запросе ошибка. Смотрите код ошибки в поле meta.code в теле ответа, например:
{
"meta": {
"api_version": "3.0.20949",
"code": 404,
"error": {
"message": "Results not found",
"type": "itemNotFound"
},
"issue_date": "20260717"
}
}
| Код | Описание | Решение |
|---|---|---|
| 400 | Некорректный запрос. | Посмотрите описание ошибки в параметре error.message и проверьте параметры запроса. Примеры ошибочных запросов см. в разделе Поиск не даёт результатов. |
| 403 | Доступ запрещён. |
|
| 404 | Объект не найден. | Убедитесь, что параметры запроса указаны без ошибок. Пример ошибочного запроса см. в разделе Поиск не даёт результатов. |
| 408 | Превышено время ожидания. | Повторите запрос позже. |
| 503 | Внутренняя ошибка сервера. | Повторите запрос позже. |
Поиск не даёт результатов
Возможные причины:
Ошибки в параметрах запроса
Убедитесь, что названия параметров написаны в нужном регистре и без опечаток: см. Справочник API.
Пример ошибочного запроса (параметр q указан в неверном регистре как Q):
https://catalog.api.2gis.com/3.0/items?Q=Москва Университетский проспект, 9&key=API_KEY
Ответ
{
"meta": {
"api_version": "3.0.20949",
"code": 404,
"error": {
"message": "Results not found",
"type": "itemNotFound"
},
"issue_date": "20260717"
}
}
Пример исправленного запроса (параметр q указан в правильном регистре):
https://catalog.api.2gis.com/3.0/items?q=Москва Университетский проспект, 9&key=API_KEY
Ответ
{
"meta": {
"api_version": "3.0.20949",
"code": 200,
"issue_date": "20260717"
},
"result": {
"items": [
{
"address_name": "Университетский проспект, 9",
"full_name": "Москва, Университетский проспект, 9",
"id": "4504235282606753",
"name": "Университетский проспект, 9",
"purpose_name": "Жилой дом",
"type": "building"
}
],
"total": 1
}
}
Нет доступа к полям по запросу
Если вы запрашиваете информацию о полях, которые доступны за дополнительную плату, убедитесь, что у вас есть к ним доступ. Если доступа нет, эти поля не отобразятся в теле ответа. Чтобы приобрести доступ, свяжитесь с отделом продаж 2ГИС. Подробнее см. в разделе Дополнительная информация по запросу.
Пример ошибочного запроса (нет доступа к полю items.structure_info.year_of_construction):
https://catalog.api.2gis.com/3.0/items/byid?id=4504235299048514&fields=items.address,items.point,items.structure_info.year_of_construction&key=API_KEY
В ответе не отобразится поле с годом постройки здания:
Ответ
{
"meta": {
"api_version": "3.0.21981",
"code": 200,
"issue_date": "20261106"
},
"result": {
"items": [
{
"address": {
"building_id": "4504235299048514",
"components": [
{
"number": "12",
"street": "Кадашёвская набережная",
"street_id": "4504338361755723",
"type": "street_number"
}
],
"postcode": "119017"
},
"address_name": "Кадашёвская набережная, 12",
"full_name": "Москва, Кадашёвская набережная, 12",
"id": "4504235299048514",
"name": "Кадашёвская набережная, 12",
"point": {
"lat": 55.743142,
"lon": 37.618706
},
"purpose_name": "Музей",
"type": "building"
}
],
"total": 1
}
}
Несуществующие параметры или значения
Проверьте список доступных параметров и значений в Справочнике API.
Пример ошибочного запроса (у параметра type не существует значения entrance):
https://catalog.api.2gis.com/3.0/items?q=Москва Университетский проспект, 9&type=entrance&key=API_KEY
Ответ
{
"meta": {
"api_version": "3.0.20949",
"code": 400,
"error": {
"message": "Param 'type' is invalid. Value 'entrance' is outside of allowed values: 'coordinates','station_entrance','street','adm_div.country','route','branch','adm_div.district','adm_div.amana','attraction','adm_div.region','adm_div.place','adm_div','parking','adm_div.city','adm_div.district_area','station_platform','crossroad','kilometer_road_sign','adm_div.settlement','station','coordinates_additional','gate','building','station.metro','road','adm_div.division','adm_div.living_area'",
"type": "paramIsOutsideSet"
},
"issue_date": "20260717"
}
}
Нет данных в 2ГИС
Чтобы убедиться, что данные действительно отсутствуют в 2ГИС, попробуйте найти необходимый объект вручную на карте. Откройте карту на 2gis.ru и введите адрес, имя или координаты объекта в строке поиска. Если вы нашли нужный объект, скорректируйте запрос и отправьте снова.
Поиск даёт неточные или слишком широкие результаты
Возможные причины:
Не используются ключевые параметры
Запрос работает наиболее эффективно, если используются следующие параметры:
location— координаты точки, в которой нужно искать результат (местоположение пользователя, центр города и прочее). Чем ближе найденный объект к этой точке, тем выше он отображается в ответе на запрос.viewpoint1иviewpoint2— координаты левого верхнего и правого нижнего угла прямоугольной области видимости. Эта область используется как один из критериев для выбора и ранжирования результатов, но не ограничивает жёстко область поиска.radius— радиус поиска в метрах для фильтрации результатов.type— типы объектов, среди которых выполняется поиск. Если передаётся несколько типов, более релевантные результаты одних типов могут вытеснить менее релевантные результаты других типов.
Подробнее о структуре запроса см. в разделе Пример запроса.
Пример эффективного запроса, который содержит все ключевые параметры:
https://catalog.api.2gis.com/3.0/items?q=Москва Университетский проспект, 9&type=building&location=37.549425,55.697848&radius=300&viewpoint1=37.531115,55.702856&viewpoint2=37.575258,55.687182&key=API_KEY
Ответ
{
"meta": {
"api_version": "3.0.20949",
"code": 200,
"issue_date": "20260717"
},
"result": {
"items": [
{
"address_name": "Университетский проспект, 9",
"full_name": "Москва, Университетский проспект, 9",
"id": "4504235282606753",
"name": "Университетский проспект, 9",
"purpose_name": "Жилой дом",
"type": "building"
}
],
"total": 1
}
}
Формат, доступные значения и ограничения параметров см. в Справочнике API.
Недостаточно параметров для сужения поиска
Используйте геоограничения и задайте больше фильтрующих параметров.
Например, можно указать категорию. Пример запроса без указания категории:
https://catalog.api.2gis.com/3.0/items?q=1913 год&location=30.3079,59.9289&key=API_KEY
Ответ (возвращаются 2 объекта)
{
"meta": {
"api_version": "3.0.20949",
"code": 200,
"issue_date": "20260715"
},
"result": {
"items": [
{
"address_comment": "1-4 этаж",
"address_name": "Вознесенский проспект, 13",
"id": "5348553838538209",
"name": "1913 год, гостиница",
"type": "branch"
},
{
"address_comment": "1, 2 этаж",
"address_name": "Вознесенский проспект, 13",
"id": "5348552838519391",
"name": "1913 год, ресторан в историческом центре",
"type": "branch"
}
],
"total": 2
}
}
Пример запроса с указанием категории:
https://catalog.api.2gis.com/3.0/items?q=1913 год&location=30.3079,59.9289&rubric_id=164&key=API_KEY
Ответ (возвращается 1 объект)
{
"meta": {
"api_version": "3.0.20949",
"code": 200,
"issue_date": "20260717"
},
"result": {
"items": [
{
"address_comment": "1, 2 этаж",
"address_name": "Вознесенский проспект, 13",
"id": "5348552838519391",
"name": "1913 год, ресторан в историческом центре",
"type": "branch"
}
],
"total": 1
}
}