Aggregated data API

Aggregated data API предоставляет агрегированные отчёты по медийным метрикам

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

анализировать эффективность рекламных кампаний на разных уровнях детализации.

Endpoint
URL, по которому отправляются запросы к API
POST /v1/reports/agg_report?project_id={project_id}
Параметры запроса
Query-параметры
__________________________________________________________________________________

`project_id` (обязательный) - ID проекта
Тело запроса
{
  "ResponseType": "JSON",
  "Fields": ["EventDate", "MediaCampaign"],
  "MediaMetrics": ["Impressions", "Clicks", "CTR"],
  "TargetMetrics": ["TargetEventCount", "TargetEcomAmount"],
  "InteractionFilter": {
    "DateFrom": "2024-01-01",
    "DateTo": "2024-01-31"
  },
  "AttributionModel": "mli",
  "AttributionWindow": "30",
  "DateGrouping": "day"
}
Параметры
__________________________________________________________________________________
InteractionFilter
__________________________________________________________________________________
TargetFilter
__________________________________________________________________________________
Модели атрибуции
API поддерживает следующие модели атрибуции:

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


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

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

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

- `year` — год

Поля группировки
___________________________________________________________________________
Медийные метрики
___________________________________________________________________________
Видео метрики
___________________________________________________________________________
Целевые метрики
___________________________________________________________________________
Примеры запросов
Базовый отчет по кампаниям и дням
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", "Reach"],
    "TargetMetrics": ["TargetEventCount"],
    "InteractionFilter": {
      "DateFrom": "2024-01-01",
      "DateTo": "2024-01-31"
    },
    "AttributionModel": "mli",
    "AttributionWindow": "30",
    "DateGrouping": "day"
  }'
Анализ эффективности по источникам
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": ["MediaSource", "MediaCampaign"],
    "MediaMetrics": ["Impressions", "Clicks", "Reach", "Frequency"],
    "TargetMetrics": ["TargetEventCount", "TargetEcomAmount"],
    "InteractionFilter": {
      "DateFrom": "2024-01-01",
      "DateTo": "2024-01-31",
      "MediaCampaignId": [12345, 12346, 12347]
    },
    "TargetFilter": {
      "EventType": ["Purchase"]
    },
    "AttributionModel": "fl",
    "AttributionWindow": "30",
    "DateGrouping": "day"
  }'
E-commerce отчет с группировкой по неделям
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", "TargetEcomItemsCategory1"],
    "MediaMetrics": ["Impressions", "Clicks"],
    "TargetMetrics": ["TargetEventCount", "TargetEcomAmount", "TargetEcomQuantity"],
    "InteractionFilter": {
      "DateFrom": "2024-01-01",
      "DateTo": "2024-03-31"
    },
    "TargetFilter": {
      "EventType": ["Purchase"]
    },
    "AttributionModel": "mli",
    "AttributionWindow": "30",
    "DateGrouping": "week"
  }'
Видео метрики по креативам
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": ["MediaCampaign", "MediaCreative"],
    "MediaMetrics": [
      "Impressions",
      "VideoStart",
      "VideoQ25",
      "VideoQ50",
      "VideoQ75",
      "VideoComplete",
      "VideoSkip"
    ],
    "InteractionFilter": {
      "DateFrom": "2024-01-01",
      "DateTo": "2024-01-31",
      "MediaCampaignId": [12345]
    },
    "AttributionModel": "mli",
    "AttributionWindow": "30",
    "DateGrouping": "day"
  }'
Анализ качества трафика
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",
      "GIVT",
      "PartOfGIVT",
      "BehaviorFraudImpressions",
      "HiddenFraudImpressions",
      "VisibleImpressions"
    ],
    "InteractionFilter": {
      "DateFrom": "2024-01-01",
      "DateTo": "2024-01-31"
    },
    "AttributionModel": "mli",
    "AttributionWindow": "30",
    "DateGrouping": "day"
  }'
Формат ответа
Успешный ответ
{
  "data": [
    {
      "EventDate": "2024-01-15",
      "MediaCampaign": "Campaign Name 1",
      "Impressions": "15000",
      "Clicks": "450",
      "CTR": "3.0",
      "Reach": "8500",
      "TargetEventCount": "120.5"
    },
    {
      "EventDate": "2024-01-16",
      "MediaCampaign": "Campaign Name 1",
      "Impressions": "16200",
      "Clicks": "520",
      "CTR": "3.2",
      "Reach": "9100",
      "TargetEventCount": "135.0"
    }
  ],
  "count": 2
}
Ошибка валидации
{
  "ErrorCode": 400,
  "ErrorMessage": "validate error",
  "Errors": [
    {
      "Error": true,
      "FailedField": "AttributionModel",
      "Tag": "required",
      "Value": null
    }
  ]
}

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


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

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


Максимум записей: 100,000

Минимум полей группировки: 2

Максимум кампаний в фильтре: 20

Rate limit: 40 запросов в минуту

Таймаут: 300 секунд

Рекомендации
Выбор модели атрибуции
# Для performance кампаний (оценка последнего касания)
attribution_model = "mli"

# Для brand awareness (оценка всего пути)
attribution_model = "fl"

# Для более справедливой оценки с учетом времени
attribution_model = "mtd"
Оптимизация запросов
# Группируйте по крупным периодам для обзора
date_grouping = "month"

# Используйте день для детального анализа коротких периодов
date_grouping = "day"  # только для периодов до 2-3 месяцев
Работа с большими данными
def get_aggregated_by_campaigns(project_id, date_from, date_to):
    """Разделение запроса по кампаниям"""
    campaigns = get_campaigns(project_id, active=True)

    all_data = []
    for batch in chunks(campaigns, 10):  # По 10 кампаний
        campaign_ids = [c['placement_id'] for c in batch]

        response = get_agg_report(
            project_id=project_id,
            campaign_ids=campaign_ids,
            date_from=date_from,
            date_to=date_to
        )
        all_data.extend(response['data'])

    return all_data
Расчет производных метрик
def calculate_metrics(data):
    """Расчет CPA, ROAS и других метрик"""
    for row in data:
        impressions = float(row.get('Impressions', 0))
        clicks = float(row.get('Clicks', 0))
        conversions = float(row.get('TargetEventCount', 0))
        revenue = float(row.get('TargetEcomAmount', 0))

        # Conversion Rate
        row['CR'] = (conversions / clicks * 100) if clicks > 0 else 0

        # Viewable CTR
        visible_impr = float(row.get('VisibleImpressions', 0))
        row['vCTR'] = (clicks / visible_impr * 100) if visible_impr > 0 else 0

    return data
Сравнение моделей атрибуции
def compare_attribution_models(project_id, date_from, date_to):
    """Сравнение разных моделей атрибуции"""
    models = ['mli', 'mfi', 'ml', 'fl']
    results = {}

    for model in models:
        response = get_agg_report(
            project_id=project_id,
            fields=['MediaCampaign'],
            media_metrics=['Impressions', 'Clicks'],
            target_metrics=['TargetEventCount'],
            date_from=date_from,
            date_to=date_to,
            attribution_model=model,
            attribution_window='30',
            date_grouping='month'
        )
        results[model] = response['data']

    return results