Revision History

 

Version

Date

Author

Note

1.0

2015-06-24

BR

Initial version

1.0.1

2015-08-14

BR

Minor changes & improvements

1.1

2015-09-15

BR

Introduced Private Marketplace Criteria Dimensions

Added Ordering Parameters

Updated Auth Details & Example Request

1.1.72016-03-31BR

Misc backend changes & updates

New authentication endpoint version (v2)

Introduction

Smaato offers a 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

The API requires an OAuth 2.0 authentication.

PLEASE NOTE:

Never hand your API credentials (Client ID & Client Secret) to a third party! This would compromise the security of your account.

Authentication for the SPX Reporting API requires 2 steps:

  1. Getting your OAuth Credentials from your SPX Account (under OAuth API Credentials)

    1. Log in to your SPX account and go to OAuth API Credentials


    2. You'll then be able to generate API Credentials:


    3. Click on Create Client ID, and you'll get the necessary credentials:


    4. You can also generate the Access Token directly from this page by clicking Generate:



  2. 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

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’ll 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}.

Please note:

The 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’re 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"
  }
}

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

Date

view report by Period

ApplicationId

view report by Application ID

ApplicationType

view report by Application Type (OS, mobile site)

AdspaceId

view report by Adspace ID

CountryCode

view report by Country (ISO 3166 Standard)

LineItemId

view report by Line Item ID

LineItemType

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

OrderId

view report by Order ID (applicable for Direct Orders)

AdvertiserId

view report by Advertiser ID (applicable for Direct Orders)

CreativeId

view report by Creative ID (applicable for Direct Orders)

DealId

view report by Deal ID (applicable for Private Marketplace)

DemandPartnerId

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.

 

{
  "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 that you’re using can optionally 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

ApplicationId

name, app_type, app_url, iab_category, created

AdspaceId

name, width, height, iab_category, page_placement

CreativeId

name, creative_type, status, created

OrderId

name, advertiser, status, created

LineItemId

name, status, start_date, end_date, priority, pacing, traffic_allocation, created

 

 

{
  "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

period_type

(only fixed for now)

string

fixed

start_date

as yyyy-mm-dd

string

2015-04-18

end_date

as yyyy-mm-dd

string

2015-04-28

{
  "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 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

ApplicationId

values

match field value

list

yes

[1,2,3,4]

{
  "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

{
  "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.

Please note: the KPI incomingAdRequests is not available for the following dimensions:

LineItemId, LineItemType, OrderId, AdvertiserId, CreativeId.

 

Parameter

Description

Type

incomingAdRequests

# of Ad Requests

boolean

servedAds

# of Served Ads

boolean

impressions

# of Impressions

boolean

clicks

# of Clicks

boolean

CTR

Clickthrough Rate

boolean

eCPM

effective CPM

boolean

grossRevenue

Total Publisher Revenue

boolean

netRevenue

Net Publisher Revenue

boolean

fillrate

Fillrate

boolean

{
  "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

In essence, the Response looks similar to the Request, 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

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 given time period

 

{
  "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 given time period

In this example, we’re using the Extended Attributes name and priority to return the Line Item’s names and priorities.

{
  "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 given time period

 

{
  "criteria":{
    "dimension":"CreativeId",
    "child": null
  },
  "kpi": {
      "CTR": true
  },
  "period":{
    "period_type":"fixed",
    "start_date":"2015-08-13",
    "end_date":"2015-08-20"
  }
}

Appendix

ApplicationType Mapping

 

ApplicationType

Name

1

Mobile Website

2

iOS

3

Android

4

Blackberry

7

Windows Phone

LineItemType Mapping

 

LineItemType

Name

AdNetwork

Network

SMX

Smaato Exchange

Direct

Direct

House

House

PreferredDeal

Preferred Deal

PrivateExchange

Private Exchange

Disclaimer

© 2016 Smaato Inc. All rights reserved.


All copyrights, trademarks, trade names, patents, industrial designs, and other intellectual property rights contained herein, including text, illustrations and animation are the exclusive property of Smaato Inc. and is protected by international copyright and by other intellectual property rights.


All rights not expressly conferred are reserved. Except as otherwise indicated, you may not modify the materials available herein in any way or use them for any commercial purposes without our permission.


All documentation, data, reports, ideas, concepts and/or their application, and/or the presentation of its information is proprietary to and embodies the confidential technologies, design, and processes of Smaato Inc. and are to be treated as strictly confidential.


The information (including, but by no means limited to, data, drawings, specification, documentation, software listings, source and/or object code) shall not be disclosed, manipulated, and/or disseminated in any manner inconsistent with the nature and/or conditions under which this documentation has been issued.


Smaato Inc. shall not be liable for any expenses, damages, and/or related costs, which may result from the use of any information, contained hereafter.


SMAATO INC MAKES NO WARRANTY OF ANY KIND THAT THE SMAATO INC SERVICE AND/OR THE SITE WILL ALWAYS BE AVAILABLE, ACCESSIBLE, UNINTERRUPTED, TIMELY, AND SECURE OR OPERATE WITHOUT ERROR OR THAT ANY SOFTWARE PROVIDED HEREUNDER WILL OPERATE WITHOUT ERROR.


SMAATO INC SHALL NOT BE LIABLE FOR ANY DAMAGES, EXPENSES AND/OR ANY RELATED COSTS, WHICH MAY RESULT FROM THE USE OF ANY INFORMATION, CONTAINED HEREIN.


Smaato Inc. reserves the right to make any modification to this manual or the information contained herein at any time without notice.

Contact

 

San Francisco

Hamburg

Singapore

New York

240 Stockton St., 10th Floor


San Francisco, CA 94108

Valentinskamp 70, Emporio 19th Floor


20355 Hamburg, Germany

333 North Bridge Rd, #05­00


Singapore 188721

Empire State Building

350 Fifth Avenue, Suite 4210


New York, NY 10118

T: +1 (650) 286­-1198

T: +49 (40) 3480-9490

T: +65 6336-6815

T: +1 (646) 807-4596

americas@smaato.com

emea@smaato.com

apac@smaato.com

americas@smaato.com