Digital Turbine's Catalog API provides a feed of all the information currently available on the Via Manual Campaigns page
This will allow publishers to automate:
This is a restful API that must be called programmatically, returning JSON.
The Catalog API uses "Basic Authentication" over SSL to authenticate and authorize users, using your Via login credentials in the Authorization header.
<?php
$url = "https://via.appia.com/ext/api/campaigns/manual?siteId=####";
$creds = "example@appia.com:appia123";
$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);
?>
If you are requesting all campaigns, please request them no more than hourly, ideally at an arbitrary time (not exactly at the top of every hour)
If you are requesting information for specific campaign id's, please request them no more than once every 10 minutes.
https://via.appia.com/ext/api/campaigns/manual?siteId=####
Parameter | Required | Description |
---|---|---|
Accept Header | Yes | Defaults to JSON and the most recent API version. Allowed values:
|
Authorization | Yes | See Authentication section above |
Parameter | Required | Description |
---|---|---|
siteId | Yes | Defaults to all site IDs. Allowed value - any valid Site ID ex. https://via.appia.com/ext/api/campaigns/manual/?siteId=#### |
campaignId | No | Defaults to all campaigns. Allowed value - any valid Campaign ID ex. https://via.appia.com/ext/api/campaigns/manual/99999?siteId=#### |
expand=creatives | No | Returns the creative images for each campaign |
Listings are paginated. Request the next page by appending the "Next" url parameters that are returned in the response
Example
If the initial request url is: https://via.appia.com/ext/api/campaigns/manual?siteId=#### And the following is retuned at the end of the response "next": "campaigns/manual?siteId=####&offset=25&limit=25" The url for the next page of results should be https://via.appia.com/ext/api/campaigns/manual?siteId=####&offset=25&limit=25 |
Field | Description |
---|---|
campaignId | The unique numeric id for the campaign |
url | The a unique url for this campaign, to access this API for only this campaign |
name | Digital Turbine's name for the campaign |
description | Digital Turbine's description for the campaign |
status | Current state of the campaign:
|
startDate | Date values will use ISO-8601 compliant short notation, either YYYY-MM-DD for dates or YYYY-MM-DD“T”HH:MM:SS for date time. Example
|
endDate | Date values will use ISO-8601 compliant short notation, either YYYY-MM-DD for dates or YYYY-MM-DD“T”HH:MM:SS for date time. Example
|
note | Important notes about the campaign, usually regarding restrictions about where the campaign can run |
impressionUrl | The url to use to report impressions for this campaign [YOUR_SITE_ID] - substitute your site_id that is running the campaign ex. siteId=9999 Optional, but recommended: [USER_ANDROID_ID] - substitute the Android ID of the user viewing the campaign, if it is known ex. androidId=B77H823942an1234 [USER_ADVERTISING_ID] - substitute the Google Advertising Id of the user viewing the campaign, if it is known ex. aaid=38400000-8cf0-11bd-b23e-10b96e40000d [USER_IDFA] - substitute the IDFA of the user viewing the campaign, if it is known ex. idfa=236A005B-700F-4889-B9CE-999EAB2B605D |
clickUrl | The url to use when a user clicks on an ad for this campaign [YOUR_SITE_ID] - substitute your site_id that is running the campaign. ex. siteId=9999 [TIME_STAMP] - a unique timestamp for this click, used to break any caching. ex.ts=1395353746407 Optional, but recommended: [USER_ANDROID_ID] - substitute the Android ID of the user viewing the campaign, if it is known ex. androidId=B77H823942an1234 [USER_ADVERTISING_ID] - substitute the Google Advertising Id of the user viewing the campaign, if it is known ex. aaid=38400000-8cf0-11bd-b23e-10b96e40000d [USER_IDFA] - substitute the IDFA of the user viewing the campaign, if it is known ex. idfa=236A005B-700F-4889-B9CE-999EAB2B605D |
unlimitedTotalBudget | If = false, then the campaign has a max budget set |
remainingTotalBudget | If unlimitedTotalBudget = false, this is the amount of the budget currently remaining |
remainingDailyCap | The amount of the dailyCap that remaining for today. Can be null if there is no daily limit. |
dailyCap | The maximum daily budget allowed for this campaign. Can be null if there is no daily limit. Campaigns are removed from API results when daily caps are met. |
dailyCapType | The value returned will be either 'Network' for a daily cap that is shared across Digital Turbine's network, or 'Site' for a daily cap that is allocated to the siteId passed in the request. |
bilingType | Value returned will be either CPI or CPC. |
targetedLocations | Array of targeted countries, cities, or demographic market areas (DMAs) |
excludedLocations | Array of excluded countries, cities, or demographic market areas (DMAs) |
defaultPayout | The payout for the campaign, unless otherwise set with a sitePayout below. This is the net payout. However, if "hasCustomRevShareAgreement" = true, the defaultPayout value is Gross for those publishers. |
maxPayout (deprecated) | Deprecated as of 6/10/2015 and will be removed from the API at a later date. Use defaultPayout |
sitePayouts (deprecated) | Deprecated as of 6/10/2015 and will be removed from the API at a later date. Use defaultPayout |
countries (deprecated) | Deprecated as of 2/29/2016 and will be removed from the API at a later date. Replaced by targetedLocations & excludedLocations. |
application | "identifier" - the unique identifier for the application being advertised in this campaign. Either the packagename in GooglePlay or the bundleId for the Apple AppStore. ex. com.appia.sampleapp |
category | The app store category for the app being advertised in this campaign |
platform | Android or iOS |
maxOsPlatform | The most recent OS version allowed to see this ad |
minOsPlatform | The oldest recent OS version allowed to see this ad |
appStoreUrl | The url to the appstore page for the app being advertised |
excludedDevices | Specific device models that are not allowed to see ads for this campaign |
excludedSites | A list of subsites that are not allowed to run the campaign (under the name field) |
blockedSubSites | Array of excluded publisher sub sites. |
creatives | An array of creative images for a campaign. Populated only when request parameter "expand=creatives" is used (this field will be null if the request parameter is not present). For each creative image, the following information is returned:
|
{ "items": [ { "campaignId": 9998, "url": "https://via.appia.com/ext/api/campaigns/manual/9998", "name": "Sample Campaign 1", "description": "This is a campaign sample for the API documentation", "status": "Active", "startDate": "2012-06-20T14:00", "endDate": null, "note": "No Individual Homescreen Ad Units", "impressionUrl": "http://ads.appia.com/v2/impressionAd.jsp?campaignId=9998&siteId=[YOUR_SITE_ID]&androidId=[USER_ANDROID_ID]&macAddress=[USER_MAC_ADD]&udid=[USER_UDID]", "clickUrl": "http://ads.appia.com/v2/clickAd.jsp?campaignId=9998&siteId=[YOUR_SITE_ID]&androidId=[USER_ANDROID_ID]&macAddress=[USER_MAC_ADD]&udid=[USER_UDID]&ts=[TIME_STAMP]", "unlimitedTotalBudget": false, "remainingTotalBudget": 5000.1, "remainingDailyCap": 700.8, "dailyCap": 800, "dailyCapType" : "Network", "billingType" : "CPI", "targetedLocations"[ { "id": 6252001 "countryIsoCode": "US" "countryName": "United States" "subdivision1Name": null "subdivision2Name": null "cityName": null "dmaCode": null "dmaName": null "type": "country" } ], "excludedLocations"[ { "id": null "countryIsoCode": null "countryName": null "subdivision1Name": null "subdivision2Name": null "cityName": null "dmaCode": 505 "dmaName": "Detroit, MI" "type": "dma" } ], "defaultPayout": 2, "maxPayout": 2, "sitePayouts": [], "countries": [ { "name": "United States", "code": "US" } ], "application": { "url": null, "identifier": "com.appia.sample1" }, "category": { "name": "Lifestyle", "description": "Lifestyle" }, "platform": "Android", "maxOsPlatform": null, "minOsPlatform": "Android 2.3", "appStoreUrl": "http://play.google.com/store/apps/details?id=com.appia.sample1", "excludedDevices": [ "Samsung Captivate SGH-i897", "Alcatel Venture", "HTC Knight PG06100", "ZTE N860", "Samsung Precedent SCH-M828C", "Samsung Galaxy Suit SGH-T499", "Pantech P8000", "Samsung Replenish M580", "T-Mobile myTouch 4G Slide", "LG P509", "LG P999", "Huawei M865C", "Huawei Ascend M860", "Samsung Galaxy Tab SCH-I800", "SE Xperia PLAY R800x", "LG Thrill 4G P925", "Samsung Repp SCH-R680", "LG Thrill 4G P920H", "Motorola Electrify" ], "excludedSites": [], "blockedSubSites": [ { "id": 1, "siteId": 2710, "name": "subsitetestName" }, { "id": 2, "siteId": 2710, "name": "subsitetestName2" } ], "hasCustomRevShareAgreement": true }, { "campaignId": 9999, "url": "https://via.appia.com/ext/api/campaigns/manual/9999", "name": "Sample Campaign 2", "description": "This is a campaign sample for the API documentation", "status": "Active", "startDate": "2012-07-03T13:00", "endDate": null, "note": "No Individual Homescreen Ad Units", "impressionUrl": "http://ads.appia.com/v2/impressionAd.jsp?campaignId=9999&siteId=[YOUR_SITE_ID]&androidId=[USER_ANDROID_ID]&macAddress=[USER_MAC_ADD]&udid=[USER_UDID]", "clickUrl": "http://ads.appia.com/v2/clickAd.jsp?campaignId=9999&siteId=[YOUR_SITE_ID]&androidId=[USER_ANDROID_ID]&macAddress=[USER_MAC_ADD]&udid=[USER_UDID]&ts=[TIME_STAMP]", "unlimitedTotalBudget": false, "remainingTotalBudget": 3605.6, "remainingDailyCap": null, "dailyCap": null, "defaultPayout": 0.8, "maxPayout": 0.8, "sitePayouts": [ { "id": 2222, "url": null, "name": "Sample Site 2222", "payout": 0.95, "isNetPayout": null }, { "id": 1111, "url": null, "name": "Sample Site 1111", "payout": 2.5, "isNetPayout": null } ], "countries": [ { "name": "United States", "code": "US" } ], "application": { "url": null, "identifier": "com.appia.sample2" }, "category": { "name": "Health & Fitness", "description": "Health & Fitness" }, "platform": "Android", "maxOsPlatform": null, "minOsPlatform": "Android 2.0", "appStoreUrl": "http://play.google.com/store/apps/details?id=com.appia.sample2", "excludedDevices": [], "excludedSites": [ { "id": 1234, "url": null, "name": "Sample Site 1", "payout": null, "isNetPayout": null }, { "id": 1235, "url": null, "name": "Sample Site 2", "payout": null, "isNetPayout": null } ], "hasCustomRevShareAgreement": true } ], "offset": 0, "limit": 2, "next": "campaigns/manual?offset=25&limit=25", "previous": "", "first": "campaigns/manual?offset=0&limit=25", "last": "campaigns/manual?offset=500&limit=25", "totalRecords": 504, "totalPages": 21 } |
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:
Sample Error Response
{ "errorDetails": { "errorCode": 400, "sourceErrorEntity": "X is not a valid value for status", "userMessage": "There was an error with the parameters passed. Please verify and try again.", "developerMessage": "Cannot parse query; your argument X is not a valid value for status is invalid. ", "moreInfoUrl": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1" } } |
<?php $url = "https://via.appia.com/ext/api/campaigns/manual?siteId=1111"; $creds = "email:password"; $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); ?> |