Authentication
The Advertiser API uses "Basic Authentication" to authenticate users, using the Advertiser's Via credentials. An advertiser will only be able to see his/her campaigns.
Example of Basic Authentication
Login: youremail@digitalturbine.com
Password: password123
Reports
Unversioned
See the newest version of the API
*Please note, Appia endpoints will continue to work (i.e. ..via.appia.com..)
URL(s):
JSON Format: https://via.digitalturbine.com/api/report/advertiser/performance.json
XML Format: https://via.digitalturbine.com/api/report/advertiser/performance.xml
Based on Accept Header specification: https://via.digitalturbine.com/api/report/advertiser/performance
Version 1
URL(s):
JSON Format: https://via.digitalturbine.com/api/report/advertiser/v1/performance.json
XML Format: https://via.digitalturbine.com/api/report/advertiser/v1/performance.xml
Based on Accept Header specification: https://via.digitalturbine.com/api/report/advertiser/v1/performance
Request Parameters - All parameters must be in camel case - i.e., startDate, not startdate
| Field | Required | Description |
|---|
| startDate | No | Will not report on data collected before the start date. Required if endDate is present. Cannot be today. Defaults to yesterday. |
| endDate | No | Will not report on data collected after the end date. Required if startDate is present. Cannot be today. Must be within 90 days of startDate. Defaults to yesterday. |
| campaignIds | No | Comma separated list of Campaign Ids to report on. If not present, all Campaigns for the user will be displayed. |
Format
https://via.digitalturbine.com/api/report/advertiser/performance?startDate=<yyyy-MM-dd>&endDate=<yyyy-MM-dd>&campaignIds=X,Y,Z
Example
https://via.digitalturbine.com/api/report/advertiser/performance?startDate=2013-10-01&endDate=2013-10-31&campaignIds=1001,2333
Response Parameters
| Field | Description | Type |
|---|
| startDate | yyyy-MM-dd | Date |
| endDate | yyyy-MM-dd | Date |
| clickCount | Number of clicks for all campaigns | Integer |
| preloadCount | Number of preloads for all campaigns | Integer |
| installCount | Number of installs for all campaigns | Integer |
| ctr | CTR for all campaigns, or for specific tier | Float |
| spend | Spending for all campaigns, or for specific tier | Float |
| cpi | CPIfor all campaigns, or for specific tier | Float |
| conversionRate | Conversion rate (Installs / Preloads) | Float |
| campaignId | Digital Turbine's numerical identifier for the campaign | Integer |
| campaignName | The headline text for the campaign | String |
| platform | The platform the campaign is running on | String |
| siteId | Digital Turbine's numerical identifier for a device | Integer |
| appIdentifier | iTunes ID or Android Package Name | String |
| name | Name of the tier | String |
| countryCode | ISO 2 letter country code | String |
| countryName | Country name | string |
Sample Response (JSON)
{"performance":{"startDate":"2021-04-07","endDate":"2021-04-07","clickCount":14,"installCount":14,"preloadCount":0,"conversionRate":1.0000,"ctr":null,"spend":70.00,"cpi":5.00,"tiers":[{"name":"Default","clickCount":14,"installCount":14,"preloadCount":0,"conversionRate":1.0000,"ctr":null,"spend":70.00,"cpi":5.00}],"countries":[{"countryCode":"US","countryName":"United States","clickCount":14,"installCount":14,"preloadCount":0,"conversionRate":1.0000,"ctr":null,"spend":70.00,"cpi":5.00}],"campaigns":[{"campaignId":11111,"campaignName":"DT Test","appIdentifier":"com.google","platform":"ANDROID","sites":[{"siteId":12605,"tiers":[{"name":"Default","clickCount":14,"installCount":14,"preloadCount":0,"conversionRate":1.0000,"ctr":null,"spend":70.00,"cpi":5.00}],"countries":[{"countryCode":"US","countryName":"United States","clickCount":14,"installCount":14,"preloadCount":0,"conversionRate":1.0000,"ctr":null,"spend":70.00,"cpi":5.00}],"days":[{"date":"2021-04-07","tiers":[{"name":"Default","clickCount":14,"installCount":14,"preloadCount":0,"conversionRate":1.0000,"ctr":null,"spend":70.0000,"cpi":5.00}]}]}]}]}}
Sample Response (XML)
<report>
<performance>
<startDate>2018-09-12</startDate>
<endDate>2018-09-12</endDate>
<clickCount>0</clickCount>
<installCount>3489</installCount>
<preloadCount>19542</preloadCount>
<conversionRate>0.1785</conversionRate>
<ctr xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:nil="true"/>
<spend>6334.35</spend>
<cpi>1.82</cpi>
<tiers>
<tier>
<name>Default</name>
<clickCount>0</clickCount>
<installCount>3489</installCount>
<preloadCount>19542</preloadCount>
<conversionRate>0.1785</conversionRate>
<spend>6334.35</spend>
<cpi>1.82</cpi>
</tier>
</tiers>
<countries>
<country>
<countryCode>US</countryCode>
<countryName>United States</countryName>
<clickCount>0</clickCount>
<installCount>3489</installCount>
<preloadCount>19542</preloadCount>
<conversionRate>0.1785</conversionRate>
<spend>6334.35</spend>
<cpi>1.82</cpi>
</country>
</countries>
<campaigns>
<campaign>
<campaignId>90909</campaignId>
<campaignName>APPIAGame-US_Generic_Ignite_CPI</campaignName>
<appIdentifier>com.appia.android/appIdentifier>
<platform>ANDROID</platform>
<sites>
<site>
<siteId>9090</siteId>
<tiers>
<tier>
<name>Default</name>
<clickCount>0</clickCount>
<installCount>214</installCount>
<preloadCount>1873</preloadCount>
<conversionRate>0.1143</conversionRate>
<spend>181.90</spend>
<cpi>0.85</cpi>
</tier>
</tiers>
<countries>
<country>
<countryCode>US</countryCode>
<countryName>United States</countryName>
<clickCount>0</clickCount>
<installCount>214</installCount>
<preloadCount>1873</preloadCount>
<conversionRate>0.1143</conversionRate>
<spend>181.90</spend>
<cpi>0.85</cpi>
</country>
</countries>
<days>
<day>
<date>2018-09-12</date>
<tiers>
<tier>
<name>Default</name>
<clickCount>0</clickCount>
<installCount>214</installCount>
<preloadCount>1873</preloadCount>
<conversionRate>0.1143</conversionRate>
<spend>181.9000</spend>
<cpi>0.85</cpi>
</tier>
</tiers>
</day>
</days>
</site>
</sites>
</campaign>
</campaigns>
</performance>
</report>
Sample Error Response
<report>
<errors>startDate must be earlier than 2018-09-13</errors>
<errors>endDate must be earlier than 2018-09-13</errors>
</report>
Sample No Data Response (JSON)
{"performance":{"startDate":"2021-02-11","endDate":"2021-02-11","clickCount":0,"installCount":0,"preloadCount":0,"conversionRate":0.0000,"ctr":null,"spend":0.00,"cpi":0.00,"tiers":[],"countries":[],"campaigns":[]}}
Sample No Data Response (XML)
<report>
<performance>
<startDate>2018-09-12</startDate>
<endDate>2018-09-12</endDate>
<clickCount>0</clickCount>
<installCount>0</installCount>
<preloadCount>0</preloadCount>
<conversionRate>0.0000</conversionRate>
<ctr xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:nil="true"/>
<spend>0.00</spend>
<cpi>0.00</cpi>
<tiers/>
<countries/>
<campaigns/>
</performance>
</report>
Sample Python Script:
This script will summarize the data by campaign ID, site ID, spend, install count, preload count, and conversion rate:
import json
import csv
import requests
import pandas as pd
from requests.auth import HTTPBasicAuth
#change dates as needed
start_date = '2018-11-26'
end_date = '2018-12-03'
#enter your credentials here
username = ''
password = ''
url = 'https://via.appia.com/api/report/advertiser/performance?startDate=%s&endDate=%s' % (start_date, end_date)
print(url)
json_response = requests.get(url, auth=HTTPBasicAuth(username,password)).json()
campaigns = json_response["performance"]["campaigns"]
data=[]
for i in range(len(campaigns)):
campaignId = campaigns[i]["campaignId"]
#print(campaignId)
campaignName = campaigns[i]["campaignName"]
#print(campaignName)
sites = campaigns[i]["sites"]
for j in range(len(sites)):
siteId = sites[j]["siteId"]
#print(siteId)
spend = sites[j]["tiers"][0]["spend"]
installCount = sites[j]["tiers"][0]["installCount"]
preloadCount = sites[j]["tiers"][0]["preloadCount"]
conversionRate = sites[j]["tiers"][0]["conversionRate"]
data.append((campaignId,campaignName,siteId,spend,installCount,preloadCount,conversionRate))
data = pd.DataFrame(data, columns = ['campaignID','campaignName','siteID','spend','installCount','preloadCount','conversionRate'])
data.to_csv('API_Data_%s_%s.csv' % (start_date, end_date))
Notes:
- To get the data by day, an advertiser must request a single day.