TargetADS API's

TargetADS API

API TargetADS предоставляют программный доступ к данным рекламных кампаний и аналитическим отчётам. Они объединяет несколько типов запросов: сырые события, агрегированные метрики, отчёты по пути к конверсии и служебные справочные методы.

Данная справка описывает общую структуру API и основные принципы работы с ним.

Ключевые возможности

Raw Data Reports

Возвращает сырые пользовательские взаимодействия: просмотры страниц, события, клики, показы и другие действия.
Подходит для построения собственных аналитических моделей, воронок и детального анализа.
Aggregated Reports

Предоставляет агрегированные медийные метрики и целевые показатели. Могут включать атрибуцию по различным моделям
и временным окнам.
Path To Conversion

Содержит список пользовательских взаимодействий, ведущих к целевому событию. В отчёте доступны аттрибуционные веса, которые помогают анализировать вклад каналов.
Meta API

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

Базовый URL

Все запросы отправляются на основной адрес:

https://api.targetads.io

Базовый URL одинаков для всех типов отчётов и служебных методов.

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

Доступ к API осуществляется через авторизацию по Bearer Token.
Передайте токен в HTTP-заголовке при каждом запросе:

Authorization: Bearer <TOKEN>

Токен доступа выдаётся в пользовательском интерфейсе платформы и связан с конкретным проектом (project_id) и набором разрешений.

Получение списка кампаний

curl -X GET "https://api.targetads.io/v1/meta/campaigns?project_id=12486&active=true" \
  -H "Authorization: Bearer YOUR_TOKEN"

API Endpoints
__________________________________________________________________________________

Эти методы составляют основу API и используются большинством интеграций.

Лимиты и ограничения

API имеет технические ограничения, которые следует

учитывать при построении интеграции:

Rate Limiting
- 40 запросов в минуту на project_id
- Лимит применяется с использованием sliding window алгоритма
- При превышении лимита API возвращает `429 Too Many Requests`

Размер данных
- Path to Conversion: максимум 1,000,000 записей на запрос
- Raw Reports: максимум 10,000,000 записей на запрос
- Aggregated Reports: максимум 100,000 записей на запрос

Таймауты
- Таймаут запроса: 300 секунд (5 минут)
- Рекомендуется разбивать большие запросы на несколько меньших по кампаниям

Обработка больших объемов данных

Для избежания таймаутов при работе с большими объемами данных используйте стратегию разделения запросов:

1. Получите список кампаний через `/v1/meta/campaigns`
2. Разделите запросы по 5-10 кампаниям
3. Используйте параметры `Offset` и `Limit` для пагинации

Эти ограничения помогают стабильно обрабатывать большие объёмы данных и обеспечивать производительность сервиса.

Агрегированный отчет

Ответ отчётных методов имеет унифицированную структуру.
Вне зависимости от типа отчёта сервер возвращает три ключевых элемента:
- Columns — массив имён полей
- Rows — массив строк, где каждая строка соответствует набору значений
- CountRows — количество строк, включённых в ответ

Такой формат упрощает дальнейшую обработку и загрузку данных в BI-системы.

curl -X POST "https://api.targetads.io/v1/reports/agg_report?project_id=12486" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "ResponseType": "JSON",
    "Fields": ["EventDate", "MediaCampaign"],
    "MediaMetrics": ["Impressions", "Clicks", "CTR"],
    "TargetMetrics": ["TargetEventCount"],
    "InteractionFilter": {
      "DateFrom": "2024-01-01",
      "DateTo": "2024-01-31"
    },
    "AttributionModel": "mli",
    "AttributionWindow": "30",
    "DateGrouping": "day"
  }'

Модели атрибуции
__________________________________________________________________________________

API поддерживает следующие модели атрибуции:

Временные окна атрибуции:

Доступные окна: `7`, `15`, `30`, `60`, `90` дней

Группировка по времени

Поддерживаемые периоды группировки:
- `day` — день
- `week` — неделя
- `month` — месяц
- `quarter` — квартал

- `year` — год

Обработка ошибки
__________________________________________________________________________________

Формат ошибки:

{
  "ErrorCode": 400,
  "ErrorMessage": "validate error",
  "Errors": [
    {
      "Error": true,
      "FailedField": "Fields",
      "Tag": "required",
      "Value": null
    }
  ]
}