If you want to collect reporting data from Ad Revenue Insights, this short guide will help you build the API call and explain the basics.
The Ad Revenue Insights module includes a Pull API, allowing you to use the collected data in other systems or simply for data exports.
Preparations
Before you can access your data, there are a few steps to follow:
-
User: You can either use an existing Admin User in the system or create a new Admin User to serve as a dedicated API user. We recommend creating a new Admin User specifically for the API to avoid potential issues if you need to deactivate other users. A clean, dedicated Admin user is the preferred approach.
-
Credentials: Obtain the credentials for the Admin User you plan to use as the API connection user.
-
API URL: Ensure you have the correct URL. Each client has a unique domain URL, and your account is no exception. Please contact your Technical Account Manager to confirm the correct domain to use.
Script Example
This example highlights the functions with brief explanations, which will be covered in more detail in a later section:
from datetime import datetime
import requests
import json
import os
import re
import csv
import collections
url = "insert_your_domain"
credentials = {"email" : 'your-email',"password" : 'your_password'}
date = '2022-04-11'
csvFileName = 'output_' + date + '.csv'
response = requests.post(url + "/users/login",data=credentials)
if response.status_code > 400:
raise Exception('Status code: '+str(response.status_code))
token_value = response.json()["result"]["token"]
def runCommand(path, params):
resp = requests.post(
url=url + path,
headers={
"accept": "*/*",
"authorization": token_value,
"content-type": "application/json"
},
data=json.dumps(params)
)
if resp.status_code >= 400:
raise Exception('Status code: '+str(resp.status_code))
return resp.json()['result']
groupBy = [
'date', # Date
'siteId', # Site
'publisherId', # Publisher
'placementId', # Placement
'sourceId', # Source
'sspId', # SSP
'revenueType', # Revenue type
'advertiserNr', # Advertiser
'buyerNr', # Buyer
'dealNr', # Deal
'bidderNr', # DSP
'size', # Crative Size
'paymentTypeId', # Payment type
'mediaTypeId', # Media type
'dealTypeId', # Deal type
'orderNr', # Order
'lineItemNr', # Line item
]
sums = [
'revenue', # API Gross revenue
'revenueAfterSsp', # Total revenue
'soldImpressions', # Sold impressions
'clicks', # Clicks
'ism', # Viewable Imps
'ismMeasured', # Viewable measured
]
reportSettings = {
"customCommand": "reportProgrammatic",
"reportFormat": "array", # new array-format..
"start": date,
"end": date,
# set the below to something high to include all advertisers/buyers etc without grouping them into "[Smaller advertisers]" etc.
"maxAdvertisers": '10000000',
"attributes": {
"advertiserNr": {
"externalId": True,
},
"dealNr": {
"dealId": True,
"name": True,
},
"sourceId": {
"id": True,
"name": True,
}
},
"groupBy": groupBy,
"sums": sums,
# uncomment the 'advMappingId'-row to not use the default advertiser mappings, that would be the same as using this report UI-setting:
# Other options => Advertiser mapping => [Ignore default mappings]
# "advMappingId": "no_mapping_magic",
}
result = runCommand("/reports", reportSettings)
arr = result['data']
if len(arr):
with open(csvFileName, 'w') as file:
wr = csv.writer(file, quoting=csv.QUOTE_ALL)
wr.writerow(arr[0].keys())
for row in arr:
wr.writerow(row.values())
else:
print("Report is empty")
# List import-status for all systems:
# "completed" => OK
# "failed" => Error at Import
# "none" => Import not run (yet)
ssps = runCommand("/ssps", { "customCommand": "getAll" })
tasks = runCommand("/tasks", { "customCommand": "getTasks", "start": date, "end": date, "type": "SSPimport" })
print("====== Import status by system ======")
for ssp in ssps:
if ssp['active']: # Only include active systems
task = next(t for t in tasks if t['objectId'] == ssp['id'])
state = task['state'] if task else "none"
print("\t" + ssp['name'] + ": " + state)
print("Done")
1. Setting up the credentials, specifying the domain to access, and naming the output file:
url = "INSERT_YOUR_DOMAIN"
credentials = {"email" : 'bla',"password" : 'bla'}
date = '2022-04-11'
csvFileName = 'output_' + date + '.csv'
2. Options for grouping your output:
groupBy = [
'date', # Date
'siteId', # Site
'publisherId', # Publisher
'placementId', # Placement
'sourceId', # Source
'sspId', # SSP
'revenueType', # Revenue type
'advertiserNr', # Advertiser
'buyerNr', # Buyer
'dealNr', # Deal
'bidderNr', # DSP
'size', # Crative Size
'paymentTypeId', # Payment type
'mediaTypeId', # Media type
'dealTypeId', # Deal type
'orderNr', # Order
'lineItemNr', # Line item
This corresponds to the dimensions in the standard GUI reporting.
3. Selecting the metrics you wish to report on:
Anything that can be reported on in Yield UI, can be exported via the API Pull.
sums = [
'revenue', # API Gross revenue
'revenueAfterSsp', # Total revenue
'soldImpressions', # Sold impressions
'clicks', # Clicks
'ism', # Viewable Imps
'ismMeasured', # Viewable measured
4. Putting the settings together:
reportSettings = {
"customCommand": "reportProgrammatic",
"reportFormat": "array", # new array-format..
"start": date,
"end": date,
# set the below to something high to include all advertisers/buyers etc without grouping them into "[Smaller advertisers]" etc.
"maxAdvertisers": '10000000',
"attributes": {
"advertiserNr": {
"externalId": True,
},
"dealNr": {
"dealId": True,
"name": True,
},
"sourceId": {
"id": True,
"name": True,
}
},
"groupBy": groupBy,
"sums": sums,
# uncomment the 'advMappingId'-row to not use the default advertiser mappings, that would be the same as using this report UI-setting:
# Other options => Advertiser mapping => [Ignore default mappings]
# "advMappingId": "no_mapping_magic",
This is where you compile the options listed above into a coherent report.
-
maxAdvertisers: Use this to limit the number of advertisers if there is a very large number.
-
attributes: Additional information that can be included if needed.
-
advMapping: Determines whether to apply the advertiser mappings used in the GUI.