Reporting API (V 1.0.4)

 Introduction

The Publisher Reporting API enables publishers to monitor their performance within the Start.io ( Formerly StartApp) network.
Paging option is available as of this version (1.0.4).

This document describes the reporting API syntax and includes various examples. 

  1.  The API is done via HTTP GET method. The response parameters are returned in a JSON format in the HTTP body.
  2. Report request parameters MUST be URL encoded.
  3. Access to Start.io’s Server is restricted, partnerId and password (token) shall be provided upon integration request.
  4. Data history: The API cannot retrieve data older than three months.
  5. By default, the report can retrieve a limited number of rows. To retrieve full report (without a record limitation) use the paging option.
  6. Our Reporting API is limited to 100 requests per minute per user. Exceeding this limit will result in an error with the HTTP status code 429 - Too Many Requests.

Resource Details

URL: https://api.start.io/pub/report/1.0
Method: GETResponse Format: JSON
API Version: 1.0

Request

The request is a valid HTTP GET URL that includes the report query parameters Request parameters:
Mandatory: authentication parameters, time frame
Optional: dimensions, filter operators
Request structure: https://api.start.io/pub/report/1.0?partner=1234&token=7894& startDate=yyyymmdd&endDate= yyyymmdd& dimension=dimension1,dimension2,dimension3

Mandatory Request Parameters

Field Name

Type

Description

Example

partner

String

Partner Id provided by Start.io

198765432

token

String

Security token provided by Start.io

12hgt78564

startDate

Time (yyyymmdd)

The first day of the report time frame.
*The API data is available for the last 3 months

20180315

endDate

Time (yyyymmdd)

The last day of the report time frame

20180316

Optional Request Parameters

The optional parameters include dimensions and filter operators

Report dimensions

The dimension "date" is chosen by default and should not be added to the request

Field Name

Type

Description

Example

prod

String

The package name of your application

com.foobar.app

segId

String

Represent the app identification number

 12365479

os

Int

The operating system of your application
Possible values:
0 - ANDROID
1- iOS

 

adType

Int

The ad format
Possible values:
0 – Banner
1 – Return Ad
2 - Rich Text (relevant for native ads)
3 - Full page interstitial
4 - Splash
6 - Video
7 - Rewarded
8 - MRec
9 - Cover

 

country

String

A two-character ISO 3166-1 country code for the country
Note: Need to be encoded

US

connectionType

String

The connection type that has been used by the device
Possible values: " WIFI", "NO WIFI"
Note: Need to be encoded

 

deviceType

String

The device type
Possible values: "MOBILE", "TABLET"
Note: Need to be encoded

 

adTagId

String Identifier that can be attached to any ad 12365479

Filter Operator

The filter operator enables the client to retrieve only a subset of the query result.
The operator must be URL encoded in order to be included in URL query strings.

Operator

Description

Example

URL Encoded Form

Filter

Exact match (Filter)

country=US,GB

country=US%2cGB

Pagination information

By default, the API will return a single page of data.
To retrieve all pages of data you need to include in the request the following parameter.

Field name

Value

URL structure

pagingEnabled

true

https://api.start.io/pub/report/1.0?partner=1234&token=7894& startDate=yyyymmdd&endDate= yyyymmdd& dimension=dimension1,dimension2,dimension3&pagingEnabled=true

In the response, you will receive the data and a field called "next": 
"next": "nextToken=123456abcde&offset=1"

To get the next page you need to include this parameter in the request.

Request structure: https://api.start.io/pub/report/1.0?partner=1234&token=7894& startDate=yyyymmdd&endDate= yyyymmdd& dimension=dimension1,dimension2,dimension3&nextToken=123456abcde&offset=1

In ecah request you will recive the data and the next field. the last page will include only the data without the next field.

Response

The response data structure includes dimensions and metrics.
The list of dimensions includes 'date' and dimension fields specified in the request.
The list of metrics is constant and will appear in every response.
Response structure:

{
  "logs": [
    "This sections contains errors and warnings regarding the transaction"
  ],
  "data": [
    "This sections contains the report data"
  ]
} 

In case paging is enabled the response structure will look like: 

{
  "logs": [
    "This sections contains errors and warnings regarding the transaction"
  ],
  "data": [
    "This sections contains the report data"
  ],
  "next": "nextToken=123456abcde&offset=1"
} 

Metrics

Field Name

Type

Description

Example

impressions

Int

The number of times that the ad has been presented

845464

clicks

Int

The total number of clicks

35546

ctr

Double

ctr=clicks/impressions

0.313

revenue

Double

The revenue generated from the relevant conversions ($)

132.124

cpm

Double

cpm=revenue/impressions*1000

1.245

Logs

The 'logs' section in the response describes errors and warnings regarding the transaction

Code

Severity

Message

SA101

error

Server error

SA102

error

Unauthenticated

SA103

error

Unauthorized

SA104

error

Incorrect API version

SA105

error

Incorrect start parameter

SA106

error

Incorrect end parameter

SA107

error

The API data is available for the last 3 months

SA108

error

A future end is not allowed

SA109

error

Invalid dimension

SA117

error

Query size is too big- please be more specific or enable paging

SA120

error

Invalid next token or offset parameter (when paging is enabled)

SA121

error

pagingEnabled cannot be sent with nextToken or offset

Examples

Example #1:
The following example describes a scenario, where the partner id and/or the token are missing or not verified
Request: https://api.start.io/pub/report/1.0?partner=???&token=???startDate=20181001&endDate=20181010
Response:

{
  "logs": [
    {
      "severity": "error",
      "messageCode": "SA102",
      "message": "Unauthenticated"
    }
  ],
  "data": []
} 

Example #2:
The following example describes a request for a specific time frame.
By default, the only dimension is 'date'.
Request: https://api.start.io/pub/report/1.0?partner=80584578&token=7858521348bbcdacef89cf384f1&startDate=20181009 &endDate=20181010

Response:

{
  "logs": [],
  "data": [
    {
      "clicks": 14964,
      "impressions": 69462,
      "revenue": 71.29147,
      "ctr": 0.21542,
      "cpm": 1.02633,
      "date": 20181009
    },
    {
      "clicks": 15318,
      "impressions": 70753,
      "revenue": 81.9642,
      "ctr": 0.2164,
      "cpm": 1.15845,
      "date": 20181010
    }
  ],
  "results": 2
}

Example #3:
The following example describes a request for specific time frame with the following 2 different dimensions ('date', 'segId')
Request: http://api.start.io/pub/report/1.0?partner=80584578&token=7858521348bbcdacef89cf384f1&startDate=20181009 &endDate=20181010&dimension=segId

Response:


{
  "logs": [],
  "data": [
    {
      "clicks": 20,
      "impressions": 123,
      "revenue": 0.55134,
      "ctr": 0.1626,
      "cpm": 4.48247,
      "segId": "208785107",
      "date": 20181010
    },
    {
      "clicks": 2,
      "impressions": 7,
      "revenue": 0,
      "ctr": 0.28571,
      "cpm": 0,
      "segId": "206047872",
      "date": 20181010
    },
    {
      "clicks": 124,
      "impressions": 477,
      "revenue": 3.85056,
      "ctr": 0.25995,
      "cpm": 8.07246,
      "segId": "208783164",
      "date": 20181010
    },
    {
      "clicks": 334,
      "impressions": 1283,
      "revenue": 0,
      "ctr": 0.26032,
      "cpm": 0,
      "segId": "206853570",
      "date": 20181010
    },
    {
      "clicks": 1665,
      "impressions": 8382,
      "revenue": 11.0568,
      "ctr": 0.19863,
      "cpm": 1.31911,
      "segId": "208858446",
      "date": 20181010
    },
    {
      "clicks": 905,
      "impressions": 6105,
      "revenue": 5.79529,
      "ctr": 0.14823,
      "cpm": 0.94927,
      "segId": "206645562",
      "date": 20181010
    },
    {
      "clicks": 322,
      "impressions": 5535,
      "revenue": 0.73868,
      "ctr": 0.05817,
      "cpm": 0.13345,
      "segId": "207358515",
      "date": 20181010
    },
    {
      "clicks": 504,
      "impressions": 1998,
      "revenue": 15.50842,
      "ctr": 0.25225,
      "cpm": 7.76197,
      "segId": "206665287",
      "date": 20181010
    },
    {
      "clicks": 398,
      "impressions": 2177,
      "revenue": 0.60125,
      "ctr": 0.18282,
      "cpm": 0.27618,
      "segId": "205316540",
      "date": 20181010
    },
    {
      "clicks": 10751,
      "impressions": 41784,
      "revenue": 42.15809,
      "ctr": 0.25729,
      "cpm": 1.00895,
      "segId": "205418137",
      "date": 20181010
    },
    {
      "clicks": 293,
      "impressions": 2882,
      "revenue": 1.70373,
      "ctr": 0.10166,
      "cpm": 0.59116,
      "segId": "209874625",
      "date": 20181010
    }
  ],
  "results": 12
}

Example #4:
The following example describes a request with paging enables.
Request: https://api.start.io/pub/report/1.0?partner=80584578&token=7858521348bbcdacef89cf384f1&startDate=20181009 &endDate=20181010&dimension=segId&pagingEnabled=true

Response:


{
  "logs": [],
  "data": {
    "data": [
      {
        "clicks": 20,
        "impressions": 123,
        "revenue": 0.55134,
        "ctr": 0.1626,
        "cpm": 4.48247,
        "segId": "208785107",
        "date": 20181010
      },
      {
        "clicks": 2,
        "impressions": 7,
        "revenue": 0,
        "ctr": 0.28571,
        "cpm": 0,
        "segId": "206047872",
        "date": 20181010
      }
    ],
    "next": "nextToken=123456abcde&offset=1"
  }
}
Was this article helpful?
Have more questions? submit a request