1. Objective
This document provides directions on how to access YouAppi’s reporting API for partners.
2. API Request
2.1 Request URL Format
Access to the YouAppi reporting API is via HTTP GET, using the following base URL:
https://reports.youappi.com/publisher?2.2 Mandatory Parameters
The table below contains the parameters that must be included in the API request:
| Parameter Name | Description | Value Type | Example | Mandatory |
| apiKey | The apiKey is a unique key that will be provided to the publisher by YouAppi. | String | ab1c2de3-456f-78e9-h60d-2350f5fc722a | Yes |
| start | The start date of the data in the report. The allowed format is: ‘YYYY-MM-DD’. |
String | 2016-06-01 | Yes |
| end | The end date of the data in the report. The allowed format is: ‘YYYY-MM-DD’. This date cannot be further back than 90 days. | String | 2016-06-07 | Yes |
| fields |
A comma-separated list of columns for the report. At least one field is mandatory. See the complete list of available fields below. |
String | [see section 1.4] | Yes |
| timezone | The requested timezone – according to UTC. Default is UTC |
String | +8 | No |
2.3 Available Fields
The table below includes information about each of the available fields in the request.
| Parameter Name | Description |
| day | The date of the data in the report. Format is: ‘YYYY-MM-DD’ |
| hour | The hour of the data in the report. Breakdown by ‘hour’ is only available for the last 30 days and together with breakdown by ‘day’. |
| ads_requested | The total number of ads requested by the publisher |
| ads_served | The total number of recommended ads returned by YouAppi |
| impressions | The number of unique impressions |
| clicks | The number of clicks |
| installs | The number of installs |
| revenue | The publisher’s revenue, in $ |
| ctr | Click-Through Rate (clicks/impressions), in % |
| cvr | Conversion Rate (installs/clicks), in % |
| ecpm | Effective revenue per 1,000 impressions |
| country | Two-letter country code |
| ad_unit_type | image, video, RewardedVideo, InterstitialVideo, InterstitialAd |
| ad_unit_id | The placement name the publisher sent on the request |
| device_type | Smartphone or Tablet |
| os | Android or iOS |
| publisher_token | The publisher_token that was sent by the publisher |
| integration | The integration name (associated with the accesstoken). |
| video_starts | The number of video starts |
| video_first_quartiles | The number of video views that reached first quartiles |
| video_midpoints | The number of video views that reached midpoint |
| video_third_quartiles | The number of video views that reached third quartiles |
| video_completes | The number of completed views |
2.4 Sample Request
The following is an example of the format of the request:
https://reports.youappi.com/publisher?apiKey=1g2g3j4k-4adc-4b33-23e2-485b2r5yje8f&start=2017-06-01&end=2017-06-01&fields=day,impressions,clicks,installs,revenue,ctr,cvr,ecpm,country&timezone=-43. API Response
3.1 Response Format
The response of the API is in JSON format. YouAppi’s response looks like this:
{
"count":2,
"results":[
{
"day":"2017-06-01",
"impressions":20000,
"clicks":600,
"installs":30,
"revenue":150,
"ctr":3,
"cvr":5,
"ecpm":7.5,
"country":"us"
},
{
"day":"2017-06-01",
"impressions":30000,
"clicks":900,
"installs":45,
"revenue":240,
"ctr":3,
"cvr":5,
"ecpm":8,
"country":"ca"
}
]
}
3.2 Error messages
Errors are returned in the following format:
{
"errors":[
"Invalid start date: 01-06-2017. Expected format yyyy-MM-dd"
]
}
Possible errors include:
- Invalid start date: [DATE]. Expected format yyyy-MM-dd
- Invalid end date: [DATE]. Expected format yyyy-MM-dd
- Invalid date range. Start date is after the end date.
- Invalid date range. Date range is over 90 days limit.
- Invalid date range. Breakdown by hour is limited to 30 days. Please omit the ‘hour’ field or reduce the date range.
- Invalid field: [FIELD NAME]
- Breakdown of ‘hour’ only is not allowed. Add also the ‘day’ field.
- Unauthorized request apiKey: [API KEY]
- Number of rows exceeds 50,000. Please narrow the date range or reduce breakdowns.
For additional information and support please contact support@youappi.com.