Reporting API

Use the ONE by AOL: Mobile Reporting API to easily access your data.

It is assumed that users of the API are familiar with Digest-based Authentication. Please see the Additional Resources section below for helpful references.

Access to the API

Access to your ONE by AOL: Mobile Marketplace data via our Reporting API requires Authentication and Authorization using the following values:

  • CompanyID: 32 character GUID used for authentication
  • Company Access Key: your ONE by AOL: Mobile access key used for authorization
  • Secret Key: your ONE by AOL: Mobile password used for authorization

HTTP Response Codes

The following response codes are used. No other responses should be expected.

HTTP Code Definition Conditions When Used
200 General Success a) Successful retrieval of a report, b) Successful authentication test.
204 No Content Call was authenticated and authorized, but report returned an empty body.
401 Unauthorized a) Authentication failure, b) Authorization failure.
503 Service Unavailable The API is disabled.

Design

The Reporting API is designed to provide access to all of your data currently available in the One by AOL: Mobile UI. The API is RESTful, with JSON object return and digest-based authentication. We have provided several examples below of how to retrieve reports from our system. 

Report Specifications

API Request Structure

The general request structure is:
https://reports.nexage.com/access/<CompanyID>/reports/<reportID>?<params> 

  • reportID is the name of the specific report to be retrieved. See below for details.
  • params are request parameters specific to the report. More details below.

General Reporting Rules and Notes

  • All dates in both parameters and report output are in the format yyyy-mm-dd, where month and day are zero-filled. For example, July 4, 2012 would be represented as 2012-07-04.
  • All day, week, month attributes in report output are represented as yyyy-mm-dd hh:mm:ss, where all times are ET. The value will be midnight of the first day in the range (i.e., the month July 2012 would be 2012-07-01 00:00:00).
  • All hour attributes in report output are represented as hh:mm:ss, where all times are ET. The value is the beginning of each hourly interval (e.g., 00:00:00, 01:00:00, 02:00:00, etc.).
  • All countries in report output conform to the ISO-3166-Alpha-3 standard. For example, the United States, Canada, and Great Britain would be represented as USA, CAN, and GBR, respectively.
  • Sites are represented by DCN.
  • Site will be returned with both the names and ONE by AOL: Mobile's unique IDs. These unique IDs must be used to filter on specific Sites.
  • Position values are text only. When filtering on Unknown position, use "???".
  • When used as filters Make, Model, OS, OS Version, and Carrier must be URL encoded due to the potential for spaces.
  • In the JSON report specifications, the data types of each attribute (e.g., integer, float, string) are intended to be descriptive of the data and not prescriptive of a particular data binding.
  • An empty response body is returned if any of the following error conditions is true
    • An invalid start or stop date is passed.
    • The start date is greater than (i.e., future with respect to) the stop date.
    • The period of the report as specified by the start and stop dates exceeds 92 days.
    • An invalid dimension is passed in the parameter.
    • Filter parameter and dim parameter cannot be identical in a given request. For example dim=country and country=USA is not valid and will return no content.

Types of Reports

Three types of reports are available: Revenue, Traffic and Impression Groups.

Revenue Reports

  • reportID = sellerrevenue
  • The start and stop dates place time bounds on the report.
  • Results can be further narrowed by filter parameters as indicated.
  • The report can either be a summary (by omitting the dim parameter) or a detailed breakdown (by the dimension specified in dim).
Parameter Required Description
start Yes Date of the first day of data included in the report.
stop Yes Date of the last day of data included in the report.
dim No The dimension by which details are broken down. Options are: site, country, position, sourceType, day, week, and month.
site No Filters data by the site ID specified.
country No Filters data by the country specified.
position No Filters data by the position specified.
sourceType No Filters data by the sourceType specified. Use sourceType=0 for “mediation” and sourceType=1 for “RTB”.

Request for a Revenue Report Example:
https://reports.nexage.com/access/1234567890/reports/sellerrevenue?start=2014-01-04&stop=2014-02-04&dim=week&site=<DC>&country=<countrycode>

  • If the dim parameter is skipped, only the summary object will be included.
  • If the dim parameter is specified in the request, the details array will be shown in the report where each detail corresponds to a unique value of that dimension (e.g., specific site, specific country, etc.).
  • For day, week, or month dimensions, the dim attribute will be the date of the first day of the applicable interval. The respective attribute values are full time stamps.
  • Within the detail object, the request, served, delivered, clicked, and revenue attributes represent the actual data.
  • The inclusion of other attributes depends on the dimension specified in the request. For example, if dim=site on the request, then the site and siteId attributes will be included to differentiate each detail object.
  • In the case of site dimension, the details include both the name of the entity (i.e., site) and the ID of the entity (i.e., siteId). Note: the IDs are required when using this as a filter.
  • Other dimensions are defined by a single attribute.
  • In the case of the sourceType dimension, mediation and/or RTB will be returned. Specifying dim as sourceType OR including a sourceType filter parameter forces the traffic statistics to be adnet oriented. Therefore data returned will only include outgoing requests from ONE by AOL: Mobile to adnets.
  • In all other cases the Requests data will be site oriented and include Incoming Requests from the site to ONE by AOL: Mobile.
  • Position dimension can only be used when sourceType is specified as a filter parameter.
  • Position can only be used as filter parameter when sourceType is also specified as a filter parameter.

Response to the Request in JSON format.

[
{
"summary": { "requests":"integer", "served":"integer", "delivered":"integer", "clicked":"integer", "revenue": "float" }
{
]
-or-
{
"detail":  [
"site":"string", "siteId":"string", "country": string", "position":"string", “sourceType”: “string”, "day":"string", "week":"string", "month":"string", "requests":"integer", "served":"integer", "delivered":"integer", "clicked":"integer", "revenue":"float" }, ...
]

Traffic Reports

  • reportID = sellertraffic
  • The start and stop dates place time bounds on the report.
  • Results can be further narrowed by filter parameters as indicated.
  • The report can either be a summary (by omitting the dim parameter) or a detailed breakdown (by the dimension specified in dim).
Parameter Required Description
start Yes Date of the first day of data included in the report.
stop Yes Date of the last day of data included in the report.
dim No The dimension by which details are broken down. Options are: "site", "position", "hour", "day", "week", and "month".
site No Filters data by the site ID specified.
position No Filters data by the position specified.

Request for a Traffic Report Example:
https://reports.nexage.com/access/1234567890/reports/sellertraffic?start=2014-01-04&stop=2014-02-04&dim=week&site=<DCN>&position=<positionId>

  • If the dim parameter is skipped, only the summary object will be included.
  • If the dim parameter is specified, the details array will be shown in the report where each detail object corresponds to a unique value of that dimension (e.g., specific site, specific position, etc.).
  • For day, week, or month dimensions, the dim attribute will be the date of the first day of the applicable interval. Their respective attribute values are full time stamps.
  • For the hour dimension, the attribute values are time-only strings (e.g., the 3 PM - 4 PM hour would be 15:00:00).
  • Within the detail object, the requests, served, delivered, and clicked attributes represent the actual data.
  • The inclusion of other attributes depends on the dimension specified in the request. For example, if dim=site on the request, then the site and siteId attributes will be included to differentiate each detail object.
  • In the case of site dimension, the details include both the name of the entity (i.e., site) and the ID of the entity (i.e., siteId). Note: the IDs are required when using this as a filter.
  • Other dimensions are defined by a single attribute.
  • The Requests data will be site oriented and include Incoming Requests from the site to ONE by AOL: Mobile.

Response to the Request in JSON format.

[
{
"summary": { "requests":"integer", "served":"integer", "delivered":"integer", "clicked":"integer"},
}
]
-or-
"detail": [
{ "site":"string", "siteId": "string", "position":"string", "hour":"string", "day":"string", "week": "string", "month":"string", "requests":"integer", "served":"integer", "delivered": "integer","clicked":"integer"
} , ...
]

Impression Groups Report

This report is only available for Sites with Impression Groups enabled.

  • reportID = sellerimpressiongroups
  • The start and stop dates place time bounds on the report.
  • Results can be further narrowed by filter parameters as indicated.
  • The report can either be a summary (by omitting the dim parameter) or a detailed breakdown (by the dimension specified in dim).

Parameter Required Description
start Yes Date of the first day of data included in the report.
stop Date of the last day of data included in the report.
dim No The dimension by which details are broken down. Options are: group, day, week, and month.
site Yes Filters data by the site ID specified.
group No Filters data by the impression group specified.

Request for an Impression Groups Report Example:
https://reports.nexage.com/access/1234567890/reports/sellerimpressiongroups?start=2013-04-01&stop=2013-04-30&dim=week&site=<DCN>&group=<groupname>

  • If the dim parameter is skipped, only the summary object will be included.
  • If the dim parameter is specified, the details array will be shown in the report where each detail object corresponds to a unique value of that dimension (e.g., specific site, impression group, daily breakdown, etc).
  • For day, week, or month dimensions, the dim attribute will be the date of the first day of the applicable interval. Their respective attribute values are full time stamps.
  • Within the detail object, the requests, served, delivered, clicked, and revenue attributes represent the actual data.
  • The inclusion of other attributes depends on the dimension specified in the request. For example, if dim=group on the request, then the group attribute will be included to differentiate each detail object.
  • Other dimensions have only the single attribute to define them.

Response to the Request in JSON format.

[
{
"summary":{ "requests":"integer", "served":"integer", "delivered":"integer", 
"clicked":"integer", "revenue":"float"},
  }
]
  -or-
{
  "Detail":  [
{ "group":"string", "day":"string", "week":"string", "month":"string", "requests":"integer", "served":"integer", "delivered":"integer", "clicked":"integer", "revenue":"float" }, ...
]

Code Examples

The following example snipits of code can be dropped into your reporting project.

Via Command Line using cUrl

curl --digest -u user:pass  "report_url_here"

PHP

<?php
$url = "https://reports.nexage.com/access/<CompanyID>/reports/sellerrevenue?start=2016-08-26&stop=2016-08-27&dim=day";
$username = "companyId";
$password = "secret";
$options = array(      CURLOPT_URL => $url,      CURLOPT_SSL_VERIFYPEER => false, // for https      CURLOPT_USERPWD => $username . ":" . $password,      CURLOPT_HTTPAUTH => CURLAUTH_DIGEST,
);
$ch = curl_init(); curl_setopt_array($ch, $options); curl_exec($ch); curl_close($ch);
?>

Python

# Uses http://docs.python-requests.org/en/master/
import json import requests
def reporting_api(companyId, secret, reportType, start, stop, params):     # Assumes all string arguments except params, a dict i.e. {'dim': 'day'}     baseUrl = "https://reports.nexage.com/access/" + companyId + "/reports/" + reportType      digestAuth = HTTPDigestAuth(companyId, secret)      params['start'] = start
      params['stop'] = stop      data = requests.get(baseUrl, auth=digestAuth, params=params)      if data.status_code != 200:      print ("SERVER ERROR (" + str(data.status_code) + "): " + data.text)      return # On success, return a dict with all the data.      return json.loads(data.text)

Node.js

// Uses https://github.com/request/request
var companyId = '<CompanyID>'; var companySecret = '<CompanySecret>'; var reportParams = '?<params>'; //i.e. start=...&stop=...&dim=... var reportType = '<reportID>'; // sellerrevenue, etc. var request = require('request');
var reportUrl = 'https://reports.nexage.com/access/' + companyId + '/reports/' + reportType + reportParams;
request.get(reportUrl, function (error, response, body) { if (!error && response.statusCode == 200) { // Use data JSON here... console.log( body ); } }).auth(companyId, companySecret, false); 

Ruby

def getSecuredReport (reportURL)
     uri = URI.parse "#{reportURL}"
     h = Net::HTTP.new uri.host, uri.port      h.use_ssl = true      h.verify_mode = OpenSSL::SSL::VERIFY_NONE 
# get the authorization header if we don't already have it if !$authorization_header  digest_auth = Net::HTTP::DigestAuth.new
          uri.user = 'companyId'           uri.password = 'secret'
          req = Net::HTTP::Get.new uri.request_uri
         # this will be a 401 response with the www-authenticate header          res = h.request req
$authorization_header = digest_auth.auth_header uri, res['www-authenticate'], 'GET'end # create a request and add the authorization header req = Net::HTTP::Get.new uri.request_uri req.add_field 'Authorization', $authorization_header
res = h.request req
return res.body

Additional Resources and Technical References

Have more questions? Submit a request