Usage

The /reports/usage resource provides comprehensive access to usage reports for your apps. Reports can be generated in a variety of formats.

The main resource gives you a single combined result across the filter parameters you select. The result can be limited by dates, products, countries and some other parameters.

Using the group_by parameter, you can get a report broken down by products, countries, dates, networks, or any combination thereof.

Scope: All of the resources in this route require read access in the private scope (private:read).

Available Metrics

Unlike other routes in the API, the response object in this route will contain different metrics for different networks.

See the table below for details:

	Apple	Flurry	Google Analytics
active_users			●
avg_optin_rate	●
crashes	●	●	●
daily_active_devices	●	●
daily_new_devices		●
median_session_length		●
monthly_active_devices	●
paying_users	●
app_store_views	●
unique_app_store_views	●
impressions	●
unique_impressions	●
screen_views			●
screen_views_per_user			●
sessions	●	●	●
session_duration		●	●
sessions_per_device	●	●
sessions_per_user			●
unique_screen_views			●

Getting Totals

Request

GET /reports/usage/?group_by=network&start_date={start_date}&end_date=(end_date)&products={product_ids}&countries={countries}&format={format}&networks={networks}

Arguments

Argument	Type	Description
start_date	Date	Date (yyyy-mm-dd), inclusive, to start reporting from. Default: the beginning of time.
end_date	Date	Date (yyyy-mm-dd), inclusive, to stop reporting. Default: today.
group_by	List	One or more pivots separated by a comma (,). Available pivots: network, product, country, and date.
products	List	One or more products to include in the response separated by a comma (,). Default: all active products in account.
countries	List	One or more countries to limit the report to separated by a comma (,). See /data/countries for all available countries. Default: include all countries.
format	String	Output format: JSON or CSV. Defaults to JSON.

Response

The response will depend on whether you requested data for multiple networks or a single one. See metrics by network table above, or examples below.

Example

// GET /reports/usage?group_by=network

{
  "apple:analytics": {
    "sessions": 3589097152,
    "avg_optin_rate": "0.43",
    ...
    "storefront": "apple:analytics",
    "store": "apple"
  },
  "flurry_analytics": {
    "sessions": 1540311105,
    ...
    "storefront": "flurry_analytics",
    "store": "flurry_analytics"
  },
  "google_analytics": {
    "sessions": 1251311105,
    ...
    "storefront": "google_analytics",
    "store": "google_analytics"
  }
}

Generating a Report By Product, Country, or Date

Request

GET /reports/usage/?group_by={group_by}&start_date={start_date}&end_date={end_date}&products={product_ids}&countries={countries}&format={format}

Arguments

Argument	Type	Description
start_date	Date	Date (yyyy-mm-dd), inclusive, to start reporting from. Default: the beginning of time.
end_date	Date	Date (yyyy-mm-dd), inclusive, to stop reporting. Default: today.
group_by	List	One or more pivots separated by a comma (,). Available pivots: network, product, country, and date.
products	List	One or more products to include in the response separated by a comma (,). Default: all active products in account.
countries	List	One or more countries to limit the report to separated by a comma (,). See /data/countries for all available countries. Default: include all countries.
format	String	Output format: JSON or CSV. Defaults to JSON.

group_by=network is required. Additional group_by options can also be specified, but network is required. Omitting networks will result in a 400 response.

Response

The response depends on the specified group_by given. No matter which group_by, the deepest part of the representation is a leaf containing a representation with the metrics detailed in the table above.

Example For Usage By Country from Google Analytics

// GET /reports/usage/?group_by=countries&networks=google_analytics

{
  "AU": {
    "crashes": 5,
    "sessions": 1121,
    "session_duration": "53911.00",
    "active_users": 192,
    "screen_views": 2443,
    "unique_screen_views": 1311,
    "sessions_per_user": "1.32",
    "screen_views_per_user": "4.82",
    "iso": "AU",
    "country": "Australia"
  },
  "US": {
      "crashes": 110,
      "sessions": 1345394,
      "session_duration": "1272666.00",
      "active_users": 96912,
      "screen_views": 5122347,
      "unique_screen_views": 361239,
      "sessions_per_user": "1.44",
      "screen_views_per_user": "5.29",
      "storefront": "google_analytics",
      "store": "google_analytics",
      "iso": "US",
      "country": "United States"
    },
    ...
}

Example For Usage By network, Date, and Product

// GET /reports/usage/?group_by=networks,dates,products

{
  "apple:analytics": {
    "2017-10-01": {
      "100000000000001": {
        "sessions": 109275,
        "avg_optin_rate": "0.32",
        ...
        "storefront": "apple:analytics",
        "store": "apple",
        "date": "2017-10-02",
        "product_id": 100000000000001
      },
      "100000000000002": {
        ...
      }
    }
    "2017-10-02": {
      ...
    },
  },
  "google_analytics": {
    "2017-10-01": {
      ...
    }
  },
  ...
}