# API Запросы для экранов

Источник: https://docs.dataforce.io/articles/api-requests-for-screens

Здесь собраны готовые запросы, которые воспроизводят экраны кабинета Dataforce ADS. Каждый экран — это несколько запросов к одному-двум отчётам: отличаются только измерения, метрики и фильтры.

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

**Во всех примерах:**

- `{space_id}` — ваше пространство, `project_id=123` — ваш проект;
- `example.ru` — ваш домен, `competitor1.ru` и `competitor2.ru` — конкуренты;
- регион — Москва (`213`), устройство — `desktop`, период — сентябрь 2026.

Подставьте свои значения из справочников.

> Если вызываете API из кода, кодируйте значения параметров (URL-encode): символы `<`, `>`, `|`, `;` и кириллица в адресе должны быть закодированы.

---

## Свой домен в выдаче: «Вместе» и «Раздельно»

На экранах SOI Конкуренты, SOI Динамика и SOI Товары свои площадки (сайты и приложения проекта) можно показывать вместе или раздельно. В API это пара «измерение + фильтр», и использовать их нужно **только вместе**:

| Режим | Отчёты `context.*` | Отчёт `products` |
| --- | --- | --- |
| **Вместе** (по умолчанию) | измерение `app_id_or_domain_own_merged` + фильтр `is_app_id_or_domain_own_merged_best=1` | измерение `domain_own_merged` + фильтр `is_domain_own_merged_best=1` |
| **Раздельно** | измерение `app_id_or_domain` + фильтр `is_app_id_or_domain_best=1` | измерение `domain` + фильтр `is_domain_best=1` |

Фильтр `*_best=1` убирает повторные показы одной площадки в одной выдаче. Без него доли завышаются.

Чтобы разделить свои площадки и конкурентов, используйте фильтры `app_id_or_domain_is_own=1` / `=0` (в `products` — `domain_is_own=1` / `=0`).

---

## SOI Динамика

Отчёт выбирается по фильтру «Места показов»: `context.ads` — Контекст, `context.dm` — Динамические места, `context.all` — оба блока. Примеры ниже — для Контекста.

### Сводка (плитки KPI)

```
GET https://direct.dataforce.io/public-api/reporting/spaces/{space_id}/reports/context.ads
?periods=2026-09-01:2026-09-30
&metrics=prc_ws_top1,prc_ws_top3,prc_ws,prc_count_top1,prc_count_top3,prc_count
&filters=project_id=123;serp_region=213;serp_device=desktop;domain<in>example.ru;is_app_id_or_domain_best=1
&format=JSON
```

### График по неделям

```
GET https://direct.dataforce.io/public-api/reporting/spaces/{space_id}/reports/context.ads
?periods=2026-09-01:2026-09-30
&dimensions=week,date_from,date_to
&metrics=prc_ws_top1,prc_ws_top3,prc_ws,prc_count_top1,prc_count_top3,prc_count
&order_by=-week
&filters=project_id=123;serp_region=213;serp_device=desktop;domain<in>example.ru;is_app_id_or_domain_best=1
&format=JSON
```

Для разбивки по дням замените `week` на `date`, по месяцам — на `month`.

### Категории

Корневой уровень дерева:

```
GET https://direct.dataforce.io/public-api/reporting/spaces/{space_id}/reports/context.ads
?periods=2026-09-01:2026-09-30
&dimensions=path_1,path_1_id,path_1_has_child
&metrics=prc_ws_top1,prc_ws_top3,prc_ws,prc_count_top1,prc_count_top3,prc_count
&order_by=+prc_ws
&filters=project_id=123;serp_region=213;serp_device=desktop;domain<in>example.ru;is_app_id_or_domain_best=1;path_1_id<>0
&format=JSON
```

Чтобы раскрыть категорию, запросите следующий уровень: измерения `path_2,path_2_id,path_2_has_child`, фильтры `path_2_id<>0;path_1_id=<id раскрываемой категории>`. Так же — для уровней 3–5. `path_N_has_child` показывает, есть ли у категории вложенные.

### Кампании

По показам:

```
GET https://direct.dataforce.io/public-api/reporting/spaces/{space_id}/reports/context.ads
?periods=2026-09-01:2026-09-30
&dimensions=utm_campaign
&metrics=prc_ws_top1_campaign,prc_ws_top3_campaign,prc_ws_campaign,prc_count_top1_campaign,prc_count_top3_campaign,prc_count_campaign
&order_by=+prc_ws_top3_campaign
&filters=project_id=123;serp_region=213;serp_device=desktop;domain<in>example.ru;is_app_id_or_domain_best=1
&limit=10&offset=0
&format=JSON
```

По взвешенным показам:

```
GET https://direct.dataforce.io/public-api/reporting/spaces/{space_id}/reports/context.ads
?periods=2026-09-01:2026-09-30
&dimensions=utm_campaign
&metrics=prc_ws_through,blur,prc_ws_top1_campaign_weight,prc_ws_top3_campaign_weight,prc_ws_campaign_weight,prc_count_top1_campaign_weight,prc_count_top3_campaign_weight,prc_count_campaign_weight
&order_by=+prc_ws_through
&filters=project_id=123;serp_region=213;serp_device=desktop;domain<in>example.ru;is_app_id_or_domain_best=1;utm_campaign<>
&limit=10&offset=0
&format=JSON
```

Фильтр `utm_campaign<>` отсекает показы без UTM-метки. Он нужен только для таблицы взвешенных показов.

### Метрики

| Колонка экрана | Сводка, график, категории | Кампании по показам | Кампании по взвешенным показам |
| --- | --- | --- | --- |
| %SOI Топ-1 | `prc_ws_top1` | `prc_ws_top1_campaign` | `prc_ws_top1_campaign_weight` |
| %SOI Топ-3 | `prc_ws_top3` | `prc_ws_top3_campaign` | `prc_ws_top3_campaign_weight` |
| %SOI Общий | `prc_ws` | `prc_ws_campaign` | `prc_ws_campaign_weight` |
| %ПЗ Топ-1 | `prc_count_top1` | `prc_count_top1_campaign` | `prc_count_top1_campaign_weight` |
| %ПЗ Топ-3 | `prc_count_top3` | `prc_count_top3_campaign` | `prc_count_top3_campaign_weight` |
| %ПЗ Общий | `prc_count` | `prc_count_campaign` | `prc_count_campaign_weight` |
| % вклада | — | — | `prc_ws_through` |
| % размытия | — | — | `blur` |

- **% вклада** (`prc_ws_through`) — доля спроса запросов кампании в общем спросе всех запросов, где домен показывался хотя бы под одной кампанией. Это не то же самое, что %SOI.
- **% размытия** (`blur`) — насколько запросы кампании пересекаются с другими кампаниями того же домена. Чем выше, тем сильнее пересечение.

Как считаются %SOI и %ПЗ, описано в статье «**[Метрики: Конкуренты и Динамика](https://docs.dataforce.io/articles/metrics-competitors-and-dynamic)**».

---

## SOI Конкуренты

### Топ-10 конкурентов

```
GET https://direct.dataforce.io/public-api/reporting/spaces/{space_id}/reports/context.ads
?periods=2026-09-01:2026-09-30
&dimensions=app_id_or_domain
&metrics=ws
&order_by=+ws
&filters=project_id=123;serp_region=213;serp_device=desktop;is_app_id_or_domain_own_merged_best=1;app_id_or_domain_is_own=0
&limit=10
&format=JSON
```

Количество конкурентов в топе задаёт `limit`.

### «Мой проект» по неделям

```
GET https://direct.dataforce.io/public-api/reporting/spaces/{space_id}/reports/context.ads
?periods=2026-09-01:2026-09-30
&dimensions=app_id_or_domain_own_merged,week,date_from,date_to
&metrics=prc_ws
&order_by=-week
&filters=project_id=123;serp_region=213;serp_device=desktop;is_app_id_or_domain_own_merged_best=1;app_id_or_domain_is_own=1
&with_diff=1
&format=JSON
```

### Конкуренты по неделям

Подставьте домены из запроса «Топ-10 конкурентов»:

```
GET https://direct.dataforce.io/public-api/reporting/spaces/{space_id}/reports/context.ads
?periods=2026-09-01:2026-09-30
&dimensions=app_id_or_domain_own_merged,week,date_from,date_to
&metrics=prc_ws
&order_by=-week
&filters=project_id=123;serp_region=213;serp_device=desktop;is_app_id_or_domain_own_merged_best=1;app_id_or_domain_own_merged<in>competitor1.ru|competitor2.ru
&with_diff=1
&format=JSON
```

### Мои площадки

Блок внизу экрана строится отчётом `context.all`:

```
GET https://direct.dataforce.io/public-api/reporting/spaces/{space_id}/reports/context.all
?periods=2026-09-01:2026-09-30
&dimensions=app_id_or_domain,week,date_from,date_to
&metrics=prc_ws
&order_by=-week
&filters=project_id=123;serp_region=213;serp_device=desktop;app_id_or_domain_is_own=1
&format=JSON
```

> %SOI Общий может превышать 100%: если площадка занимает в одной выдаче несколько мест, учитывается каждое.

### Вкладки и переключатели

| На экране | В запросе |
| --- | --- |
| %SOI Топ-1 / Топ-3 / Общий | метрика `prc_ws_top1` / `prc_ws_top3` / `prc_ws` |
| %ПЗ Топ-1 / Топ-3 / Общий | метрика `prc_count_top1` / `prc_count_top3` / `prc_count` |
| Количество мест | метрика `count_places` |
| Показы: Премиум / Прочие | фильтр `is_premium_position=1` / `is_premium_position=0`; «Все» — без фильтра |

---

## SOI Товары

Все запросы — к отчёту `products`.

### Топ-10 конкурентов

```
GET https://direct.dataforce.io/public-api/reporting/spaces/{space_id}/reports/products
?periods=2026-09-01:2026-09-30
&dimensions=domain_is_own,domain_own_merged
&metrics=prc_ws
&order_by=+prc_ws
&filters=project_id=123;serp_region=213;serp_device=desktop;is_domain_own_merged_best=1;domain_is_own=0
&limit=10
&format=JSON
```

### «Мой проект» по неделям

```
GET https://direct.dataforce.io/public-api/reporting/spaces/{space_id}/reports/products
?periods=2026-09-01:2026-09-30
&dimensions=domain_own_merged,week,date_from,date_to
&metrics=prc_ws
&order_by=-week
&filters=project_id=123;serp_region=213;serp_device=desktop;is_domain_own_merged_best=1;domain_is_own=1
&with_diff=1
&format=JSON
```

### Вкладки

| Вкладка | Метрика | Дополнительный фильтр |
| --- | --- | --- |
| %SOI Видимый | `prc_ws` | `position<=4` (видимая область: 3, 4, 5 или 6 товаров) |
| %SOI Общий | `prc_ws` | — |
| %ПЗ Общий | `prc_count` | — |
| Средняя позиция | `avg_position` | — |
| Количество мест | `count_places` | — |

Отдельной метрики «%SOI Видимый» нет: это та же `prc_ws` с фильтром по позиции.

Подробнее о метриках — в статье «[Метрики: Товары](https://docs.dataforce.io/articles/metrics-products)».

---

## Товары и цены

Тоже отчёт `products`. Экран показывает данные за весь период, без разбивки по времени.

### Верхняя таблица: конкуренты

```
GET https://direct.dataforce.io/public-api/reporting/spaces/{space_id}/reports/products
?periods=2026-09-01:2026-09-30
&dimensions=domain_is_own,domain,currency
&metrics=prc_ws,count_products,median_price,median_upper,median_lower
&order_by=+count_products
&filters=project_id=123;currency=₽;serp_platform<has>desktop,serp_platform<has>mobile;serp_region=213;domain_is_own=0
&limit=5
&format=JSON
```

Для своих доменов замените `domain_is_own=0` на `domain_is_own=1`.

### Нижняя таблица: товары

```
GET https://direct.dataforce.io/public-api/reporting/spaces/{space_id}/reports/products
?periods=2026-09-01:2026-09-30
&dimensions=category_last_parsed,is_listing,domain,product_name
&metrics=median_price,count_products_prc,count_products_by_domain_prc,median_upper,median_lower
&order_by=+count_products_prc
&filters=project_id=123;domain<in>example.ru|competitor1.ru;serp_platform<has>desktop,serp_platform<has>mobile;serp_region=213
&limit=10&offset=0
&format=JSON
```

Домены для этой таблицы берите из справочника `product_domains`.

### Метрики

| Метрика | Описание |
| --- | --- |
| `count_products` | Количество товаров в галерее |
| `median_price` | Медианная цена |
| `median_upper` | Доля товаров дороже медианы рынка, % |
| `median_lower` | Доля товаров дешевле медианы рынка, % |
| `count_products_prc` | Доля товара среди всех товаров, % |
| `count_products_by_domain_prc` | Доля товара среди товаров домена, % |

`median_upper` и `median_lower` в сумме не обязаны давать 100%.

### Переключатели

| На экране | В запросе |
| --- | --- |
| Тип товара: Товар | фильтр `is_listing=0` |
| Тип товара: Каталог | фильтр `is_listing=1` |
| Тип товара: Все | **без фильтра** `is_listing` |
| Видимая область | фильтр `position<=4` во всех запросах экрана |
| Валюта | фильтр `currency=₽` (нужен для медианной цены в верхней таблице) |

> **Важно:** Не передавайте `is_listing=3` для варианта «Все» — придёт пустой ответ. Просто уберите фильтр.

---

## SOI Статистика

Все запросы — к отчёту `statistics`. Данные агрегированы за весь период.

### Наличие рекламы

```
GET https://direct.dataforce.io/public-api/reporting/spaces/{space_id}/reports/statistics
?periods=2026-09-01:2026-09-30
&metrics=prc_ws_ads_exist,prc_ws_dm_exist,prc_ws_products_exist,prc_ws_apps_exist,prc_ws_ads_not_exist,prc_ws_dm_not_exist,prc_ws_products_not_exist,prc_ws_apps_not_exist
&filters=project_id=123;serp_region=213;serp_device=desktop
&format=JSON
```

### Количество объявлений (гистограмма)

```
GET https://direct.dataforce.io/public-api/reporting/spaces/{space_id}/reports/statistics
?periods=2026-09-01:2026-09-30
&dimensions=volume_ads
&metrics=prc_ws
&order_by=-volume_ads
&filters=project_id=123;serp_region=213;serp_device=desktop
&format=JSON
```

Для динамических мест замените `volume_ads` на `volume_dm`, для товаров — на `volume_products`.

### Детализация по ОС

```
GET https://direct.dataforce.io/public-api/reporting/spaces/{space_id}/reports/statistics
?periods=2026-09-01:2026-09-30
&dimensions=serp_devices_os
&metrics=prc_ws_ads_exist,avg_ads,prc_ws_apps_exist,prc_ws_dm_exist,avg_dm
&filters=project_id=123;serp_region=213;serp_device=desktop
&format=JSON
```

### Детализация по категориям

```
GET https://direct.dataforce.io/public-api/reporting/spaces/{space_id}/reports/statistics
?periods=2026-09-01:2026-09-30
&dimensions=path_1,path_1_id,path_1_has_child
&metrics=prc_ws_ads_exist,avg_ads,prc_ws_apps_exist,prc_ws_dm_exist,avg_dm
&filters=project_id=123;serp_region=213;serp_device=desktop;path_1_id<>0
&format=JSON
```

### Метрики

| Метрика | Описание |
| --- | --- |
| `prc_ws_ads_exist` / `prc_ws_ads_not_exist` | Доля спроса (WS) с рекламой / без рекламы, % |
| `prc_ws_dm_exist` / `prc_ws_dm_not_exist` | То же для динамических мест |
| `prc_ws_products_exist` / `prc_ws_products_not_exist` | То же для товарной галереи |
| `prc_ws_apps_exist` / `prc_ws_apps_not_exist` | То же для приложений |
| `avg_ads` / `avg_dm` | Среднее число объявлений / динамических мест в выдаче |
| `prc_ws` | Доля спроса для строки гистограммы |

Переключатель «% Охвата / % Запросов» меняет семейство метрик: `prc_ws_…` (по спросу) или `prc_…` (по запросам), например `prc_ads_exist`.

> Метрики с префиксом `compact_` (например, `compact_prc_ws_ads_exist`) возвращают не число, а массив `[регион, устройство, значение]`. Для обычных таблиц используйте метрики без префикса.

---

## Тренды

Все запросы — к отчёту `trends`.

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

```
GET https://direct.dataforce.io/public-api/reporting/spaces/{space_id}/reports/trends
?periods=2026-09-01:2026-09-30
&dimensions=path_1,path_1_id
&metrics=ws2_prc
&order_by=+ws2_prc
&filters=project_id=123
&limit=30
&format=JSON
```

### Общий спрос по неделям

```
GET https://direct.dataforce.io/public-api/reporting/spaces/{space_id}/reports/trends
?periods=2026-09-01:2026-09-30
&dimensions=week,start_of_week_from,end_of_week_to
&metrics=ws2
&order_by=-week
&filters=project_id=123
&with_diff=1
&format=JSON
```

### Спрос по категориям

```
GET https://direct.dataforce.io/public-api/reporting/spaces/{space_id}/reports/trends
?periods=2026-09-01:2026-09-30
&dimensions=week,start_of_week_from,end_of_week_to,path_1,path_1_id
&metrics=ws2
&order_by=-week
&filters=project_id=123;path_1_id<in>1001|1002|1003
&with_diff=1
&format=JSON
```

`path_1_id` берите из запроса «Топ категорий» или справочника `categories`.

### Метрики

| Метрика | Описание |
| --- | --- |
| `ws2` | Спрос «WS» — последнее собранное значение частотности за неделю (не сумма за неделю) |
| `ws2_prc` | Доля категории в спросе проекта, % |
| `ws2_total` | Спрос по всему проекту |

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

> **Важно:** **Не передавайте фильтр `serp_region` в отчёт `trends`.** Ошибки не будет, но все значения придут нулевыми. Спрос считается по проекту целиком.

- Номера недель в `trends` и `context.*` за один и тот же период могут не совпадать. Сопоставляйте ряды по датам (`start_of_week_from` / `end_of_week_to` и `date_from` / `date_to`), а не по номеру недели.
- Серии «%SOI ТОП3» с графика экрана через API недоступны.

---

## Объявления

Один запрос к отчёту `soi_competitors.all_data`. Вкладки экрана отличаются только набором `dimensions`.

```
GET https://direct.dataforce.io/public-api/reporting/spaces/{space_id}/reports/soi_competitors.all_data
?periods=2026-09-01:2026-09-30
&dimensions=title,snippet
&metrics=prc_ws_through
&order_by=+prc_ws_through
&filters=project_id=123;serp_region=213;serp_platform<has>desktop;block_name<in>ads;domain<in>example.ru
&limit=100&offset=0
&format=JSON
```

| Вкладка | `dimensions` |
| --- | --- |
| Объявления | `title,snippet` |
| Тексты | `snippet` |
| Посадочные страницы | `url_cut` |
| Запросы | `query,title,snippet,url_cut` |
| Тексты и UTM-метки | `title,snippet,utm_campaign` |
| UTM-метки | `utm_source,utm_medium,utm_campaign` |

- `prc_ws_through` — «Популярность, %»: доля показов текста среди всех показов домена.
- Блок выдачи (`block_name`): `ads` — Контекст, `dynamic_places` — Динамические места, `ads|dynamic_places` — все.
- «Премиум / Прочие» — фильтр `is_premium_position=1` / `=0`, «Все» — без фильтра.
- На крупных проектах выборка — тысячи строк. Выгружайте постранично через `limit` и `offset`.

---

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

- Общие правила запросов — «[API для работы с отчётами](https://docs.dataforce.io/articles/api-working-with-reports)».
- Значения фильтров — «[Справочники API](https://docs.dataforce.io/articles/api-reference-guides)».