Решение частых проблем поиска

При использовании Places API вы можете получить не тот результат, который ожидали. Например, поисковая выдача будет содержать слишком много результатов или не содержать интересующий вас объект. В инструкции собраны наиболее частые проблемы поиска и возможные пути их решения.

Поиск не даёт результатов

Возможные причины:

Ошибки в параметрах запроса

Убедитесь, что названия параметров написаны в нужном регистре и без опечаток: см. Справочник 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
    }
}

Несуществующие параметры или значения

Проверьте список доступных параметров и значений в Справочнике 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
    }
}