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. 

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

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

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.

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.

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

Logs

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

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