Reports
Reports endpoint will be responsible for gracefully pulling of necessary advertising data (clicks, impressions, spend, etc) per specified platform
GET to URL
Main host - https://www.adverity.com/
Report endpoint - mint/reports/platform/{platform_name}/account/{account_id}/data
Final endpoint = Main host + Report endpoint = https://www.adverity.com/mint/reports/platform/{platform_name}/account/{account_id}/data
REPORT FILE FORMAT
Either JSON or CSV can be used.
REQUEST RATE FREQUENCY
We’ll need the reports per account for the specified platform:
historical data - 1-YEAR AGO DATE RANGE
weekly data - 7-DAY AGO DATE RANGE
Historical data is needed once per account for the specified campaigns. If new campaign is added to account we’ll pull it 1 time.
Weekly data will be pulled every day per account for the specified campaigns. It’s needed to have always refreshed reports because external APIs can update the metrics -> its values can be changed during last week.
PAGINATION
In case of big amount of data (rows) per request we can use pagination and parse the data page by page for example if number of rows is more than 100000.
REQUEST BODY
The data filtering should be used while requesting the data including it in request body:
CAMPAIGNS - list of campaigns (ids) (minimum 1 campaign can be added to list)
DATE RANGE - start_date / end_date in format YYYY-MM-DD
FREQUENCY - DAILY only
DIMENSIONS - list of dimension columns (“date”, “campaign_id”, “ad_group_id”, “ad_id”)
METRICS - list of metric columns (“completed_views_full”, “completed_views_first”, “completed_views_mid”, “completed_views_third”, “spend”, “video_start”, “video_views”, “platform_conversions”, “clicks”, “impressions”)
DIMENSIONS and METRICS can be unified into the single COLUMNS column containing the list of dimensions and metrics
EXAMPLE BODY
{
"campaigns": [17957, 23457, 90292, 17283],
"start_date": "2024-05-01",
"end_date": "2024-06-10",
"frequency": "daily",
"dimensions": ["date", "campaign_id", "ad_group_id", "ad_id"],
"metrics": ["completed_views_full", "completed_views_first", "completed_views_mid", "completed_views_third", "spend", "video_start", "video_views", "platform_conversions", "clicks", "impressions"]
}
Metrics
Metric |
Description |
---|---|
clicks |
The number of times a person has clicked on an ad |
completed_views_first |
Video viewed calculated at 100% at 25% of the duration |
completed_views_full |
Metric that count the times that a video ad is viewed till the end |
completed_views_mid |
Video viewed calculated at 100% at 50% of the duration |
completed_views_third |
Video viewed calculated at 100% at 75% of the duration |
impressions |
The number of times your ad has been viewed |
spend |
Amount of money spent |
video_start |
Number of Video Start |
video_views |
Number of Video Views |
platform_conversions |
Number of Conversions |
Dimensions
Metric |
Description |
---|---|
date |
The date in format YYYY-MM-DD |
campaign_id |
ID for advertising campaign |
ad_group_id |
ID for advertising group within campaign |
ad_id |
ID for advertising ad within group |