SPX Reporting API
Introduction
Smaato offers an HTTP based reporting API to publishers. The API provides the capability to retrieve traffic and revenue reports for a specific period of time.
Restrictions: Authentication Credentials
Authentication for the SPX Reporting API (2 step process)
Getting your OAuth Credentials from your SPX Account (under OAuth API Credentials)
First, log in to your SPX account and go to OAuth API Credentials in the user menu in the top right corner of SPX.

You will then be able to generate API credentials

Then, click on Create Client ID and you will get the necessary credentials.

Now, you can also generate the access token directly from this page by clicking Generate.
Generating an access token using the credentials (more information under Authentication below).
If you’ve been previously using v1 Authentication and would like to continue doing so, refer to your documentation for Authentication v1.

Requests
URL |
https://api.smaato.com/v1/reporting/ |
---|---|
Request Type |
HTTPS POST Request |
Content Type |
application/json |
Authentication |
Authentication
As soon as you have retrieved your authentication credentials (c
lient_id
and c
lient_secret
) from your SPX Account (under OAuth API Credentials), you need to retrieve an access token to get started.
To do so, make a POST Request to:
https://auth.smaato.com/v2/auth/token/
The following the are data that you need to provide to the POST request:
client_id
– substitute this for your application’s client ID.
client_secret
– (this is the other credential provided by your account manager)
grant_type
= client_credentials
Example Access Token Request:
POST https://auth.smaato.com/v2/auth/token/ HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Content:
client_id={client_id}&client_secret={client_secret}&grant_type=client_credentials
In response to the POST request, you will receive a JSON object that will have the {access_token}. You may now access our API using this {access_token}.
access_token
expires every 10 hours, so you’ll have to repeat this step frequently. The access_token
needs to be provided as an Authorization header to all HTTP requests to all Smaato API endpoints that need authorization. An example header is:Authorization: Bearer {access_token}
Example Request
As soon as you are set up with authentication, you can request your reporting data as per the following example. Please note that all parameters are case sensitive.
Example: Clicks for all applications for the given time period
POST https://api.smaato.com/v1/reporting/ HTTP/1.1
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json
Host: api.smaato.com
Content:
{
"criteria":{
"dimension":"ApplicationId",
"child": null
},
"kpi": {
"clicks": true
},
"period":{
"period_type":"fixed",
"start_date":"2015-04-14",
"end_date":"2015-08-13"
}
}
Request Parameters
How to Use Criteria
Criteria are dimensions by which you are able to view your reporting data. By default, you’ll get all data for a given dimension. If you’re looking to get more specific data, see How to Use Filters (below).
Dimension | Description |
---|---|
|
view report by Period |
|
view report by Application ID |
|
view report by Application Type (OS, mobile site) |
|
view report by Adspace ID |
|
view report by Country (ISO 3166 Standard) |
|
view report by Line Item ID |
|
view report by Line Item Type (SMX, Direct, Network, Preferred Deal, Private Exchange) |
|
view report by Order ID (applicable for Direct Orders) |
|
view report by Advertiser ID (applicable for Direct Orders) |
|
view report by Creative ID (applicable for Direct Orders) |
|
view report by Deal ID (applicable for Private Marketplace) |
|
view report by Demand Partner ID (applicable for Private Marketplace) |
Using Multiple Criteria Dimensions
It is possible to view a report by more than one dimension; the second dimension then must be set as a child of the first dimension. See here an example:
{
"criteria":{
"dimension":"ApplicationId",
"child": {
"dimension": "ApplicationType",
"child": null
}
},
"period":{
"period_type":"fixed",
"start_date":"2015-04-14",
"end_date":"2015-08-13"
}
}
Expanded Dimension Attributes
Some criteria dimensions can be expanded with additional attributes you may want to retrieve. These can be specified in the fields parameter.
List of all available attributes:
Dimension | Values |
---|---|
|
name, app_type, app_url, iab_category, created |
|
name, width, height, iab_category, page_placement |
|
name, creative_type, status, created |
|
name, advertiser, status, created |
|
name, status, start_date, end_date, priority, pacing, traffic_allocation, created |
Example:
{
"criteria":{
"dimension":"ApplicationId",
"fields": [
"name",
"app_url"
],
"child": null
},
"period":{
"period_type":"fixed",
"start_date":"2015-04-14",
"end_date":"2015-08-13"
}
}
How to use Time Periods
You’ll need to enter a time period to specify the date range for your report (all parameters are mandatory).
Parameter | Description | Type | Example |
---|---|---|---|
|
(only fixed for now) |
string |
fixed |
|
as yyyy-mm-dd |
string |
2015-04-18 |
|
as yyyy-mm-dd |
string |
2015-04-28 |
Example:
{
"criteria":{
"dimension":"ApplicationId",
"child": null
},
"kpi": {
"clicks": true
},
"period":{
"period_type":"fixed",
"start_date":"2015-04-14",
"end_date":"2015-08-13"
}
}
How to Use Filters
To filter your result set, you can use filters. Filters are a list of objects that reduce the amount of data transferred through the API.
All criteria dimensions (as specified above) are available as Filters; to get a list of all available values for a dimension, request the according to dimension without any filter.
To view the mapping of the criteria dimensions ApplicationType and LineItemType, please refer to the Appendix at the end.
Parameter | Description | Type | Mandatory | Example |
---|---|---|---|---|
field |
any Criteria dimension |
string |
yes |
|
values |
match field value |
list |
yes |
[1,2,3,4] |
Example:
{
"criteria":{
"dimension":"ApplicationId",
"child": null
},
"filters": [
{
"field": "ApplicationId",
"values": [1]
}
],
"period":{
"period_type":"fixed",
"start_date":"2015-04-14",
"end_date":"2015-08-13"
}
}
How to Use Ordering
To order your result set, you may use the ordering parameter – an enum identifying the field to order the result set on. Specify the field type from the filter that you’d like to request, and choose between ascending or descending values.
Parameter | Description | Type | Mandatory | Example |
---|---|---|---|---|
field |
a criteria dimension or KPI |
string |
yes |
ApplicationId |
order |
ASCENDING or DESCENDING |
string |
yes |
ASCENDING |
Example:
{
"criteria":{
"dimension":"ApplicationId",
"child": null
},
"orderings": [
{
"field":"Clicks",
"order":"DESCENDING"
}
],
"period":{
"period_type":"fixed",
"start_date":"2015-04-14",
"end_date":"2015-08-13"
}
}
How to Use KPIs
Use KPI parameters to get the data you’re looking for. If you don’t specify any KPIs in your request, the API will return all KPIs available.
incomingAdRequests
is not available for the following dimensions: LineItemId, LineItemType, OrderId, AdvertiserId, CreativeId
.Parameter | Description | Type |
---|---|---|
|
# of Ad Requests |
boolean |
|
# of Served Ads |
boolean |
|
# of Impressions |
boolean |
|
# of Clicks |
boolean |
|
Clickthrough Rate |
boolean |
|
effective CPM |
boolean |
|
Total Publisher Revenue |
boolean |
|
Net Publisher Revenue |
boolean |
|
Fillrate |
boolean |
Example:
{
"criteria":{
"dimension":"ApplicationId",
"child": null
},
"kpi":{
"clicks":true,
"impressions": true,
"CTR": true
},
"period":{
"period_type":"fixed",
"start_date":"2015-04-14",
"end_date":"2015-08-13"
}
}
Responses
Content Type | application/json |
---|
The response looks similar to the request but is enriched with the requested values.
Example Response:
[
{
"kpi":{
"clicks":58208
},
"criteria":[
{
"meta":{
},
"name":"Applicationid",
"value":1
}
]
},
{
"kpi":{
"clicks":47147
},
"criteria":[
{
"meta":{
},
"name":"Applicationid",
"value":2
}
]
}
]
Errors
Errors are JSON objects in combination with a HTTP error code other than HTTP 200. Error messages are always a list of strings that describe the error at hand.
Example Error Object
{
"criterita":{
"dimension":[
"Invalid dimension: IDontExist"
]
}
Example Use Cases for Daily Revenue
Ad requests, Impressions and eCPM per Adspace for Previous Week
For now, the only period_type available is fixed. Therefore, please specify a start_date 7 days prior to the actual date, and that actual date as end_date.
{
"criteria":{
"dimension":"Date",
"child": {
"dimension": "ApplicationId",
"child": {
"dimension": "AdspaceId",
"child": null
}
}
},
"kpi":{
"incomingAdRequests":true,
"impressions": true,
"eCPM": true,
"grossRevenue": true
},
"period":{
"period_type":"fixed",
"start_date":"2015-08-13",
"end_date":"2015-08-20"
}
}
Daily Revenue and Fillrate per Country for a Given Time period
Example:
{
"criteria":{
"dimension":"CountryCode",
"child": null
},
"kpi":{
"fillrate": true,
"grossRevenue": true
},
"period":{
"period_type":"fixed",
"start_date":"2015-08-13",
"end_date":"2015-08-20"
}
}
Daily Revenue and eCPM per Line Item for a Given Time period
In this example, we’re using the extended attributes name and priority to return the line item’s names and priorities.
Example:
{
"criteria":{
"dimension":"LineItemId",
"fields": [
"name",
"priority"
],
"child": null
},
"kpi":{
"eCPM": true,
"grossRevenue": true
},
"period":{
"period_type":"fixed",
"start_date":"2015-08-13",
"end_date":"2015-08-20"
}
}
Clickthrough Rate Per Creative for a Given Time Period
Example:
{
"criteria":{
"dimension":"CreativeId",
"child": null
},
"kpi": {
"CTR": true
},
"period":{
"period_type":"fixed",
"start_date":"2015-08-13",
"end_date":"2015-08-20"
}
}
Appendix
ApplicationType
ApplicationType | Name |
---|---|
1 |
Mobile Website |
2 |
iOS |
3 |
Android |
Line Item Type Mapping
Line Item Type | Name |
---|---|
AdNetwork |
Network |
SMX |
Smaato Exchange |
Direct |
Direct |
House |
House |
PreferredDeal |
Preferred Deal |
PrivateExchange |
Private Exchange |
Last Modified: September 30, 2019 at 2:34 pm
© 2005-2020 Smaato, Inc. All Rights Reserved. Smaato® is a registered trademark of Smaato, Inc.