Reporting API (V 1.10)

Introduction 

The advertiser reporting API enables advertisers to monitor their performance within the StartApp network.
Paging option is available as of this version (1.10).

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 StartApp’s Server is restricted, partnerId and password (token) shall be provided upon integration request.
  4. Data history:
    1. The API cannot retrieve data older than three months.
    2. To prevent a query from retrieving too much data you may receive error #SA117 (status code 400).
  5. By default, the report can retrieve a limited number of rows. To retrieve full report (without a record limitation) use the paging option.

Resource details

URL: http://api.startapp.com/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 Request Parameters

Field Name

Type

Description

Example

partner

String

Partner Id provided by StartApp

987654321

token

String

Security token provided by StartApp

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

Field Name Type Description Example
date Time (yyyymmdd) Specific day in the time frame 20180315
country String A two-character ISO 3166-1 country code for the country US
creative String Creative Id  4000012345
publisher String Publisher Id 156896546
application String App Id 236597562

Request example:

http://api.startapp.com/adv/report/1.0?partner=105840068&token=20765d18576921348bbcdacef89cf384f1&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.
Operator Description Example Example (URL Encoded Form)
Filter Exact match (Filter) country=US,GB country=US%2cGB

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.startapp.com/adv/report/1.0?partner= 130063258&token=4c75bcbc30e1fd3245711ea7efc13468&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.

Field name

Value

URL structure

pagingEnabled

true

https://api.startapp.com/adv/report/1.0?partner= 130063258&token=4c75bcbc30e1fd3245711ea7efc13468&startDate=20181001& endDate=20181028&dimension=date&dimension=country&campaignId
=30223655&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: http://api.startapp.com/adv/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 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

Field Name Type Appears in response? Description Example
campaignId String always An internal ID for the campaign 300012356
campaignName String always The name that was given to the campaign by the advertiser "iOS Dating campaign"
date Time (yyyymmdd) if specified in request Specific day in the time frame 20180315
country String if specified in the request A two-character ISO 3166-1 country code for the country US
creativeName String if creative specified in the request The name that was given to the creative by the advertiser "Banner EN"
creativeId String if creative specified in the request An internal ID for the creative 400235625
publisher String if specified in request The Publisher ID of the publishing app 123659655
application String if specified in request The App ID of the publishing app 203568988


Metrics

Field Name Type Description Example
impressions Int The number of times that the ad has been presented 845,464
clicks Int The total number of clicks 35,546
ctr Double ctr=clicks/impressions 0.453
installs Int The total number of installs 3,154
cr Double cr=installs/clicks 0.136
spent Double The amount of USD spent on the relevant conversions 32.124

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 date parameter
SA106 error Incorrect end date parameter
SA107 error No data available at this date
SA108 error Future end date is not allowed
SA109 error Invalid dimension
SA117 error Query size is too big - please be more specific
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:

http://api.startapp.com/adv/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 with the dimensions: 'date' and 'country'.
By default, the reports also include the dimensions 'campaignId' and 'campaignName.'

Request:

http://api.startapp.com/adv/report/1.0?partner=105840068& token=765d18576921348bbcdacef89cf384f1&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"
},
### This JSON is partial for example purposes ###
{
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:

http://api.startapp.com/adv/report/1.0?partner=105840068& token=765d18576921348bbcdacef89cf384f1&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"
}
}
Was this article helpful?
0 out of 0 found this helpful