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

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

Как устроен запрос к отчётам, описано в статье «API для работы с отчётами».

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 не учитывается: придёт полный список.

Ответ

{
  "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 с текстом «Проект не найден».

Что дальше?

Подставьте найденные значения в готовые запросы из статьи «Запросы для экранов».