Reporting API (V 1.10)

Introduction 

Resource details

URL: https://api.start.io/adv/report/1.0
Method: GET
Response Format: JSON

Request

The request is a valid HTTP GET URL that includes the report query parameters.
Request parameters:

• Mandatory: authentication parameters, time frame
• Optional: optional dimensions, filter operators
• Request headers:
  • Field Name: Accept-Encoding
  • Value: gzip
  • Mandatory: No
  • Description: Compress response data in gzip format.
    ‘Content-Encoding: gzip’ header will be added to the response headers.
• Request structure:

  https://api.start.io/adv/report/1.0?partner=987654321&token=12hgt78564&startDate=yyyymmdd&endDate= yyyymmdd&dimension=dimension1&dimension=dimension2&dimension=dimension3

Mandatory Request Parameters

 Optional Request Parameters

The optional parameters include optional dimensions and filter operators.

Optional Dimensions

The following dimensions are optional and can be added to the report if mentioned as parameters in the request. 

See the full list of dimensions in the response chapter.

Request example:

https://api.start.io/adv/report/1.0?partner=123456789&token=**token**&startDate=20181022&endDate=20181027&dimension=date&dimension=country

Filter Operator

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

Note: Filtering is not applicable for the dimension "campaignName". In order to filter specific campaigns, use filtering on campaignId.

Request Example with filtering:

In the following request, we filter data which is relevant to campaignId 30023655. 
https://api.start.io/adv/report/1.0?partner= 123456789&token=**token**&startDate=20181001& endDate=20181028&dimension=date&dimension=country&campaignId=30023655

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/adv/report/1.0?partner=1234&token=**token**& startDate=yyyymmdd&endDate=yyyymmdd&dimension=dimension1,dimension2,dimension3&nextToken=123456abcde&offset=1

In each request you will receive 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 include the default dimensions and the optional dimensions.
• 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"
  ]
}

Dimensions

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/adv/report/1.0?partner=???&token=**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 with the dimensions: 'date' and 'country'.
By default, the reports also include the dimensions 'campaignId' and 'campaignName.'

Request:

https://api.start.io/adv/report/1.0?partner=105840068& token=**token**&startDate=20181006&endDate=20181007& dimension=date&dimension=country

Response:

{
  "logs": [],
  "data": [
    {
      "campaignName": "AAA_Android_US_Phone_Display_CID1234",
      "impressions": 142546,
      "clicks": 2763,
      "installs": 20,
      "spent": 20,
      "ctr": 0.01938,
      "cr": 0.00723,
      "date": 20181006,
      "country": "US",
      "campaignId": "300032556"
    },
    {
      "campaignName": " AAA_Android_US_Phone_Display_CID1234",
      "impressions": 1,
      "clicks": 0,
      "installs": 0,
      "spent": 0,
      "ctr": 0,
      "cr": 0,
      "date": 20181007,
      "country": "JP",
      "campaignId": "SAP_23662"
    },
    {
      "campaignName": " AAA_Android_US_Phone_Display_CID1234",
      "impressions": 134698,
      "clicks": 2936,
      "installs": 24,
      "spent": 24,
      "ctr": 0.02179,
      "cr": 0.00817,
      "date": 20181007,
      "country": "US",
      "campaignId": "300023662"
    }
  ]
}

Example #3

The following example describes a request with paging enables.

Request:

https://api.start.io/adv/report/1.0?partner=123456789&token=**token**&startDate=20181006&endDate=20181007& dimension=date&dimension=country&&pagingEnabled=true

Response:

{
  "logs": [],
  "data": {
    "data": [
      {
        "campaignName": "AAA_Android_US_Phone_Display_CID1234",
        "impressions": 142546,
        "clicks": 2763,
        "installs": 20,
        "spent": 20,
        "ctr": 0.01938,
        "cr": 0.00723,
        "date": 20181006,
        "country": "US",
        "campaignId": "300032556"
      },
      {
        "campaignName": " AAA_Android_US_Phone_Display_CID1234",
        "impressions": 1,
        "clicks": 0,
        "installs": 0,
        "spent": 0,
        "ctr": 0,
        "cr": 0,
        "date": 20181007,
        "country": "JP",
        "campaignId": "SAP_23662"
      },
      {
        "campaignName": " AAA_Android_US_Phone_Display_CID1234",
        "impressions": 134698,
        "clicks": 2936,
        "installs": 24,
        "spent": 24,
        "ctr": 0.02179,
        "cr": 0.00817,
        "date": 20181007,
        "country": "US",
        "campaignId": "300023662"
      }
    ],
    "next": "nextToken=123456abcde&offset=1"
  }
}