Publisher Report API with Sub-Sites

Owned by Ryan Hundemer (Deactivated)
Last updated: May 17, 2016
13 min read

Table of Contents 

Authentication

The Reporting API uses "Basic Authentication" over SSL to authenticate and authorize users, using your Via login credentials in the Authorization header.

More information about authentication:

http://www.w3.org/Protocols/HTTP/1.0/spec.html#BasicAA

Example:

<?php
$url = "https://via.appia.com/ext/api/reports/subsites?siteId=XXXX";
$creds = "example@digitalturbine.com:digitalturbine123";
$c = curl_init();
curl_setopt($c, CURLOPT_URL, $url);
curl_setopt($c, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($c, CURLOPT_HTTPHEADER,array('Authorization: Basic ' . base64_encode($creds)));
$result = curl_exec($c);
curl_close($c);
?>

Frequency

Digital Turbine's reporting is rolled up hourly, so it's recommended that queries be scheduled at most once per hour, at a staggered time so all Publisher requests are not at the top of the hour, thereby reducing response times.

Request

URL

https://via.appia.com/ext/api/reports/subsites

*Please note, Appia endpoints will continue to work (i.e. ..via.appia..)

Headers

ParameterRequiredDescription
Accept HeaderNo

XML and JSON are supported

AuthorizationYesSee Authentication section above

Request Parameters

ParameterRequiredDescription
siteIdNo

ex. https://via.appia.com/ext/api/reports/subsites?siteId=9999

 If not passed in, API will return results for all of your sites

subSiteNo

ex. https://via.appia.com/ext/api/reports/subsites?siteId=9999&subSite=test

The subSite value that was passed in on the ad request or click

Requires SiteId

If not passed in, API will return results for all of your sub-sites

startDateNo

ex. https://via.appia.com/ext/api/reports/subsites?startDate=2014-01-01

Requires End Date

yyyy-mm-dd

endDateNo

ex. https://via.appia.com/ext/api/reports/subsites?startDate=2014-01-01&endDate=2014-01-31

Requires Start Date

yyyy-mm-dd

Max 31 day range in 1 API request

Response

Data Returned

FieldDescription
date

Date values will use ISO-8601 compliant short notation, YYYY-MM-DD

siteIdThe a unique url for this campaign, to access this API for only this campaign
campaignId

The unique numeric id for the campaign

subSiteThe subSite value that was passed in on the ad request or click
impressionCount

 

clickCount

 

installCount

 

revenue 

 

 

Sample Response

{
    "data": [
        {
            "date": "2014-04-08",
            "sites": [
                {
                    "siteId": 9998,
                    "impressionCount": 250,
                    "clickCount": 25,
                    "installCount": 25,
                    "revenue": 29,
                    "campaigns": [
                        {
                            "campaignId": 5555,
                            "impressionCount": 150,
                            "clickCount": 18,
                            "installCount": 18,
                            "revenue": 5.76,
                            "subSites": [
                                {
                                    "subSite": "Test",
                                    "impressionCount": 100,
                                    "clickCount": 7,
                                    "installCount": 5,
                                    "revenue": 1.6
                                },
                                {
                                    "subSite": "123Example",
                                    "impressionCount": 30,
                                    "clickCount": 7,
                                    "installCount": 6,
                                    "revenue": 1.92
                                }
                            ]
                        },
                        {
                            "campaignId": 9999,
                            "impressionCount": 100,
                            "clickCount": 7,
                            "installCount": 7,
                            "revenue": 23.24,
                            "subSites": [
                                {
                                    "subSite": "123Example",
                                    "impressionCount": 90,
                                    "clickCount": 6,
                                    "installCount": 6,
                                    "revenue": 19.92
                                }
                            ]
                        }
                    ]
                }
            ]
        },
        {
           "date": "2014-04-09",
            "sites": [
                {
                    "siteId": 9998,
                    "impressionCount": 250,
                    "clickCount": 25,
                    "installCount": 25,
                    "revenue": 29,
                    "campaigns": [
                        {
                            "campaignId": 5555,
                            "impressionCount": 150,
                            "clickCount": 18,
                            "installCount": 18,
                            "revenue": 5.76,
                            "subSites": [
                                {
                                    "subSite": "Test",
                                    "impressionCount": 100,
                                    "clickCount": 7,
                                    "installCount": 5,
                                    "revenue": 1.6
                                },
                                {
                                    "subSite": "123Example",
                                    "impressionCount": 30,
                                    "clickCount": 7,
                                    "installCount": 6,
                                    "revenue": 1.92
                                }
                            ]
                        },
                        {
                            "campaignId": 9999,
                            "impressionCount": 100,
                            "clickCount": 7,
                            "installCount": 7,
                            "revenue": 23.24,
                            "subSites": [
                                {
                                    "subSite": "123Example",
                                    "impressionCount": 90,
                                    "clickCount": 6,
                                    "installCount": 6,
                                    "revenue": 19.92
                                }
                            ]
                        }
                    ]
                }
            ]
        }
    ]
} 


Error Handling

The API uses a hybrid approach to error handling, relying on custom 5xx HTTP Status Codes for a first error category, then providing additional detail in the response body using the following fields:

  • Related entity property: Additional detail on the property of the entity which caused the error. (Example: If the error was caused by an invalid email address, this field would be “emailAddress”)
  • User Level Message
  • Developer Level Message
  • More Info URL: Points to a website where the developer can find out more information to fix the issue.

 

Sample Error Response

 {
    "errorDetails": {
        "errorCode": 400,
        "sourceErrorEntity": "Request",
        "userMessage": "There was an error with the parameters passed. Please verify and try again.",
        "developerMessage": "Only 31 days of data can be requested at a time. Please specify a date range between 1-31 days.",
        "moreInfoUrl": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1"
    }
}