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

AUTHORISATION

OAUTH2 is recommended to be used for authorisation. Single Adverity bearer token (without expiration) can be used to get API access.

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