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://spx-api.smaato.com/publisherportal/api/reporting/v1/report

Request Type

HTTPS POST Request

Authentication

OAuth 2.0

Authentication

As soon as you have retrieved your authentication credentials (client_id and client_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:

curl --request POST \
--url https://auth.smaato.com/v2/auth/token/ \
--header 'content-type: application/x-www-form-urlencoded' \
--data client_secret=CLIENT_SECRET \
--data client_id=CLIENT_ID \
--data 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}.

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: KPIs for all applications for the given time period.

curl -H  "Accept: application/json" \
 -H  "Authorization: Bearer ACCESS_TOKEN" \
"https://spx-api.smaato.com/publisherportal/api/reporting/v1/report?start=2022-01-01&end=2022-01-31&display-by=APP"

Request Parameters

How to Use Display-By

Display-by 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

PERIOD

view report by Period

APP

view report by Application ID

ADSPACE

view report by Adspace ID

COUNTRY

view report by Country (ISO 3166 Standard)

LINEITEM

view report by Line Item ID

LINEITEM_TYPE

view report by Line Item Type (SMX, Direct, House, Network, Preferred Deal, Private Exchange)

DIRECT_ORDER

view report by Order ID (applicable for Direct Orders)

ADVERTISER

view report by Advertiser ID (applicable for Direct Orders)

CREATIVE

view report by Creative ID (applicable for Direct Orders)

NETWORK

view report by Network ID

DEAL

view report by Deal ID (applicable for Private Marketplace)

BUYER 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 split-by parameter. See here an example:

curl -H  "Accept: application/json" \
 -H  "Authorization: Bearer ACCESS_TOKEN" \
"https://spx-api.smaato.com/publisherportal/api/reporting/v1/report?start=2022-01-01&end=2022-01-31&display-by=APP&split-by=ADSPACE"

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

start

as yyyy-mm-dd string 2022-01-01

end

as yyyy-mm-dd string 2022-01-31

Example:

curl -H  "Accept: application/json" \
 -H  "Authorization: Bearer ACCESS_TOKEN" \
"https://spx-api.smaato.com/publisherportal/api/reporting/v1/report?start=2022-01-01&end=2022-01-31&display-by=APP"

How to Use Filters

You’ll need to enter a time period to specify the date range for your report (all parameters are

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 (see mapping in appendix) 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 dimension LineItemType, please refer to the Appendix at the end.

Example:

curl -H  "Accept: application/json" \
 -H  "Authorization: Bearer ACCESS_TOKEN" \
"https://spx-api.smaato.com/publisherportal/api/reporting/v1/report?start=2022-01-01&end=2022-01-31&display-by=APP&apps=8681,8632"

How to Use Ordering

To order your result set, you may use the following parameters. Specify the criteria that you’d like to order by, and choose between ascending or descending values.

Parameter Description Type Mandatory Default

asc

Ascending (true) or descending (false) order

boolean

no

false

order

an order criteria (NAME, ID, GROSS_REVENUE, NET_REVENUE, IMPRESSIONS, GROSS_ECPM, NET_ECPM, CLICKS, AD_REQUESTS, FILLRATE, SERVED_ADS, VIEWRATE)

string

no

GROSS_REVENUE

Example:

curl -H  "Accept: application/json" \
 -H  "Authorization: Bearer ACCESS_TOKEN" \
"https://spx-api.smaato.com/publisherportal/api/reporting/v1/report?start=2022-01-01&end=2022-01-31&display-by=APP&order=CLICKS&asc=false"

How to Use KPIs

The API will always return all KPIs available.

Please Note:

KPI Parameter Description

grossRevenue

Total Publisher Revenue

netRevenue

Net Publisher Revenue
impressions # of Impressions
grossEcpm effective CPM (gross)
netEcpm effective CPM (net)
clicks # of Clicks
servedAds # of Served Ads
viewrate View rate
ctr Clickthrough Rate
adRequests # of Ad Requests
fillrate Fillrate

Responses

The response contains the KPIs per requested criteria and the aggregated total KPIs. Additionally it contains some meta data.

Example:

{
  "data": {
    "lines": [
      {
        "line": {
          "name": "My First App",
          "additionalName": null,
          "entityId": 8681,
          "entityParentId": null,
          "entityType": "APP",
          "active": true,
          "kpis": {
            "grossRevenue": 99.954,
            "netRevenue": 79.786,
            "impressions": 39899,
            "grossEcpm": 2.505,
            "netEcpm": 2,
            "clicks": 948,
            "servedAds": 219876,
            "viewrate": 18.146,
            "ctr": 2.376,
            "adRequests": 407862,
            "fillrate": 53.909
          }
        },
        "splitLines": null
      },
      {
        "line": {
          "name": "My Second App",
          "additionalName": null,
          "entityId": 8632,
          "entityParentId": null,
          "entityType": "APP",
          "active": true,
          "kpis": {
            "grossRevenue": 99.914,
            "netRevenue": 88.95,
            "impressions": 275048,
            "grossEcpm": 0.363,
            "netEcpm": 0.323,
            "clicks": 1618,
            "servedAds": 589826,
            "viewrate": 46.632,
            "ctr": 0.588,
            "adRequests": 943408,
            "fillrate": 62.521
          }
        },
        "splitLines": null
      }
    ],
    "total": {
      "grossRevenue": 199.868,
      "netRevenue": 168.736,
      "impressions": 314947,
      "grossEcpm": 0.635,
      "netEcpm": 0.536,
      "clicks": 2566,
      "servedAds": 809702,
      "viewrate": 38.897,
      "ctr": 0.815,
      "adRequests": 1351270,
      "fillrate": 59.922
    }
  },
  "metaData": {
    "publisherId": 4711,
    "totalNumberOfElements": 2,
    "numberOfElements": 2,
    "offset": 0,
    "displayBy": "APP",
    "splitBy": null,
    "reportId": "ZIOoetOesrKZW/FKAJEBiQ==",
    "timestamp": 1645706483928,
    "duration": 43
  }
}

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

{
  "globalMessage":"Invalid Data",
  "validationErrors":[{
    "field":"splitBy",
    "message":"Split by 'ADVERTISER' is not supported in combination with display by 'DEAL_ID'"
  }],
  "status":"400 (Bad Request)"
}

Example Use Cases for Daily Revenue

KPIs per day split by Ad Space for previous week

Please specify a start date 6 days prior to the actual date, and that actual date as end date. The specified start and end days are included in the report.

Example:

curl -H  "Accept: application/json" \
 -H  "Authorization: Bearer ACCESS_TOKEN" \
"https://spx-api.smaato.com/publisherportal/api/reporting/v1/report?start=2022-02-14&end=2022-02-20&display-by=PERIOD&split-by=ADSPACE"

KPIs per Country for a given time period

Example:

curl -H  "Accept: application/json" \
 -H  "Authorization: Bearer ACCESS_TOKEN" \
"https://spx-api.smaato.com/publisherportal/api/reporting/v1/report?start=2022-02-14&end=2022-02-20&display-by=COUNTRY"

KPIs per Line Item for a given time period

Example:

curl -H  "Accept: application/json" \
 -H  "Authorization: Bearer ACCESS_TOKEN" \
"https://spx-api.smaato.com/publisherportal/api/reporting/v1/report?start=2022-02-14&end=2022-02-20&display-by=LINEITEM"

KPIs per Creative for a given time period

Example:

curl -H  "Accept: application/json" \
 -H  "Authorization: Bearer ACCESS_TOKEN" \
"https://spx-api.smaato.com/publisherportal/api/reporting/v1/report?start=2022-02-14&end=2022-02-20&display-by=CREATIVE"

Appendix

Line Item Type Mapping

Line Item Type Name
NETWORK Network
SMAATO_EXCHANGE Smaato Exchange
DIRECT Direct
HOUSE House
PREFERRED_DEAL Preferred Deal
PRIVATE_EXCHANGE Private Exchange

Filter Parameter Name Mapping

Filter Parameter Name Display-By Criteria Expected Arguments
apps APP List of app IDs (integer)
adspaces ADSPACE List of ad space IDs (integer)
advertisers ADVERTISER List of advertiser IDs (integer)
direct-orders DIRECT_ORDER List of direct order IDs (integer)
network-orders NETWORK List of network order IDs (integer)
buyers BUYER List of buyer IDs (integer)
line-item-types LINEITEM_TYPE List of line item types (string)
line-items LINEITEM List of line item IDs (integer)
creatives CREATIVE List of creative IDs (integer)
countries COUNTRY List of country codes (string)
deals DEAL List of deal IDs (string)
Doc Feedback Product Feedback

Last Modified: May 31, 2023 at 1:11 pm