Publisher Reports API v2
Downloadable Document
Table of Contents
Introduction
Digital Turbine’s Reports API provides a programmatic method for our publishing partners to view campaign performance data.
- The API is accessed through an HTTP GET request and returns the data in XML
- The following data is included in the report and broken down per country per campaign:
- Number of Impressions
- Number of Clicks / Preloads
- Number of Installs
- Total Net Revenue (numbers will be Gross if Partner has no standard revenue share agreement)
- Click through Ratio
- Cost per Install
- Access to the Digital Turbine Reports API is restricted and a login will be provided upon request
Requesting Reports
Digital Turbine Report API URL
https://via.appia.com/api/report/country
*Please note, Appia endpoints will continue to work (i.e. ..appia.com/v2/..)
Request Parameters
Field | Required | Description |
id | Yes | Authentication attribute provided by Digital Turbine |
password | Yes | Authentication attribute provided by Digital Turbine |
| siteId | Yes | Value provided by Digital Turbine to identify the publisher |
| startDate | No | Required if End Date is specified |
| endDate | No | Required if Start Date is specified. Must be after Start Date. Maximum range of 31 days. Cannot include today. |
| campaignId | No | Campaign id to filter report by |
| includeRevShare | No | Include revenue share flag. Default value: true |
Sample Request
Format
https://via.appia.com/api/report/country?id=<user id>&password=<password>&siteId=<siteId>&startDate=<yyyy-mm-dd>&endDate=<yyyy-mm-dd>
Examples:
To request a report for yesterday’s performance results - no date parameters are needed
- https://via.appia.com/api/report/country?id=1&password=test&siteId=123
To request a report for a month's results - using startDate and endDate
- https://via.appia.com/api/report/country?id=1&password=test&siteId=123&startDate=2012-12-01&endDate=2012-12-31
Note: the API must be called for each site ID individually. A developer could use a loop to iterate through multiple site IDs and aggregate the XML responses.
Reading Reports
Response Parameters
Field | Description | Type |
date | yyyy-mm-dd | Date |
countryCode | two-letter country code | String |
campaignId | Digital Turbine's numerical identifier for the campaign | Integer |
campaignName | The headline text for the campaign | String |
campaignDescription | Digital Turbine's name for the campaign | String |
| platform | The platform targeted for the campaign - Android or iOS | String |
| impressions | Number of impressions for this campaign, within the specified country on the specified date | Integer |
| clicks / Preloads | Number of clicks for this campaign, within the specified country on the specified date | Integer |
| installs | Number of app installs from this campaign, within the specified country on the specified date | Integer |
| Preloads | Number of Preloads for this campaign, within the specified country on the specified date | Integer |
| revenue | Total gross revenue for this campaign, within the specified country on the specified date | Integer |
| clickThroughRatio | Number of clicks divided by number of impressions | Float |
| averageBidRate | Total revenue divided by number of installs | Float |
Sample Response
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<report>
<reportDate> <date>2013-01-16</date>
<countries>
<country>
<countryCode>CA</countryCode>
<campaigns>
<campaign>
<campaignId>247</campaignId>
<campaignName>Awesome Action Game</campaignName>
<campaignDescription>Action Game -Android CPI-US/UK/CA/AU</campaignDescription>
<platform>Android</platform>
<impressions>10000</impressions>
<clicks>0</clicks>
<installs>100</installs>
<preloads>20</preloads>
<revenue>200.00</revenue>
<clickThroughRatio>00.20</clickThroughRatio>
<averageBidRate>2.00</averageBidRate>
</campaign>
<campaign>
<campaignId>325</campaignId>
<campaignName>Best Travel App</campaignName>
<campaignDescription>TravelApp-Android CPI-US/CA</campaignDescription>
<platform>Android</platform>
<impressions>20000</impressions>
<clicks>0</clicks>
<installs>150</installs>
<preloads>200</preloads>
<revenue>150.00</revenue>
<clickThroughRatio>0.25</clickThroughRatio>
<averageBidRate>1.50</averageBidRate>
</campaign>
</campaigns>
</country>
<country>
<countryCode>US</countryCode>
<campaigns>
<campaign>
<campaignId>247</campaignId>
<campaignName>Awesome Action Game</campaignName>
<campaignDescription>Action Game -Android CPI-US/UK/CA/AU</campaignDescription>
<platform>Android</platform>
<impressions>10000</impressions>
<clicks>0</clicks>
<installs>100</installs>
<preloads>30</preloads>
<revenue>200.00</revenue>
<clickThroughRatio>00.20</clickThroughRatio>
<averageBidRate>2.00</averageBidRate>
</campaign>
<campaign>
<campaignId>399</campaignId>
<campaignName>Meet People App</campaignName>
<campaignDescription>MeetPeople-Android CPI-US/UK</campaignDescription>
<platform>Android</platform>
<impressions>20000</impressions>
<clicks>0</clicks>
<installs>150</installs>
<preloads>250</preloads>
<revenue>150.00</revenue>
<clickThroughRatio>0.25</clickThroughRatio>
<averageBidRate>1.50</averageBidRate>
</campaign>
</campaigns>
</country>
</countries>
</reportDate>
<reportDate> <date>2013-01-17</date>
<countries>
<country>
<countryCode>CA</countryCode>
<campaigns>
<campaign>
<campaignId>247</campaignId>
<campaignName>Awesome Action Game</campaignName>
<campaignDescription>Action Game -Android CPI-US/UK/CA/AU</campaignDescription>
<platform>Android</platform>
<impressions>10000</impressions>
<clicks>0</clicks>
<installs>100</installs>
<preloads>20</preloads>
<revenue>200.00</revenue>
<clickThroughRatio>00.20</clickThroughRatio>
<averageBidRate>2.00</averageBidRate>
</campaign>
<campaign>
<campaignId>325</campaignId>
<campaignName>Best Travel App</campaignName>
<campaignDescription>TravelApp-Android CPI-US/CA</campaignDescription>
<platform>Android</platform>
<impressions>20000</impressions>
<clicks>0</clicks>
<installs>150</installs>
<preloads>30</preloads>
<revenue>150.00</revenue>
<clickThroughRatio>0.25</clickThroughRatio>
<averageBidRate>1.50</averageBidRate>
</campaign>
</campaigns>
</country>
<country>
<countryCode>US</countryCode>
<campaigns>
<campaign>
<campaignId>247</campaignId>
<campaignName>Awesome Action Game</campaignName>
<campaignDescription>Action Game -Android CPI-US/UK/CA/AU</campaignDescription>
<platform>Android</platform>
<impressions>10000</impressions>
<clicks>0</clicks>
<installs>100</installs>
<preloads>220</preloads>
<revenue>200.00</revenue>
<clickThroughRatio>00.20</clickThroughRatio>
<averageBidRate>2.00</averageBidRate>
</campaign>
<campaign>
<campaignId>399</campaignId>
<campaignName>Meet People App</campaignName>
<campaignDescription>MeetPeople-Android CPI-US/UK</campaignDescription>
<platform>Android</platform>
<impressions>20000</impressions>
<clicks>0</clicks>
<installs>150</installs>
<preloads>250</preloads>
<revenue>150.00</revenue>
<clickThroughRatio>0.25</clickThroughRatio>
<averageBidRate>1.50</averageBidRate>
</campaign>
</campaigns>
</country>
</countries>
</reportDate>
</report>
Error Response
If one of the request parameters is incorrect, an error message will be displayed.
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<report>
<error>Only one month of data can be requested at a time. Please specify a date range between 1-31 days.</error>
</report>
No Data Response
If there is no data for the requested site and date range, an empty report element will be returned.
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<report/>