Reporting API Guide for Partners

1583 views 2019-12-26 Ofer Garnett 0

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=-4

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