Categories API

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

Как это работает

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

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

Типы категорий

В Categories 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.

Формат ответа на запрос

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

Отправьте запрос к 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
```
Отправьте запрос к 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
```

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

Получите ключ доступа:
1. Зарегистрируйтесь в личном кабинете Platform Manager.
2. Создайте демо-ключ или купите ключ для доступа к API: см. инструкцию Ключи доступа.
Работать с ключами можно в личном кабинете Platform Manager: подробнее см. в разделе Platform Manager.
Изучите формат запроса и формат ответа.
Изучите примеры запросов к Categories API.