Downloadable Document

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/>