iAd Publisher API Guide
Describes how app publishers can access data about the iAd performance of their individual apps.
Overview
If you are an iOS app publisher who uses iAd to generate advertising revenue, you can use the iAd Publisher API to efficently track the performance and revenue generated from the advertising in your apps. The iAd Publisher API provides programmatic access to your iAd account data, allowing you to pull reporting data from iAd for integration into your own systems for analysis. The API also allows you to report on revenue by device class and revenue by ad format, which are not available through the web portal.
The iAd Publisher API is available to all iAd publishers with admin access who have enabled iAd integration in their apps.
The iAd Publisher API uses the same authentication system as the iAd Workbench API. To request and download the API keys, tokens, and certificates required to access iAd, you will need an iAd Workbench account. If you do not not already have an iAd Workbench account:
Go to iadworkbench.apple.com and log in with your Apple ID.
Provide your contact information and create your Workbench account.
To request and download the API keys, tokens, and certificates required to access the iAd server:
Log in to iAd Workbench.
Click on the dropdown arrow next to your account name near the top right.
Choose API from the popup menu.
Enter the displayed security code.
Press the Download New Keys button.
Save the Zip file in an approprate location.
Note: If anyone in your organization has previously downloaded keys for either iAd Publisher API or iAd Workbench API (which can be used to create and monitor advertising campaigns) and you generate a new set of keys on the website, the previous keys will be voided.
Implement your utilization of the iAd Publisher API by following the details proved in “ API Concepts ” and following sections of this document and use this end point URL:
https://iadapi.apple.com/publisher/v1
Note: Communication with the web service must be over https.
This document describes the v1 URL of iAd Publisher. For more details, see “ Versioning of the API ” below.
API Basics
The iAd Publisher API 1.0 supports JSON-RPC 2.0 payloads over HTTP POST. This allows you to programmatically access performance data from your iAd account.
A request is a JSON-RPC 2.0 payload in an HTTP POST request with the Content-Type header of “ application/json ”.
A response is a JSON-RPC 2.0 payload in an HTTP response request with the Content-Type header of “ application/json ” and is encoded as UTF-8.
The request payload contains the method name and the method parameters, which in this API is a single Dictionary object.
The response payload contains the result, which in this API must be a single Dictionary object.
Any Array (also called a Collection or List) should contain uniform types. Within the JSON-RPC Dictionary objects, all keys must be String objects and the following primitives and objects may be represented (in nested forms): String, Number, Array, Dictionary, Boolean, NULL. For example, an Array may contain String objects, Number objects, other Array objects, or other Dictionary objects, which in turn may have other primitive types within them. Dictionary objects may have any primitive type for a given value, but the keys must be strings.
Versioning of the API
iAd Publisher API v1 is read-only. It allows you to generate reports on the performance and revenue generated by your iAd-enabled apps. The API version is specified in the URL, e.g., https://iadapi.apple.com/publisher/v1 is the URL for the v1 version.
If new features are added to the iAd Publisher API, as long as they are backward compatible, the URL will remain the same. If new features are ever added that are not backward compatible, a new URL will be introduced that supports those features.
Invoking the API
There is no additional charge to use the Publisher API. However, there is a limit of 10,000 API calls per day (Midnight to Midnight, UTC), total for all iAd APIs, including Workbench API and Publisher Reporting API. If you expect to make more API calls than this, consult your iAd account representative.
Because the communication protocol for the iAd Publisher API is JSON RPC 2.0, any language can be used to develop client programs.
Request objects must follow the JSON-RPC 2.0 specification and must include the following fields:
jsonrpc: A string specifying the version of JSON-RPC protocol. The string value must be exactly “2.0”.
method: A string containing the name of the method to be invoked.
id: A unique identifier established by your client program. It must be a string that ideally is unique for each call. The server will reply back using the same ID. If the input request id is unique, the output response will be uniquely assoctiated with the call that generated it. This field must be specified.
params: An array of name-value pairs of named parameters and their corresponding values.
Response objects follow the JSON-RPC 2.0 specification and include the following fields:
jsonrpc: A string specifying the version of JSON-RPC protocol, which is exactly “2.0”.
id: This will be provided in every response and is the same as the ID sent in the request object.
result: In almost all cases, the result includes a Success attribute, a boolean value of true or false indicating success or failure of the API call. If Success is true , then result includes the response to the method request. If Success is false , then result includes an error message and an error code.
Note: The InitSession method does not return a Success attribute.
API Concepts
Session Management
The InitSession method returns a Session ID to use with other API method calls.
Obtaining Report Metrics
The GetAppMetrics method provides iAd performance metrics for your iOS apps.
Session Management
InitSession
The InitSession method authenticates your account, establishes a secure connection, and provides the session ID required to make other API calls. Call InitSession before doing anything else with the API.
The InitSession method requires your access token and returns a SessionID string. Use this SessionID string to authenticate all other API operations. A SessionID expires after one hour of inactivity.
Input
Parameter
Type
Required/Optional
Comments
accessToken
String
Required
accessToken is one of the keys given to a user along with client side certificate to initiate session.
Listing 1-1 InitSession Sample Input
{
"method":"InitSession",
"id": "RequestNo-001",
"params":{
"accessToken":"1234567890"
},
"jsonrpc":"2.0"
}
Output
Note: The InitSession function is the only function that does not return a Success value.
Parameter
Type
Comments
SessionId
String
SessionId to be used for all other API operations.
Listing 1-2 InitSession Sample Output
{ "id": "RequestNo-001",
"result": {
"SessionId": "44e5b59211ae0da9c9739b0866936ca94301d444"
},
"jsonrpc": "2.0"
}
Obtaining Report Metrics
GetAppMetrics
Input
Parameter
Type
Required/Optional
Comments
SessionId
String (alphanumeric)
Required
SessionId obtained from InitSession call.
AppIds
List of Strings (numeric)
Required
Each AppId number is an iTunes Adam ID, the numerical portion of the URL of the app’s iTunes page.
You may not request information on apps that do not correspond to the accessToken you provided to InitSession .
StartTime
Date string
Required
The starting date of the period you want data for, in YYYY-MM-DD format, based on UTC time. The earliest date supported is 2015-03-05, March 5, 2015.
EndTime
Date string
Required
The ending date of the period you want data for, in YYYY-MM-DD format. A maximum of 7 days is allowed in a single request.
Listing 1-3 GetAppMetrics Sample Input
{
"method": "GetAppMetrics",
"id": "1001",
"params": {
"SessionId": "3ee7bb3fe686cae2415b99b63399bd20b4269bd0",
"AppIds": [
"456789123",
"345678912"
],
"StartTime": "2015-04-05"
"EndTime": "2015-04-05",
},
"jsonrpc": "2.0"
}
Output
Note: Output is reported per ad type, per device type, and per day, individually. You may receive multiple sets of data for a single app. It is up to you to aggregate the results.
Parameter
Type
Comments
Metrics
Collection
Products element.
Metrics.AppId
String (numeric)
The ID of the app for which you requested information.
Metrics.AppName
String
The registered name of the app for which you requested information.
Metrics.Country
String
The country for which information is reported.
Metrics.CreativeType
String
The ad type for which information is reported. If your app supports more than one type of ad, you will get separate Metrics results for each type.
Metrics.DeviceClass
String
The device class for which information is reported. If your app supports more than one class of device, you will get separate Metrics results for each class.
Metrics.Date
Date and time string
The date for which information is reported, based on UTC time.
If you requested information about more than one day, you will get separate Metrics results for each day in the range requested.
Metrics.Taps
String (numeric)
Number of times a user tapped on an ad in your app.
Metrics.eCPM
String (numeric)
Effective cost per thousand impressions. This is the total revenue you have earned for every thousand times an ad is shown in your app.
Metrics.Impressions
String (numeric)
Total number of times users were shown ads in your app.
Metrics.TTR
String (numeric)
Tap-through rate, the ratio of taps to impressions (e.g., if 100 users are exposed to an ad banner, and the banner is tapped five times, the TTR is 5% or 0.05.).
Metrics.Revenue
String (numeric)
Ad revenue generated by this app.
Metrics.GlobalRequests
String (numeric)
The number of ad requests iAd has received from your app globally.
Metrics.iAdCountryRequests
String (numeric)
The number of ad requests iAd has received from your app in countries where iAd is supported.
Metrics.iAdFillRate
String (numeric)
Percentage of successful impressions served compared to ads requested, returned as a value between 0.00 and 100.00.
Success
Boolean
true or false depending on whether the call succeeded or not.
Listing 1-4 GetAppMetrics Sample Output
{
"id": "1001",
"result": {
"Metrics": [
{
"AppId": "900000002",
"AppName": "AnonApp",
"Country": "US",
"CreativeType": "Banner",
"DeviceClass": "iPhone",
"Date": "2015-03-05 00:00:00.0",
"Taps": "0",
"eCPM": "0.00",
"Impressions": "0",
"TTR": "0.00",
"Revenue": "0.00",
"GlobalRequests": "99999",
"iAdCountryRequests": "99999",
"iAdFillRate": "0.00"
},
{
"AppId": "900000002",
"AppName": "AnonApp",
"Country": "US",
"CreativeType": "Banner",
"DeviceClass": "iPad",
"Date": "2015-03-05 00:00:00.0",
"Taps": "0",
"eCPM": "0.00",
"Impressions": "0",
"TTR": "0.00",
"Revenue": "0.00",
"GlobalRequests": "88888",
"iAdCountryRequests": "88888",
"iAdFillRate": "0.00"
},
{
"AppId": "900000001",
"AppName": "LightRight",
"Country": "US",
"CreativeType": "Banner",
"DeviceClass": "iPad",
"Date": "2015-03-05 00:00:00.0",
"Taps": "0",
"eCPM": "0.00",
"Impressions": "0",
"TTR": "0.00",
"Revenue": "0.00",
"GlobalRequests": "77777",
"iAdCountryRequests": "77777",
"iAdFillRate": "0.00"
}
],
"Success": true
},
"jsonrpc": "2.0"
}
Next
Copyright © 2015 Apple Inc. All Rights Reserved. Terms of Use | Privacy Policy | Updated: 2015-11-12