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 Parameters

Parameter Name	Description	Value Type	Example	Mandatory
apiKey	The apiKey is a unique access token that will be provided to the advertiser 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 2.3]	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’.
impressions	The number of impressions
clicks	The number of clicks
installs	The number of installs
conversions	The number of conversions (CPA)
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
campaign_name	campaign name
promoted_item	App or Brand being promoted
device_type	Smartphone or Tablet
os	Android or iOS
publisher_id	publisher id
cpa	cost per event
bundle_id	publisher’s bundle 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&timezone=-5

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.

Advertisers

Reporting API Guide for Advertisers