REST API

Adspect предоставляет REST API для автоматизации различных задач:

Создания, изменения и удаления потоков
Скачивания PHP-файлов интеграции
Управления гостевым доступом к статистике
Получения статистики: построения воронок продаж и выгрузки логов переходов

Базовым URL для всех точек вызова является https://api.adspect.net/v1/. Описания точек вызова ниже указывают пути относительно этого базового URL. Сначала указывается HTTP-метод, за которым следует относительный путь точки вызова, например:

GET /streams

Это описание означает GET-запрос на URL https://api.adspect.net/v1/streams.

API поддерживает JSON- и XML-кодирование данных. В примерах ниже будет использовано JSON-кодирование для простоты.

Аутентификация

Для аутентификации в API используется HTTP-аутентификация типа Basic, в которой ключ API передается в качестве имени пользователя, а пароль оставляется пустым. Ваш ключ API находится в вашем профиле.

Каждый запрос к API должен содержать два обязательных заголовка:

Заголовок	Значение	Описание
`Authorization`	`Basic AUTHKEY`	Аутентификация в Adspect при помощи ключа API (см. ниже).
`Content-Type`	`application/json` или `application/xml`	Выбор JSON- или XML-кодирования данных, соответственно.

Поле AUTHKEY в заголовке Authorization формируется путем base64-кодирования строки, составленной из ключа API и добавленного в конце двоеточия.

Пример кода на PHP:

<?php
$apiKey = 'SEbMw152aoe2ArffS7yjEJzJ_MFnd33e';
$authKey = base64_encode($apiKey . ':');

Совет

Для удобства вы можете взять готовое значение AUTHKEY в вашем профиле в поле «Заголовок Authorization».

Некоторые HTTP-клиенты имеют нативную поддержку аутентификации HTTP Basic и самостоятельно добавляют заголовок Authorization. Например, Python Requests предоставляет класс requests.auth.HTTPBasicAuth. В этом случае укажите ваш ключ API в качестве имени пользователя и оставьте пароль пустым. Пример для php-curl:

<?php
$apiKey = 'SEbMw152aoe2ArffS7yjEJzJ_MFnd33e';
$curl = curl_init();
curl_setopt($curl, CURLOPT_USERPWD, $apiKey . ':');

Коллекции

Некоторые свойства объектов могут принимать значения только из строго заданных множеств — коллекций. В таблице ниже приводятся точки вызова для получения коллекций:

Точка вызова	Описание
`GET /collections/presets`	Шаблоны потоков для различных источников трафика.
`GET /collections/os`	Операционные системы для таргетинга и статистики.
`GET /collections/browsers`	Браузеры для таргетинга и статистики.
`GET /collections/engines`	Движки браузера для таргетинга и статистики.
`GET /collections/countries`	Коды стран для таргетинга и статистики.
`GET /collections/languages`	Коды языков для таргетинга и статистики.
`GET /collections/time-zones`	Часовые пояса для таргетинга и статистики.
`GET /collections/stream-modes`	Режимы потока.
`GET /collections/stream-actions`	Действия для контента и белой страницы (см. ниже).
`GET /collections/query-group-by`	Элементы разбивки для воронки продаж.
`GET /collections/query-funnel-metrics`	Колонки метрик воронки продаж.
`GET /collections/query-log-columns`	Колонки лога переходов.

Действия потока

Следующая таблица описывает действия для контента и белой страницы:

Действие	Описание
`local`	Локальный файл без редиректа.
`proxy`	Проксирование.
`fetch`	Подгрузка HTML-кода.
`iframe`	Отображение в iframe.
`301`	Редирект HTTP 301.
`302`	Редирект HTTP 302.
`303`	Редирект HTTP 303.
`noop`	Без действия.
`refresh`	Редирект HTTP Refresh.
`meta`	Редирект HTML meta refresh.
`return`	Произвольный код ответа HTTP.
`php`	Выполнить PHP-код.
`js`	Выполнить JavaScript-код.
`xar`	Заголовок X-Accel-Redirect.
`xsf`	Заголовок X-Sendfile.

Управление потоками

Поток представляется в виде объекта со следующими свойствами:

Свойство	Тип	Описание
`stream_id`	Строка	Идентификатор потока.
`account_id`	Строка	Идентификатор аккаунта. Только для чтения.
`name`	Строка	Имя потока.
`tags`	Массив строк	Теги, до 32 штук.
`mode`	Строка	Режим потока, один из: `Filter` — фильтр `Review` — модерация `Money` — контент `White` — белая страница
`notes`	Строка	Любые заметки, которые вы хотели бы записать.
`money_pages`	Массив объектов	Массив контент-страниц, до 254 объектов, каждый со следующими свойствами: `page` — URL / путь к файлу / код (в зависимости от действия), строка `action` — действие, производимое с посетителем, строка `arg_passthru` — включить проброс URL-параметров, логический `weight` — вес при ротации, целое число `enabled` — включить контент-страницу, логический
`rotator`	Строка	Ротатор контент-страниц: `Split` (сплит) или `Timer` (таймер).
`safe_pages`	Массив из одного объекта	Белая страница. Массив из одного объекта со следующими свойствами: `page` — URL / путь к файлу / код (в зависимости от действия), строка `action` — действие, производимое с посетителем, строка `arg_passthru` — включить проброс URL-параметров, логический
`filter_level`	Целое число или строка	Уровень фильтрации, один из: 0 или `Off` — минимальный 1 или `Low` — низкий 2 или `Medium` — средний 3 или `High` — высокий 4 или `Paranoid` — паранойя
`enable_fp`	Логический	Включить фильтрацию по JavaScript-отпечаткам и обучение модели VLA™.
`enable_ua`	Логический	Включить фильтрацию по встроенным спискам user agent.
`require_unique`	Логический	Пропускать только уникальных посетителей.
`require_touch`	Логический	Требовать поддержку touchscreen (нужна фильтрация по JS-отпечаткам)
`allow_apps`	Логический	Разрешить трафик из мобильных приложений.
`allow_embed`	Логический	Разрешить трафик из фреймов (в том числе iframe), элементов embed и object.
`countries`	Массив строк	Разрешенные коды стран в двухбуквенном формате.
`os`	Массив строк	Разрешенные операционные системы.
`browsers`	Массив строк	Разрешенные браузеры.
`engines`	Массив строк	Разрешенные движки браузера.
`languages`	Массив строк	Разрешенные коды языков браузера.
`timezones`	Массив целых чисел	Разрешенные часовые пояса в виде часовых сдвигов относительно UTC.
`tz_match_ip`	Логический	Проверять соответствие часового пояса браузера и местоположения.
`skipClicks`	Целое число	Число первых переходов, которые будут отфильтрованы (отложенный запуск).
`skip_clicks_mode`	Строка	Режим пропуска переходов, один из: `all` — все: счетчик пропущенных переходов уменьшается при каждом переходе `money` — контент: счетчик переходов уменьшается с каждым легитимным посетителем `safe` — белая: счетчик переходов уменьшается с каждым ботом, модератором и т.п.
`ip_list_mode`	Строка	Режим фильтрации, один из: `black` — черный: блокировать IP-адреса/ASN из черного списка, если их нет в белом списке `white` — белый: блокировать IP-адреса/ASN из черного списка или не из белого списка `special` — специальный: блокировать IP-адреса/ASN из черного списка, пропускать из белого списка.
`ip_on_review`	Логический	Заносить все IP-адреса в черный список в режиме «Модерация».
`extrapolate_ipv4`	Целое число в интервале 0 и 255	IPv4-экстраполяция.
`extrapolate_ipv6`	Целое число в интервале 0 и 64	IPv6-экстраполяция.
`cost_parameter`	Строка	Имя параметра цены перехода.
`sid_parameter`	Строка	Имя параметра sub ID.
`cid_parameter`	Строка	Имя параметра ID перехода.
`url_rules`	Массив объектов	URL-правила. См. структуру объекта URL-правила.
`schedule`	Массив объектов	Расписание. См. структуру объекта расписания.
`ua_list_mode`	Строка	Режим фильтрации user agent, один из: `black` — черный: блокировать user agent из черного списка, если их нет в белом списке `white` — белый: блокировать user agent из черного списка или не из белого списка `special` — специальный: блокировать user agent из черного списка, пропускать из белого списка.
`ua_blacklist`	Строка или массив строк	Черный список user agent.
`ua_whitelist`	Строка или массив строк	Белый список user agent.
`referer_regex`	Строка	Регулярное выражение для фильтрации по referrer-у.

Пример:

{
  "stream_id": "1eacc6d0-875f-6f5c-bff8-00162501c2b4",
  "account_id": "1eaa2ce5-d4dd-63ec-b8a4-00162501c2b4",
  "name": "Example Stream",
  "tags": ["Tag1", "Tag2"],
  "mode": "Filter",
  "notes": "This is an example comment.",
  "money_pages": [
    {
      "page": "https://example.com/offer1?clid={clickid}",
      "action": "302",
      "arg_passthru": true,
      "weight": 10,
      "enabled": true
    },
    {
      "page": "https://example.com/offer2?clid={clickid}",
      "action": "302",
      "arg_passthru": true,
      "weight": 20,
      "enabled": true
    }
  ],
  "rotator": "Split",
  "safe_pages": [
    {
      "page": "safe.html",
      "action": "local",
      "arg_passthru": true
    }
  ],
  "filter_level": "High",
  "enable_fp": true,
  "enable_ua": true,
  "require_unique": true,
  "require_touch": false,
  "allow_apps": false,
  "allow_apps": true,
  "countries": ["AE", "HK"],
  "os": ["iOS", "macOS"],
  "browsers": ["Google Chrome"],
  "engines": ["Blink"],
  "languages": ["en", "fr", "es"],
  "timezones": [-5, -6, -7],
  "tz_match_ip": true,
  "ip_on_review": true,
  "cost_parameter": "cost",
  "sid_parameter": "zoneid",
  "cid_parameter": "clickid",
  "url_rules": [
    {
      "param": "zoneid",
      "op": "REGEX",
      "arg": "[[:alnum:]-_]{8,}",
      "enabled": true
    }
  ],
  "schedule": [
    {
      "days": ["Sun", "Sat"],
      "since": "15:30:00",
      "till": "22:15:00"
    }
  ]
}

Объект URL-правила

Объект URL-правила имеет следующую структуру:

{
  "param": "gclid",
  "op": "REGEX",
  "arg": "[[:alnum:]-_]{55,}",
  "enabled": true
}

Свойства объекта URL-правила
Свойство	Тип	Описание
`param`	Строка	Имя URL-параметра, с которым работает правило.
`op`	Строка	Оператор правила. См. таблицу операторов ниже.
`arg`	Строка	Аргумент оператора. См. таблицу операторов ниже.
`enabled`	Логический	Включает правило.

Операторы URL-правил
Оператор	Аргумент	Описание
`ASSIGN`	Необязательный	Назначает параметру значение аргумента.
`RENAME`	Необязательный	Меняет имя параметра на значение аргумента.
`DELETE`	Игнорируется	Удаляет параметр.
`EXISTS`	Игнорируется	Проверяет, что параметр существует.
`NEXISTS`	Игнорируется	Проверяет, что параметр не существует.
`REGEX`	Необязательный	Проверяет, что значение параметра совпадает с регулярным выражением в аргументе.
`IREGEX`	Необязательный	Проверяет, что значение параметра совпадает с регулярным выражением в аргументе (без учета регистра).
`NREGEX`	Необязательный	Проверяет, что значение параметра не совпадает с регулярным выражением в аргументе.
`NIREGEX`	Необязательный	Проверяет, что значение параметра не совпадает с регулярным выражением в аргументе (без учета регистра).
`EQ`	Необязательный	Проверяет, что значение параметра равно аргументу.
`NEQ`	Необязательный	Проверяет, что значение параметра не равно аргументу.
`GT`	Необязательный	Проверяет, что значение параметра меньше аргумента.
`GE`	Необязательный	Проверяет, что значение параметра больше или равно аргументу.
`LT`	Необязательный	Проверяет, что значение параметра меньше аргумента.
`LE`	Необязательный	Проверяет, что значение параметра меньше или равно аргументу.

Объект расписания

Объект расписания имеет следующую структуру:

{
  "days": ["Sun", "Sat"],
  "since": "15:30:00",
  "till": "22:15:00"
}

Свойства объекта расписания
Свойство	Тип	Описание
`days`	Массив строк	Дни недели, к которым относится правило: `Mon` — понедельник `Tue` — вторник `Wed` — среда `Thu` — четверг `Fri` — пятница `Sat` — суббота `Sun` — воскресенье
`since`	Строка	Пропускать посетителей со времени суток в формате `HH:MM:SS`, например `15:30:00`.
`till`	Строка	Пропускать посетителей до времени суток в формате `HH:MM:SS`, например `22:15:00`.

Список потоков

GET /streams

Эта точка вызова возвращает список потоков в аккаунте. Список разбивается на страницы, а потоки в нем выводятся в возрастающем лексикографическом порядке их имен.

Поддерживаемые URL-параметры:

Параметр	Тип	Значение по умолчанию	Описание
`page`	Целое число	1	Номер страницы для отображения.
`per-page`	Целое число от 1 до 100	20	Число потоков на страницу.
`name`	Строка	Нет	Выводит только те потоки, в имени которых содержится указанная подстрока (без учета регистра).

Данные о списке потоков

HEAD /streams

Эта точка вызова возвращает заголовки с общей информацией о числе потоков и страниц:

Заголовок	Тип	Описание
`X-Pagination-Total-Count`	Целое число	Общее число потоков.
`X-Pagination-Page-Count`	Целое число	Общее число страниц.

Поддерживаемые URL-параметры:

Параметр	Тип	Значение по умолчанию	Описание
`per-page`	Целое число от 1 до 100	20	Число потоков на страницу.

Получение потока

GET /streams/<ID>

Эта точка вызова возвращает поток <ID>.

Создание потока

POST /streams

Эта точка вызова создает и возвращает новый поток. Укажите объект потока в теле запроса. Все свойства объекта потока имеют значения по умолчанию, поэтому вам нужно указывать только те свойства, значения которых вы хотите задать явно, например {"name":"My Stream"}.

Обновление потока

PATCH /streams/<ID>

Эта точка вызова обновляет поток <ID>. Укажите объект потока в в теле запроса. Вам нужно указать только те свойства, значения которых вы хотите изменить; все остальные свойства останутся неизменными.

Копирование потока

COPY /streams/<ID>

Эта точка вызова копирует поток <ID>. Укажите объект потока в теле запроса — указанные в нем свойства заменят свойства в скопированном потоке, что сэкономит вам дополнительный вызов точки PATCH. Если свойства изменять не требуется, то укажите пустой объект {}.

Удаление потока

DELETE /streams/<ID>

Эта точка вызова удаляет поток <ID>.

PHP-файлы интеграции

Вы можете скачать файлы index.php, filter.php и ajax.php для любого потока при помощи запросов:

Файл	Точка вызова
`index.php` и `filter.php`	`GET https://clients.adspect.ai/getindex.php?sid=<ID>` Вместо `<ID>` укажите ID конкретного потока в Adspect.
`ajax.php`	`GET https://clients.adspect.ai/getindex.php?sid=<ID>&mode=ajax` Вместо `<ID>` укажите ID конкретного потока в Adspect.

Гостевой доступ к статистике

Гостевой доступ к статистике позволяет третьим лицам просматривать заранее определенные фрагменты вашей статистики без необходимости входа в систему. Управление гостевым доступом производится при помощи сохраненных запросов:

Создается сохраненный запрос к статистике, в котором указываются параметры выгрузки отчета (даты и фильтры);
В ответ API передает ID сохраненного запроса;
Гость может выполнить этот сохраненный запрос на странице статистики, указав ID сохраненного запроса в соответствующем поле, либо перейдя по ссылке вида https://clients.adspect.ai/reporting?query_id=<ID>, где вместо <ID> подставляется ID сохраненного запроса.

Примечание

Можно создавать не более 100 сохраненных запросов.

Сохраненный запрос представляется в виде объекта со следующими свойствами:

Свойство	Тип	Описание
`query_id`	Строка	ID сохраненного запроса. Только для чтения.
`owner_id`	Строка	ID аккаунта владельца запроса. Только для чтения.
`date_from`	Целое число или строка	Минимальное Unix-время, начиная с которого выгружается отчет.
`date_to`	Целое число или строка	Максимальное Unix-время, до которого выгружается отчет.
`time_zone`	Строка	Часовой пояс по умолчанию для отображения дат и времени.
`group_by`	Массив строк	Разбивка воронки продаж по умолчанию.
`stream_id`	Массив строк	Фильтр по ID потоков.
`ip_address`	Массив строк	Фильтр по IP-адресам.
`asn`	Массив целых чисел или строк	Фильтр по номерам автономных систем (ASN). ASN могут быть заданы строками вида `AS65536` или `AS1.10`.
`country_code`	Массив строк	Фильтр по кодам стран в двухбуквенном формате.
`os`	Массив строк	Фильтр по операционным системам.
`browser`	Массив строк	Фильтр по браузерам.
`engine`	Массив строк	Фильтр по движкам браузера.
`sub_id`	Массив строк	Фильтр по sub ID.
`click_id`	Массив строк	Фильтр по ID переходов.
`mode`	Массив строк	Фильтр по режимам потока.
`target`	Массив целых чисел	Фильтр по показанным страницам: 0 — белая страница 1–255 — контент-страница с соответствующим порядковым номером

Все поля необязательны. Если тот или иной фильтр не требуется, то его можно не указывать, либо задать значение null (или пустой массив [] там, где типом значения является массив).

Пример:

{
  "query_id": "878efbf1-0fb9-4c69-ad36-40e714b0eeeb",
  "owner_id": "1eb5991f-a25b-68f4-b171-00162501c2b4",
  "date_from": 1577836800,
  "date_to": null,
  "time_zone": "Asia/Dubai",
  "group_by": [],
  "account_id": ["1eb5991f-a25b-68f4-b171-00162501c2b4"],
  "stream_id": ["6792f6ce-f153-439f-b223-f58749f1210f"],
  "ip_address": [],
  "asn": [],
  "country_code": ["HK", "AE"],
  "os": ["iOS", "macOS"],
  "browser": ["Apple Safari"],
  "engine": [],
  "sub_id": [],
  "click_id": [],
  "mode": ["Filter"],
  "target": []
}

Список запросов

GET /reports

Эта точка вызова возвращает список запросов в аккаунте, разбитый на страницы.

Поддерживаемые URL-параметры:

Параметр	Тип	Значение по умолчанию	Описание
`page`	Целое число	1	Номер страницы для отображения.
`per-page`	Целое число от 1 до 100	20	Число запросов на страницу.

Данные о списке запросов

HEAD /reports

Эта точка вызова возвращает заголовки с общей информацией о числе запросов и страниц:

Заголовок	Тип	Описание
`X-Pagination-Total-Count`	Целое число	Общее число запросов.
`X-Pagination-Page-Count`	Целое число	Общее число страниц.

Поддерживаемые URL-параметры:

Параметр	Тип	Значение по умолчанию	Описание
`per-page`	Целое число от 1 до 100	20	Число потоков на страницу.

Получение запроса

GET /reports/<ID>

Эта точка вызова возвращает сохраненный запрос <ID>.

Создание запроса

POST /reports

Эта точка вызова создает и возвращает новый запрос. Укажите объект запроса в теле HTTP-запроса.

Обновление запроса

PATCH /reports/<ID>

Эта точка вызова обновляет запрос <ID>. Укажите объект запроса в теле HTTP-запроса. Вам нужно указать только те свойства, значения которых вы хотите изменить; все остальные свойства останутся неизменными.

Копирование запроса

COPY /reports/<ID>

Эта точка вызова копирует запрос <ID>. Укажите объект запроса в теле HTTP-запроса — указанные в нем свойства заменят свойства в скопированном запросе, что сэкономит вам дополнительный вызов точки PATCH.

Удаление запроса

DELETE /reports/<ID>

Эта точка вызова удаляет запрос <ID>.

API статистики

API статистики предоставляет вам программный доступ к статистике Adspect через две точки вызова:

Воронка продаж для создания агрегированных отчетов;
Лог переходов для получения сырых данных о кликах и конверсиях.

Они функционально идентичны разделу «Статистика» личного кабинета Adspect.

Фильтры

Обе точки вызова поддерживают фильтры в виде URL-параметров для ограничения выборки статистических данных, например:

date_from=1672520400&date_to=1675198800&country_code[]=AE&os[]=iOS&os[]=macOS

Отчет, сформированный с такими фильтрами, будет содержать только клики и конверсии, отвечающие всем условиям:

за январь 2023 года: date_from=1672520400&date_to=1675198800
из Объединенных Арабских Эмиратов: country_code[]=AE
с устройств iOS или macOS: os[]=iOS&os[]=macOS

Совет

Вы можете указывать дату и время в свободном формате вместо временных меток Unix. Например, 1 Jan 2023 или 2023-01-01 вместо 1672520400. Adspect постарается максимально точно распарсить такую строку.

Следующая таблица перечисляет доступные параметры фильтров. Все параметры являются необязательными.

Примечание

Параметры, заканчивающиеся на [], являются массивами: вы можете указать несколько таких параметров, и их значения будут объединены логическим ИЛИ. Например, фильтр os[]=iOS&os[]=macOS отберет те клики и конверсии, которые были сделаны с устройств iOS или macOS.

Параметр	Тип	Описание
`query_id`	Строка	ID сохраненного запроса для гостевого доступа к статистике других пользователей Adspect.
`date_from`	Целое число или строка	Минимальное Unix-время, начиная с которого выгружается отчет.
`date_to`	Целое число или строка	Максимальное Unix-время, до которого выгружается отчет.
`time_zone`	Строка	Часовой пояс для отображения дат и времени, например, `Asia/Dubai`.
`stream_id[]`	Строка	Фильтр по ID потоков.
`ip_address[]`	Строка	Фильтр по IP-адресам.
`asn[]`	Целое число или строка	Фильтр по номерам автономных систем (ASN). ASN могут быть заданы строками вида `AS65536` или `AS1.10`.
`country_code[]`	Строка	Фильтр по кодам стран в двухбуквенном формате.
`os[]`	Строка	Фильтр по операционным системам.
`browser[]`	Строка	Фильтр по браузерам.
`engine[]`	Строка	Фильтр по движкам браузера.
`sub_id[]`	Строка	Фильтр по sub ID.
`click_id[]`	Строка	Фильтр по ID переходов.
`mode[]`	Строка	Фильтр по режимам потока.
`target[]`	Целое число	Фильтр по показанной странице: 0 — белая страница 1–255 — контент-страница с соответствующим порядковым номером

Воронка продаж

GET /reports/funnel

Эта точка вызова возвращает агрегированный отчет (воронку продаж). Каждая строка отчета является JSON-массивом, порядок элементов которого соответствует порядку параметров group_by[] и затем порядку параметров metrics[].

Следующая таблица перечисляет URL-параметры, специфичные для точки вызова воронки продаж.

Примечание

Параметры, заканчивающиеся на [], являются массивами: вы можете указать несколько таких параметров, и их значения будут объединены. Например, разбивка group_by[]=date&group_by[]=stream_id сгруппирует воронку сначала по дате, а затем по ID потока.

Аналогично, параметры metrics[]=clicks&metrics[]=money_hits добавят в отчет колонки числа кликов и переходов на контент в указанном порядке.

Параметр	Тип	Описание
`group_by[]`	Строка, необязательный	Добавляет колонку разбивки в отчет.
`metrics[]`	Строка, обязательный	Добавляет колонку метрики в отчет.

Колонки разбивки воронки продаж

Следующая таблица перечисляет доступные колонки разбивки воронки продаж для URL-параметра group_by[].

Колонка	Описание
`date`	Дата в формате `YYYY-MM-DD`.
`month`	Месяц в формате `YYYY-MM`.
`stream_id`	ID потока.
`asn`	Номер автономной системы (ASN).
`country_code`	Двухбуквенный код страны.
`os`	Операционная система.
`browser`	Браузер.
`engine`	Движок браузера.
`language`	Язык браузера.
`sub_id`	Sub ID.
`mode`	Режим потока в момент перехода.
`target`	Показанная страница: 0 — белая страница 1–255 — контент-страница с соответствующим порядковым номером
`tag`	Тег, обозначающий причину блокировки перехода.

Совет

Этот список можно получить при помощи точки вызова GET /collections/query-group-by

Колонки метрик воронки продаж

Следующая таблица перечисляет доступные колонки метрик воронки продаж для URL-параметра metrics[].

Важно

Пожалуйста, указывайте в API-запросе только те метрики, которые вам нужны.

Метрика	Описание
`clicks`	Общее число переходов.
`uniques`	Приблизительное число уникальных посетителей с точки зрения уникальности их IP-адресов.
`fingerprints`	Число посетителей, которые при обработке успешно сформировали и передали JavaScript-отпечаток. По различным причинам это число может быть меньше, чем общее число переходов, но как правило разницу составляют «тупые» боты, которые не поддерживают JavaScript.
`money_hits`	Число показов контент-страницы.
`money_uniques`	Число уникальных посетителей, которым была показана контент-страница.
`safe_hits`	Число показов белой страницы.
`givt`	«General invalid traffic» — число посетителей, заблокированных по поверхностным признакам, таким как IP-адрес, строка user agent, таргетинг и т.п.
`sivt`	«Sophisticated invalid traffic» — число посетителей, заблокированных алгоритмами Adspect на основании их JavaScript-отпечатков.
`mia`	Число посетителей, которые не смогли сформировать и отправить JavaScript-отпечаток (технические потери). Как упоминалось ранее, это как правило «тупые» боты с ограниченной поддержкой JavaScript. Другая распространенная причина технических потерь — сетевые задержки, особенно наглядные при работе с трафиком с плохим Интернет-соединением типа 3G/EDGE: посетители успевают закрыть окно или вкладку прежде, чем отпечаток будет отправлен.
`quality`	Процент показов контент-страницы от общего числа кликов. Это наилучший показатель для оценки качества трафика в целом и может быть использован для сравнения различных источников, площадок, спотов и т.п. Особую ценность представляет сбор черных или белых списков площадок на основании их качества.
`expenses`	Расход, считаемый как сумма цен переходов, если они были переданы через параметр ссылки.
`conversions`	Число конверсий.
`cr`	Коэффициент конверсии = конверсии : клики.
`revenue`	Доход, считаемый как сумма выплат по конверсиям, если они были переданы через postback.
`profit`	Прибыль или убыток = доход − расход.
`roi`	Возврат инвестиций = прибыль : расход.
`cpc`	Средняя цена перехода = расход : переходы.
`cpm`	Средняя стоимость тысячи переходов = CPC ∙ 1000.
`cpa`	Средняя цена лида = расход : конверсии.
`epl`	Средний доход с лида = доход : конверсии.
`ecpc`	Средний доход с перехода = доход : переходы.
`ecpm`	Средний доход с тысячи переходов = доход : переходы ∙ 1000.

Совет

Этот список можно получить при помощи точки вызова GET /collections/query-funnel-metrics

Примеры

Пример #1: получение статистики для всех потоков с группировкой по ID потока:

GET /reports/funnel?group_by[]=stream_id&metrics[]=clicks&metrics[]=money_hits&metrics[]=safe_hits&metrics[]=quality

["1ec5880e-bcb6-49b8-9778-a31d22b70708", "1453", "754", "699", 0.5189263592567103]
["07ac03df-268e-41ff-84ba-adfe2241beb2", "3219", "2034", "1125", 0.6318732525629077]
["7a3d39f7-fe75-431e-8be6-9ea9b56b1e4a", "179", "0", "179", 0]
["9f79b75f-20ef-4654-8141-b8bbb2124ec4", "65", "0", "65", 0]

Пример #2: получение статистики по дням для потока с ID 07ac03df-268e-41ff-84ba-adfe2241beb2:

GET /reports/funnel?group_by[]=date&metrics[]=clicks&metrics[]=money_hits&metrics[]=safe_hits&metrics[]=quality&stream_id[]=07ac03df-268e-41ff-84ba-adfe2241beb2

["2024-04-01", "931", "343", "582", 0.3684210526315789]
["2024-04-02", "1166", "829", "300", 0.7109777015437393]
["2024-04-03", "1113", "855", "243", 0.7681940700808625]
["2024-04-04", "9", "7", "0", 0.7777777777777778]

Лог переходов

GET /reports/log

Эта точка вызова возвращает лог переходов. Каждая строка отчета является JSON-массивом, порядок элементов которого соответствует порядку параметров columns[].

Следующая таблица перечисляет URL-параметры, специфичные для точки вызова лога переходов.

Примечание

Параметры, заканчивающиеся на [], являются массивами: вы можете указать несколько таких параметров, и их значения будут объединены. Например, параметры columns[]=timestamp&columns[]=ip_address добавят в отчет колонки временной метки и IP-адреса в указанном порядке.

Параметр	Тип	Описание
`columns[]`	Строка, обязательный	Добавляет колонку лога переходов в отчет.

Колонки лога переходов

Следующая таблица перечисляет доступные колонки лога переходов для URL-параметра columns[].

Важно

Пожалуйста, указывайте в API-запросе только те колонки, которые вам нужны.

Колонка	Описание
`timestamp`	Дата и время перехода или конверсии.
`ip_address`	IP-адрес.
`asn`	Номер автономной системы (ASN).
`account_id`	ID аккаунта.
`stream_id`	ID потока.
`country_code`	Двухбуквенный код страны.
`os`	Операционная система.
`browser`	Браузер.
`engine`	Движок браузера.
`languages`	Список языков браузера.
`cost`	Цена перехода или выплата по конверсии.
`sub_id`	Sub ID.
`click_id`	ID перехода.
`mode`	Режим потока в момент перехода.
`sequence`	Этап обработки перехода: 0 — базовая проверка 1 — проверка JavaScript-отпечатка 255 — конверсия
`target`	Показанная страница: 0 — белая страница 1–255 — контент-страница с соответствующим порядковым номером
`tags`	Список тегов, обозначающих причины блокировки перехода.

Совет

Этот список можно получить при помощи точки вызова GET /collections/query-log-columns

Примеры

Получение лога переходов за сегодня для потока с ID 07ac03df-268e-41ff-84ba-adfe2241beb2:

GET /reports/log?columns[]=timestamp&columns[]=ip_address&columns[]=country_code&columns[]=target&date_from=today&date_to=tomorrow&stream_id[]=07ac03df-268e-41ff-84ba-adfe2241beb2

["2024-04-01 00:00:00", "23.83.90.68", "US", 0]
["2024-04-01 00:00:00", "2a03:2880:30ff:8::33", "SE", 0]
["2024-04-01 00:00:00", "47.128.19.245", "SG", 0]
["2024-04-01 00:00:00", "176.223.109.119", "US", 0]
["2024-04-01 00:00:00", "2a03:2880:20ff:76::33", "US", 0]
["2024-04-01 00:00:00", "89.248.163.208", "NL", 0]
["2024-04-01 00:00:00", "47.128.98.197", "SG", 0]
["2024-04-01 00:00:00", "47.128.25.161", "SG", 0]
["2024-04-01 00:00:00", "95.90.237.130", "DE", 0]
["2024-04-01 00:00:00", "176.5.15.114", "DE", 0]