Reporting API Guide for Advertisers

43 views 12/02/2018 Ziv Sheffer 0

1. Objective

This document provides directions on how to access YouAppi’s reporting API for advertisers.

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/advertiser?

The table below contains the parameters that must be included in the API request.

2.2 Mandatory Parameters

Parameter Name Description Value Type Example
apiKey The apiKey is a unique access token that will be provided to the advertiser by YouAppi. String ab1c2de3-456f-78e9-h60d-2350f5fc722a
start The start date of the data in the report.
Allowed format is: ‘YYYY-MM-DD’.
String 2016-06-01
end The end date of the data in the report. Allowed format is: ‘YYYY-MM-DD’. This date cannot be further back than 90 days. String 2016-06-07
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 2.3]

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’.
impressions The number of impressions
clicks The number of clicks
installs The number of installs
spend The advertiser’s spend, in $
ctr Click-Through Rate (clicks/impressions), in %
cvr Conversion Rate (installs/clicks), in %
country Two-letter country code
campaign campaign id
device_type Smartphone or Tablet
os Android or iOS
publisher_id publisher id

2.4 Sample Request

https://reports.youappi.com/advertiser?apiKey=1g2g3j4k-4adc-4b33-23e2-485b2r5yje8f&start=2017-06-01&end=2017-06-01&fields=day,impressions,clicks,installs,spend,ctr,cvr,country

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,
         "spend":150,
         "ctr":3,
         "cvr":5,
         "country":"us"
      },
      {
         "day":"2017-06-01",
         "impressions":30000,
         "clicks":900,
         "installs":45,
         "spend":240,
         "ctr":3,
         "cvr":5,
         "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.