Aggregated data API предоставляет агрегированные отчёты по медийным метрикам
и целевым событиям, включая поддержку разных моделей атрибуции. API помогает
анализировать эффективность рекламных кампаний на разных уровнях детализации.
POST /v1/reports/agg_report?project_id={project_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"
}
Временные окна атрибуции:
- `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"
}' 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