# Справочники API

Источник: https://docs.dataforce.io/articles/api-reference-guides

Справочники отдают допустимые значения фильтров: проекты, регионы, устройства, домены, категории, UTM-метки и другие. Их используют, чтобы подставить в `filters` правильное значение, а не угадывать его.

Как устроен запрос к отчётам, описано в статье «[API для работы с отчётами](https://docs.dataforce.io/articles/api-working-with-reports)».

---

## Endpoint

```
GET https://direct.dataforce.io/public-api/reporting/projects/{project_id}/dictionaries/{dictionary}
```

Все справочники привязаны к проекту: значения у разных проектов свои. Если строите отчёт по нескольким проектам, запрашивайте справочник для каждого проекта отдельно.

### Параметры

| Параметр | Тип | Описание |
| --- | --- | --- |
| `search` | string | Поиск по названию, например `search=example`. Работает только в справочниках с поиском (см. «Список справочников») |
| `limit` | integer | Количество элементов, от 1 до 500. По умолчанию — 100. Только для справочников с пагинацией |
| `offset` | integer | Смещение для постраничной выгрузки. Только для справочников с пагинацией |

Справочники без пагинации всегда возвращают полный список. В справочниках без поиска параметр `search` не учитывается: придёт полный список.

### Ответ

```json
{
  "query": { "filters": [], "search": null, "limit": 100, "offset": 0 },
  "total_count": 6,
  "items": [
    { "value": 213, "display_name": "Москва", "attributes": [], "children": [] },
    { "value": 2, "display_name": "Санкт-Петербург", "attributes": [], "children": [] }
  ]
}
```

- `value` — то, что подставляется в фильтр отчёта;
- `display_name` — название для показа;
- `total_count` — сколько всего элементов в справочнике.

> **Важно:** В фильтр всегда подставляйте `value`, а не `display_name`. Например, для Москвы — `serp_region=213`, а не `serp_region=Москва`.

---

## Список справочников

Актуальный список справочников с их возможностями можно получить запросом:

```
GET https://direct.dataforce.io/public-api/reporting/dictionaries
```

Для каждого справочника в ответе указаны:

- `name` — имя для подстановки в адрес;
- `title` — название;
- `type` — `flat` (плоский список) или `tree` (дерево, например категории);
- `capabilities.searching` / `capabilities.pagination` — поддерживает ли справочник `search` и `limit`/`offset`;
- `dependencies` — с какими справочниками связан.

Запрашивайте справочник по адресу `/public-api/reporting/projects/{project_id}/dictionaries/{name}`. Поле `url` из этого ответа для запросов не используйте.

| Справочник | Что возвращает | Для какого фильтра |
| --- | --- | --- |
| `projects` | Проекты пространства. В `attributes` — `space_id` и название пространства | `project_id`, `space_id` в адресе запроса |
| `serp_region` | Регионы выдачи проекта | `serp_region` |
| `regions` | Регионы частотности (WS) | `ws_region` |
| `devices` | Устройства: `desktop`, `mobile` | `serp_device` |
| `serp_platform` | Платформы | `serp_platform` |
| `oses` | Операционные системы: `android`, `ios` | `serp_os` |
| `calendar` | Даты, за которые есть данные | `periods` |
| `categories` | Категории проекта. `value` совпадает с `path_N_id` в отчётах | `path_N_id` |
| `category_tree_level` | Уровни дерева категорий: 0 — дерево, 1–3 — плоский список уровня | — |
| `queries` | Запросы проекта | `query_id` |
| `query_ws` | Запросы с частотностью | `query_id` |
| `query_tags` | Теги запросов | `query_tag_name` |
| `domain` | Домены проекта и выдачи | `domain`, `app_id_or_domain` |
| `own_platforms` | Свои площадки проекта: сайты и мобильные приложения | `app_id_or_domain` |
| `product_domains` | Домены товарной галереи | `domain` в отчёте `products` |
| `block_name` | Блоки выдачи: `ads` (Контекст), `dynamic_places` (Динамические места), `ads\\|dynamic_places` (Все) | `block_name` в отчёте `soi_competitors.all_data` |
| `utm_source`, `utm_medium`, `utm_campaign` | UTM-метки объявлений | `utm_source`, `utm_medium`, `utm_campaign` |
| `serp_vendor` | Источник сбора выдачи | `serp_vendor` |
| `ws` | Тип частотности | — |
| `named_segments` | Сохранённые сегменты проекта | — |
| `named_reports` | Сохранённые отчёты проекта | — |
| `reports` | Имена отчётов, доступных в API | `{report}` в адресе запроса |

---

## Примеры

### Узнать space_id проекта

```
GET https://direct.dataforce.io/public-api/reporting/projects/123/dictionaries/projects
```

В ответе — все проекты пространства, у каждого в `attributes.space_id` указан идентификатор пространства.

### Найти домен конкурента

```
GET https://direct.dataforce.io/public-api/reporting/projects/123/dictionaries/domain?search=competitor&limit=20
```

### Получить категории первого уровня

```
GET https://direct.dataforce.io/public-api/reporting/projects/123/dictionaries/categories
```

`value` категории подставляется в фильтр `path_1_id`, например `path_1_id<in>1001|1002`.

---

## Особенности

- Справочник `domain` всегда начинается со строки «**Мой проект**»: её `value` — ваш основной домен. Она добавляется сверх `limit`, поэтому при `limit=5` придёт 6 элементов.
- Справочники `domain`, `queries`, `query_ws`, `query_tags`, `regions` и `utm_*` поддерживают поиск и пагинацию. На больших проектах в них десятки тысяч элементов: ищите нужное значение через `search`, а не выгружайте справочник целиком.
- Поиск есть также в `named_reports`, `named_segments` и `product_domains`, но без пагинации.
- Неизвестное имя справочника вернёт ошибку `404` с текстом `Dictionary "…" not found`. Несуществующий проект — `404` с текстом «Проект не найден».

---

## Что дальше?

- Подставьте найденные значения в готовые запросы из статьи «[Запросы для экранов](https://docs.dataforce.io/articles/api-requests-for-screens)».