Master API - customized aggregate data API

Master API is the infrastructure upon which AppsFlyer's pivot table is built. 

Master API structure

All Master API links have different parts, mandatory or optional, which are detailed in the following. These include: Master API base endpoint, mandatory parameters, groupings, KPIs, calculated KPIs, filters, time frame, and localization fields.

1. Master API base endpoint

Every call to the Master Report API must begin with the following endpoint:

https://hq.appsflyer.com/export/master_report/v4?

All the dynamic parameters in any master API URL follow the '?' character.

2. Mandatory parameters

All Master API URLs have the same general format:

https://hq.appsflyer.com/export/master_report/v4?api_token=[api_token]
&app_id=[app_id]&from=[from_date]&to=[to_date]&groupings=[list]&kpis=[list]

The following table describes the mandatory parameters:

3. Available groupings

These dimensions are used for collecting the data into groups to allow easier and more accurate examination of the information. You can find descriptions of these fields here.

4. KPIs

KPIs are the metrics used for gaining an insight into the behavior of your app. The KPI's are grouped by type in the tabs that follow. 

5. Calculated KPIs

In addition, to the KPIs described previously, you can add calculated KPIs to your master API reports. This enables you to have your own calculated reports included in your Master API reports.

You can insert any number of built-in KPIs in the calculated KPI formulas.

Standard arithmetic operators are supported: addition (+) encoded as %2b, subtraction (-), multiplication (*), division (/) encoded as %2f.

Calculated KPI field names must start with "calculated_kpi_", followed by any valid string, such as, "calculated_kpi_purchaserate".

Examples:

First three days combined retention

kpis=installs,loyal_users_rate&calculated_kpi_3days_retention=retention_day_1%2Bretention_day_2%2Bretention_day_3

Average revenue per impression

kpis=installs&calculated_kpi_rev_per_impression=revenue%2Fimpression

Cohort day 7 ROI

kpis=installs,roi,arpu_ltv,cost,revenue&calculated_kpi_roi_day_7=(cohort_day_7_total_revenue_per_user-average_ecpi)%2Faverage_ecpi

6. Filters

7. Time frame fields

• Daily
• Weekly

8. Localization

You can set local currency and timezone for your apps on the app settings page. The same localization preferences can also be reflected on master API reports using the parameters below.

• If all apps have the same configuration (whether by default or not), the common configuration is used. Otherwise, (different configurations per app), UTC±00:00 and USD are used.
• Localization (time zone and currency change) is not supported in Weekly Retention KPIs
• If the preferred time zone was changed in the dashboard within the requested time range, the generated report contains values starting from the last change only.

Response format

All the received fields in the response are according to V5 format.

By default, the response data is received in CSV file format. If you prefer to get the data in JSON format add &format=json to the URL.

Request examples

To save you time, here is a list of Master API URLs you can cut and paste to get different reports. Before using a URL make sure to:

1. Replace the app name from com.greatapp to your android or iOS app's ID
2. Replace [TOKEN] with your account's API token
3. Replace the from and to dates to your preferred date range
4. Change the KPIs according to your preferences
5. If your app has a different timezone or currency than the default UTC±00:00 and USD add &timezone=preferred and/or &currency=preferred to the query URL

https://hq.appsflyer.com/export/master_report/v4?api_token=[api_token]
&app_id=com.greatapp&from=[from_date]&to=[to_date]&pid=facebook
&groupings=pid,c,af_adset_id,af_ad_id
&kpis=installs,clicks,impressions,sessions,loyal_users,cost,revenue,arpu_ltv,roi

https://hq.appsflyer.com/export/master_report/v4?api_token=[api_token]
&app_id=com.greatapp,id123456789&from=[from_date]&to=[to_date]&pid=googleadwords_int
&groupings=pid,c,af_adset_id,af_ad_id
&kpis=installs,sessions,loyal_users,cost,revenue,arpu_ltv,roi

https://hq.appsflyer.com/export/master_report/v4?api_token=[api_token]
&app_id=all&from=[from_date]&to=[to_date]&groupings=geo,pid,c&kpis=
installs,clicks,impressions,sessions,loyal_users,cost,revenue,arpu_ltv,
roi&geo=us,ca	

https://hq.appsflyer.com/export/master_report/v4?api_token=[api_token]
&app_id=com.greatapp&from=[from_date]&to=[to_date]&groupings=af_keywords
&kpis=roi,arpu_ltv,average_ecpi,installs,loyal_users_rate,cost,revenue

https://hq.appsflyer.com/export/master_report/v4?api_token=[api_token]
&app_id=com.greatapp,id123456789&from=[from_date]&to=[to_date]&groupings=af_prt,pid,c&kpis=installs,
loyal_users_rate

https://hq.appsflyer.com/export/master_report/v4?api_token=[api_token]
&app_id=com.greatapp&from=[from_date]&to=[to_date]&groupings=af_siteid&pid=affiliates
&kpis=installs,loyal_users_rate,arpu_ltv,retention_day_1,retention_rate_day_1,
retention_day_7,retention_rate_day_7,retention_day_15,retention_rate_day_15,
retention_day_30,retention_rate_day_30

https://hq.appsflyer.com/export/master_report/v4?api_token=[api_token]
&app_id=com.greatapp,id123456789&from=[from_date]&to=[to_date]&groupings=attributed_touch_type
&kpis=installs,sessions,loyal_users_rate,arpu_ltv

https://hq.appsflyer.com/export/master_report/v4?api_token=[api_token]
&app_id=com.greatapp&from=[from_date]&to=[to_date]&groupings=is_primary&kpis=revenue

https://hq.appsflyer.com/export/master_report/v4?api_token=[api_token]
&app_id=all&from=[from_date]&to=[to_date]&groupings=pid,c
&kpis=installs,loyal_users_rate,retention_day_1,retention_rate_day_1,
retention_day_7,retention_rate_day_7,retention_day_15,retention_rate_day_15,
retention_day_22,retention_rate_day_22,retention_day_30,retention_rate_day_30

Limitations

Cost data

Cost data, including eCPI, may not always be available. This depends on whether the network supports cost data, the type of the network, i.e. using AppsFlyer links or self-reporting, and the requested dimensions.

In general, all sources, including owned media, which use AppsFlyer's links and have the cost parameter on the links, fully support cost data, regardless of the requested dimensions. Self-reporting networks, with their own API, usually support cost data with only some of the available dimensions.

For example, Facebook doesn’t support grouping by Geo and Channel at the same time (grouping by either of them separately is supported).

For the full list of ad networks supporting cost data click here.