Knowledge base

Monetization Stats API

Unity Ads provides an API for Publishers and Advertisers to retrieve monetization data directly in CSV format.

The monetization API will fetch the same statistics that are available in the Unity Ads Admin Panel. Publishers can use the API to programmatically pull data for their own uses.

Overview

The statistics API works in two stages:

  1. The user performs a GET request to an authentication server. After a successful authentication, the server responds with a 302 HTTP redirect message, which contains the final URL to the statistics server.

  2. When the user performs a GET request to the signed URL, the server will respond with the requested data in CSV format in the body of the message.

Authentication

The API uses the API key from the Unity Ads Admin Panel. The API key is located in the [Account Settings][2] page.

The API key must be included in the authentication GET request, as the apikey parameter.

After a successful authentication, the server will respond with a 302 HTTP-redirect message with the data URL, located in the Location HTTP-header.

The real data is fetched from the redirect URL. This is standard HTTP behavior that is supported by all HTTP clients. For example curl -L "http://gameads-admin.applifier.com/stats/monetization-api?apikey=APIKEY" will directly output the file to the console.

The statistics server will not work if accessed without a valid URL signature. If the authentication fails, the authentication server will respond with an HTTP/1.1 200 OK header, with an error message in the body:

{"error":"Authentication error","responseCode":500,"status":"error"}

Request Format

Request format

The monetization statistics API supports the following request format:

http://gameads-admin.applifier.com/stats/monetization-api?apikey=<apikey>&fields=<fields>[&splitBy=<splitbyfields>][&scale=<scale>][&start=<startDate>][&end=<endDate>][&sourceIds=<sourceIds>]

For Example:

curl -L "http://gameads-admin.applifier.com/stats/monetization-api?apikey=a0db655ac99b68cb4d1835e878e06473277dd061782dbeec813cb3b14cb723ee&splitBy=zone,country&fields=adrequests,available,views,revenue&start=2016-01-01&end=2016-10-01&scale=day&sourceIds=1003843" > ~/Desktop/UnityAdsMonetization.csv
Definitions:

These parameters are used to split your data.

NOTE: Splitting data across multiple dimensions grows the CSV exponentially, which can cause some large data sets to time out. The request will time out if the server takes more than 60 seconds to process the request.

  • <apikey> - The api authentication key retrieved from the Unity Ads Admin Panel in the API Keys tab.

  • <fields> - A comma separated list that defines the columns of available fields.

    • adrequests – Number of campaign requests (sampled for every 23rd attempt)
    • available – Number of successful campaign requests (sampled for every 23rd success)
    • started – Number of videos that started playing
    • views – Number of videos that completed
    • revenue - Total earnings
    • offers – (Deprecated)
    • all - Include all of the above

      If left empty, <fields> defaults to all.

  • <splitbyfields> - A comma-separated list that expands the rows, splitting data by the following fields.

    • source – Split by source game ID
    • zone – Split by source game's placement IDs
    • country – Split by users’ country

      If left empty, <splitbyfields> defaults to country. Use splitBy=none if you do not want to split your data.

  • <scale> – A value that splits data by time resolution. Each day is split at 00:00 UTC.

    • hour
    • day
    • week
    • month
    • quarter
    • year
    • all – Removes time resolution splitting, returning the total values within the specified time period

      If left empty, <scale> defaults to day.

  • <start> & <end> – The start and end times for the data set.

    • Negative numbers are treated as days relative to the current date. For example, "start=-7" is 7 days ago
    • The date string uses ISO format: YYYY-MM-DDThh:mm:ss.sssZ. For example: 2016-02-01T14:00:00.000Z
    • The start and end dates will be rounded upwards to next full hour. For example, the 14:00:05.000Z will be rounded to 15:00:00.000Z
    • Using <scale>=day, with non-midnight <start> & <end> dates will select the range per hour and not the whole day

      If left empty, <start> defaults to -7 and <end> defaults to 0, defining the past week.

  • <sourceIds> – comma separated list of game ids to filter the results. By default, all the games of the developer will be included.

    • Example: sourceIds=1003843

For additional questions, please contact us at unityads-support@unity3d.com.


Still need help? Get in touch!
Last updated on 24th Feb 2017