Перейти к основному содержимому

Categories API

Categories API предоставляет информацию о категориях. Категория — это группа, объединяющая компании по сферам деятельности.

Когда пользователь хочет получить детальную информацию по одной интересующей его компании, он ищет её по названию. Когда пользователь ещё не знает, какая компания ему нужна, он сначала изучает список компаний в интересующей его категории. В этом случае Categories API предоставляет информацию о категориях.

В Categories API представлены два типа категорий:

  • Объединяющая категория — объект, который соответствует обобщённой сфере деятельности и содержит ссылки на дочерние категории. Дочерние категории соответствуют более конкретным направлениям деятельности в этой сфере.
  • Категория — объект, который соответствует определённой сфере деятельности.
Расширенные возможности

Изучите также возможности других API поиска и дополните ваши сценарии работы с объектами на карте.

Начало работы​

  1. Получите ключ доступа:

    1. Зарегистрируйтесь в личном кабинете Менеджер Платформы.

    2. Создайте демо-ключ или купите подписку для доступа к API. Подробнее о стоимости сервиса см. в разделе Тарифы.

    Подробнее о работе с ключами и подписками см. в документации личного кабинета.

  2. Изучите формат запроса и формат ответа.

  3. Изучите примеры запросов к Categories API и полный справочник API.

Формат запроса​

https://catalog.api.2gis.com/2.0/catalog/rubric/search?q=кафе&region_id=32&key=YOUR_KEY

В запросе используются следующие параметры:

  • q=кафе — поиск выполняется по названию категории «кафе».
  • region_id=32 — идентификатор региона, в котором выполняется поиск.
  • key=YOUR_KEY — ваш ключ API.

Формат ответа​

Ответ возвращается в формате JSON:

{
    "meta": {
        "api_version": "2.0.448950",
        "code": 200,
        "issue_date": "20200629"
    },
    "result": {
        "items": [
            {
                "alias": "kafe_konditerskie_kofejjni",
                "branch_count": 3214,
                "caption": "Кофейни",
                "id": "162",
                "keyword": "Кафе-кондитерские / Кофейни",
                "name": "Кафе-кондитерские / Кофейни",
                "org_count": 1665,
                "parent_id": "2",
                "title": "Кофейни",
                "type": "rubric"
            }
        ],
        "total": 16
    }
}

Пример использования​

Например, чтобы получить список компаний в определённой категории, вы можете использовать Categories API совместно с Places API:

  1. Отправьте запрос к Categories API на получение ID категории:

    • Вариант 1. Поиск по названию категории:

      https://catalog.api.2gis.com/2.0/catalog/rubric/search?q=кафе&region_id=32&key=YOUR_KEY

    • Вариант 2. Получение списка категорий и выбор нужной категории из списка:

      https://catalog.api.2gis.com/2.0/catalog/rubric/list?region_id=32&key=YOUR_KEY

  2. Отправьте запрос к Places API на получение списка компаний в выбранной категории. В запрос можно передать несколько категорий через запятую:

    • Вариант 1. Поиск компаний по ключевому слову с фильтром по категории:

      https://catalog.api.2gis.com/3.0/items?q=Буше&rubric_id=162&location=37.627798,55.755355&key=YOUR_KEY

    • Вариант 2. Получение всех компаний в категории:

      https://catalog.api.2gis.com/3.0/items?rubric_id=162&location=37.627798,55.755355&key=YOUR_KEY

Тарифы​

  • Стоимость сервиса рассчитывается исходя из количества успешных запросов в месяц. Успешным запросом к API считается запрос, который возвращает HTTP-код 200 в поле meta.code в теле ответа, например:

    {
        "meta": {
            "api_version": "3.0.17799",
            "code": 200,
            "issue_date": "20240524"
        },
        ...
    }

  • Актуальную стоимость и лимиты см. в разделе Тарифы.

Варианты размещения​

  • Облако: все методы Categories API доступны через публичные endpoint-ы 2ГИС.
  • On-Premise: все методы Categories API доступны при установке API-платформы 2ГИС в закрытом контуре. Подробнее см. в разделе API-платформа для сервера.

Помощь​

  • Если у вас возникли вопросы при работе с API, задайте их AI-ассистенту (в правом нижнем углу cайта), воспользуйтесь поиском по документации или отправьте электронное письмо на api@2gis.ru.

  • Если вы хотите обсудить возможности API или его интеграцию с вашим продуктом, обратитесь к менеджеру.