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

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

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

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

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

Убедитесь, что имена параметров написаны в нужном регистре и без опечаток: см. Справочник API.

Пример ошибочного запроса (неверный регистр параметра q):

https://catalog.api.2gis.com/3.0/items?Q=Москва Доватора, 9&key=YOUR_KEY

Ответ

{
    "meta": {
        "api_version": "3.0.17799",
        "code": 404,
        "error": {
            "message": "Results not found",
            "type": "itemNotFound"
        },
        "issue_date": "20240524"
    }
}

Пример исправленного запроса:

https://catalog.api.2gis.com/3.0/items?q=Москва Доватора, 9&key=YOUR_KEY

Ответ

{
    "meta": {
        "api_version": "3.0.17799",
        "code": 200,
        "issue_date": "20240524"
    },
    "result": {
        "items": [
            {
                "address_name": "улица Доватора, 9",
                "full_name": "Москва, улица Доватора, 9",
                "id": "4504235282737147",
                "name": "улица Доватора, 9",
                "purpose_name": "Жилой дом",
                "type": "building"
            }
        ],
        "total": 1
    }
}

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

Проверьте список доступных параметров и значений в Справочнике API.

Пример ошибочного запроса (у параметра type не существует значения entrance):

https://catalog.api.2gis.com/3.0/items?q=Москва Доватора, 9&type=entrance&key=YOUR_KEY

Ответ

{
    "meta": {
        "api_version": "3.0.17799",
        "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','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','gate','building','station.metro','road','adm_div.division','adm_div.living_area'",
            "type": "paramIsOutsideSet"
        },
        "issue_date": "20240524"
    }
}

Нет данных в 2ГИС

Чтобы убедиться, что данные действительно отсутствуют в 2ГИС, попробуйте найти необходимый объект вручную на карте: откройте сайт https://2gis.ru/ и введите адрес, имя или координаты объекта в строку поиска. Если вы нашли нужный объект, скорректируйте запрос и отправьте снова.

Поиск даёт неточные или слишком широкие результаты

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

Не используются ключевые параметры

Запрос работает наиболее эффективно, если используются следующие параметры:

location: координаты ориентира, где нужно искать результат (местоположение пользователя, центр города и прочее). Чем ближе найденный объект к этой точке, тем выше он отображается в ответе на запрос.
viewpoint1 и viewpoint2: координаты левой верхней и правой нижней вершины прямоугольной области видимости. Эта область используются как один из критериев для выбора и ранжирования результатов, но не ограничивает жёстко область поиска.
radius: радиус поиска в метрах для фильтрации результатов.
type: типы объектов, среди которых выполняется поиск. Если передаётся несколько типов, более релевантные результаты одних типов могут вытеснить менее релевантные результаты других типов.

Пример эффективного запроса, который содержит все ключевые параметры:

https://catalog.api.2gis.com/3.0/items?q=Москва Доватора, 9&type=building&location=55.723, 37.568&radius=300&viewpoint2=55.7250522, 37.565250&viewpoint1=55.7220, 37.5712&key=YOUR_KEY

Ответ

{
    "meta": {
        "api_version": "3.0.17799",
        "code": 200,
        "issue_date": "20240524"
    },
    "result": {
        "items": [
            {
                "address_name": "улица Доватора, 9",
                "full_name": "Москва, улица Доватора, 9",
                "id": "4504235282737147",
                "name": "улица Доватора, 9",
                "purpose_name": "Жилой дом",
                "type": "building"
            }
        ],
        "total": 1
    }
}

Формат, доступные значения и ограничения параметров описаны в Справочнике API.

Недостаточно параметров для сужения поиска

Используйте геоограничения и задайте больше фильтрующих параметров.

Например, можно указать рубрику. Пример запроса без указания рубрики:

https://catalog.api.2gis.com/3.0/items?q=1913 год&sort_point=30.3079,59.9289&key=YOUR_KEY

Ответ (возвращаются 2 объекта)

{
    "meta": {
        "api_version": "3.0.17799",
        "code": 200,
        "issue_date": "20240524"
    },
    "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 год&sort_point=30.3079,59.9289&key=YOUR_KEY&rubric_id=164

Ответ (возвращается 1 объект)

{
    "meta": {
        "api_version": "3.0.17799",
        "code": 200,
        "issue_date": "20240524"
    },
    "result": {
        "items": [
            {
                "address_comment": "1-2 этаж",
                "address_name": "Вознесенский проспект, 13",
                "id": "5348552838519391",
                "name": "1913 год, ресторан в историческом центре",
                "type": "branch"
            }
        ],
        "total": 1
    }
}