Using Pull API aggregate data

At a glance: Use URIs to get aggregate reports in CSV files.

PullAPIAverage_us-en.png

 Are you looking for Pull API raw data?

Pull API raw data

Pull API aggregate data characteristics

  • Reports return as CSV files.
  • Data freshness rates are the same as the equivalent report on the Export Data page.
  • The filter by options are the same as in the Export Data page being: Media source, date range, in-app event name. 
  • Additional capabilities in Pull API are:
    • Ability to filter by attribution touch type
    • Selectable timezone 
  • Pull API is suited to use by team members and BI developers;
    • Team members get reports by pasting URIs in their browser. The URI templates are available in the Dashboard. 
    • BI developers get reports by embedding the URIs in scripts. 

Example URI template TemplateURL_us-en.jpg

Category  UA Retargeting* Protect360
Partners (media source)

Partners by date

Daily

Geo

Geo by date

* For retargeting reports, add the &reattr=true to the URI. 

Aggregate performance reports available via Pull API

 Related reading:

Terminology

Term Description
Pull API

Solution for downloading CSV reports using URIs.

API call or call 

Sending the URI to AppsFlyer by pasting it in the browser address bar or by using scripts.

URI
  • Uniform resource identifier sometimes similar to a web address (URL) containing the report specification.
  • Template URIs are available on the API page in the Dashboard.

Guide for team members

About URI templates

  • URI templates available in the dashboard are populated with the app ID and report type.
  • They have place holders for the API token and from/to dates which you need to edit.
  • The portion of the URI to the right of the question mark (?) contains parameters. Each parameter begins with an ampersand (&). Parameters are used to set filters, specify additional fields to be included, currency, and timezone. For example, in aggregate reports to limit (filter by) a specific media source, use the media_source parameter: &media_source=facebook
  • To get a better understanding of Pull API, complete the tutorial that follows.

Getting your first Pull API report tutorial

Before you begin:
  •  Ask the admin to provide you with the Pull API token available in the dashboard.

To download a report from the dashboard: 

  1. Go to Integration > API access.
    The API access page opens. PullAPIPartnersReport_us-en.jpg
  2. Select a report type. For example, Performance reportsPartners daily report. 
    The URI template displays. 
  3. Copy the URI by clicking on it.
  4. Open a new tab in your browser, paste the URI.
  5. Edit the URI:
    1. Replace the token placeholder with the Pull API token provided by the admin.
      Example: Replace the token placeholder so that &api_token=12345678-1234-1234-1234-123456789012 Note! There are no spaces or other punctuation. 
    2. Replace the from/to placeholders with dates.
      Example: &from=2020-01-20&to=2020-01-31 Note! There are no spaces. Don't delete the &. 
  6. Click <Enter> to send the API call. 
    The report downloads.
    Addtional parameters can be set to customize reports, for example, select a specific media source, to return retargeting data, etc. The section that follows contains the list of parameters available. 

Aggregate data Pull API parameters

Aggregate report URI and parameters

Aggregate URI mandatory parameters 
Parameter Description
api_token API Authorization token. In example calls, this is shown as: <API TOKEN HERE>. 
from
  • The date range consists of a fromand to parameter. The range is the LTV (install) date range.
  • Format: yyyy-mm-dd, 
  • Example: 2010-01-01 or 2010-01-01
to End date. As for from
Aggregate data optional filtering and display parameters excluding Protect360 reports
Parameter Description
media_source

Use to limit (filter) to a specific media source.

  • Example:media_source=facebook
 attribution_touch_type

Set this parameter as shown in the example to get view-through attribution (VTA) KPIs. 

Example: attribution_touch_type=impression

currency

Currency of revenue and cost

Aggregate Pull API reports always use the app-specific currency. 

reattr

Get retargeting conversions data.

  • [Default] If false, user acquisition data (UA) campaigns returns.
  • If true, retargeting conversion returns.
  • Example:reattr=true
timezone

[Default] Data returns using UTC.

  • Template URIs are populated with the timezone parameter set to the app-specific time zone. 
  • [Default] If the parameter is not sent, data returns using UTC.
  • If you send timezone=[Joda-Time], data returns using the app-specific time zone.

Notes about selecting timezones

  • Joda-Time time zone format takes into account daylight saving time.
  • The Joda-Time value must be identical to the value in the app settings page. For example, if the timezone setting is Paris, the timezone value in the Pull API URL should be timezone=Europe%2fParis.
  • Pulling data in the selected time zone is only available from the date when the time zone setting was made. Any data prior to the date of the change uses UTC as the timezone. 

Google Ads filtered report

https://hq.appsflyer.com/export/com.greatapp/partners_report/v5?api_token=xxxx
&from=2018-04-09&to=2018-05-09&media_source=googleadwords_int

Facebook filtered report

https://hq.appsflyer.com/export/com.greatapp/partners_report/v5?api_token=xxxx
&from=2018-04-09&to=2018-05-09&media_source=facebook
Optional parameters for Protect360 reports
parameter Description
URI
  • Ge the Protect360 URI from the dashboard.
  • Modify the URI as described here. 
 pid

To filter the report by a specific media source use the pidparameter. For example, to get the data of abc_net, pid=abc_net.

timezone

Selects the timezone used to return data.

If timezone is not sent, data is returned using UTC.

Templates including the timezone parameter. 

Example: timezone=preferred: Use to get data using the app-specific timezone.

KPIs

 Protect360 parameters are the same in Pull API and Master API. 

View-through attribution (VTA) KPIs

  • To get the VTA KPIs, add the parameter attribution_touch_type=impression to the Pull API aggregate report URI as detailed in the example.
  • You can use the parameter with any of the aggregate reports available. Just copy the URI from the user interface, and append the parameter.
  • You can also add the &media_source parameter to limit the report to a specific media source as depicted in the example that follows.
  • Some VTA KPIs, like clicks, impressions, and cost APIs, don't have values associated with them and display the value N/A instead. 
Example Example URI
VTA only  https://hq.appsflyer.com/export/{app_id}/partners_report/v5?api_token={API token}&from=yyyy-mm-dd&to=yyyy-mm-dd&attribution_touch_type=impression

VTA and media source

https://hq.appsflyer.com/export/{app_id}/partners_report/v5?api_token={API token}&from=yyyy-mm-dd&to=yyyy-mm-dd&attribution_touch_type=impression&media_source=example_ad_network

Pull API for developers

Principles of implementation

Prerequisite:

Familiarize yourself with the Pull API guide for team members.

Consider:

  • For each report type available, there is a template URI in the dashboard.
  • You modify the template to get the data you need. For example, by setting date ranges and filter by parameters.
  • The parameters for raw data and aggregate data reports differ and are detailed in the report sections.
Pull API basics
Path

https://hq.appsflyer.com/export/app_id/report_type/v5

Path parameters

app_id

  • App identifier as found in AppsFlyer.
  • Insert the app ID exactly as found in AppsFlyer.
  • Prefix iOS apps with id

report_type 

  • Defines the type of report. The list of reports and the associated URIs are in the dashboard. Go to Integration > API access. 
HTTP method

GET

Mandatory query parameters
Parameter Description
Example URI

GET 'https://hq.appsflyer.com/export/app_id/installs_report/v5? from=2020-01-01?&to=2020-01-10&api_token=api_token&currency=preferred

api_token

api_token: Pull API token for authentication

Other parameters

Parameters differ depending 

 Example

URI call example includes additional parameters: 

https://hq.appsflyer.com/export/example.app.com/installs_report/v5?
        api_token={Account owner API key should be used}&from=yyyy-mm-dd
&to=yyyy-mm-dd&additional_fields=keyword_id,store_reinstall,
deeplink_url,oaid,install_app_store,contributor1_match_type,
contributor2_match_type,contributor3_match_type,match_type

Example scripts

Integrate Pull API into scripts to retrieve data.

  • As needed, edit the scripts in terms of report type, date range, and filters. 
  • These examples use the install report.
JavaNode JSPythonC#PHP
import okhttp3.*;

import java.io.BufferedWriter;
import java.io.FileWriter;

import java.util.concurrent.TimeUnit;

public class PullApi {
  public static void main(String[] args){

    String appID = "<APP_ID>";
    String reportType = "<REPORT_TYPE>";
    String apiToken = "<API_TOKEN>";
    String from = "<FROM_DATE>";
    String to = "<TO_DATE>";
    String requestUrl = "https://hq.appsflyer.com/export/" + appID + "/" + reportType + "/v5?api_token=" + apiToken + "&from=" + from + "&to=" + to;

    OkHttpClient client = new OkHttpClient.Builder()
        .connectTimeout(30, TimeUnit.SECONDS)
        .readTimeout(30, TimeUnit.SECONDS)

        .build();

    Request request = new Request.Builder()
        .url(requestUrl)
        .addHeader("Accept", "text/csv")
        .build();

    try {
      Response response = client.newCall(request).execute();

      if(response.code() != 200) {
        if(response.code() == 404) {
          System.out.println("There is a problem with the request URL. Please make sure it is correct");
        }
        else {
          assert response.body() != null;
          System.out.println("There was a problem retrieving the data: " + response.body().string());
        }
      } else {
        assert response.body() != null;
        String data = response.body().string();
        BufferedWriter writer;

        writer = new BufferedWriter(new FileWriter(appID + "-" + reportType + "-" + from + "-to-" + to + ".csv"));
        writer.write("");
        writer.write(data);
        writer.close();
      }
      System.exit(0);
    } catch (Exception e) {
      e.printStackTrace();
      System.exit(1);
    }
  }
}

Additional information

Differences between Pull API V4 and V5. 

Raw data: API V4 is still available for use. No changes are made to file formats and headers.

Aggregate data (V5):

In V5.0, the following additional fields are provided when the media_source=facebook:

  • Campaign ID
  • Adset name
  • Adset Id
  • Ad (Adgroup) Name
  • Ad (Adgroup) Id

Traits and limitations

Trait
Trait Status Comments 
Ad network access   
Agency access  
Agency transparency  
App-specific currency  
App-specific timezone  
Data freshness Realtime  
Historical data  
Non-organic data  
Organic data  
Rate limitation

API limitations for aggregate data and raw data

Size limitations Yes
  • API calls return a max. of 200K rows.
  • If a report has exactly 200K rows, then assume rows are missing.
  • Make multiple API calls, using from/to parameters that include the time of day.  
Team member access

Only the admin can get a Pull API token.

API error codes and troubleshooting

Error codes and solutions
Status Code Symptom/message Solution
OK 200 Empty CSV file
  • addtional_fieldsappears more than once in the URI
  • Ensure that both from and to dates have the format yyyy-mm-dd
OK

200

 

No API token found in the URI

Bad request

400

Raw Reports historical lookback is limited to 90 days.

Use to and from to limit the date range to 3 months or less.

Bad request

400

Your API calls limit has been reached for report type

-
Unauthorized

401

Supplied API token is invalid 

Ask the admin for the current token
Unauthorized

401

Account may be suspended.

Log in to the dashboard and check the account status. 

Not found

404

AppsFlyer 404 error message page displays

  • Ensure that the app id is correct. iOS apps must start with id
  • The token doesn't match the app. Are you using the correct token? 
Was this article helpful?