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.
- The API is done via HTTP GET method. The response parameters are returned in a JSON format in the HTTP body.
- Report request parameters MUST be URL encoded.
- Access to Start.io’s Server is restricted, partnerId and password (token) shall be provided upon integration request.
- Data history: The API cannot retrieve data older than three months.
- By default, the report can retrieve a limited number of rows. To retrieve full report (without a record limitation) use the paging option.
- 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. |
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 |
|
adType |
Int |
The ad format |
|
country |
String |
A two-character ISO 3166-1 country code for the country |
US |
connectionType |
String |
The connection type that has been used by the device |
|
deviceType |
String |
The device type |
|
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"
}
}