Здесь собраны готовые запросы, которые воспроизводят экраны кабинета Dataforce ADS. Каждый экран — это несколько запросов к одному-двум отчётам: отличаются только измерения, метрики и фильтры.
Синтаксис параметров описан в статье «API для работы с отчётами», значения фильтров — в статье «Справочники API».
Во всех примерах:
{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 и %ПЗ, описано в статье «Метрики: Конкуренты и Динамика».
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 с фильтром по позиции.
Подробнее о метриках — в статье «Метрики: Товары».
Товары и цены
Тоже отчёт 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 для работы с отчётами».
- Значения фильтров — «Справочники API».