The /reports/sales resource provides comprehensive access to sales reports. 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, stores, or any combination thereof.
Scope: All of the resources in this route require read access in the private scope (private:read).
Contents
Getting “All Time” totals
A very common use case is to get all the data for an app and add it up for an “All time total”.
If you don’t provide start_date and end_date and aren’t using a group_by (for the routes that accept a group_by) that includes ‘dates’ you’ll get a sum of all the available data.
For some products, such as free apps from the Android Market, this will give complete “all time” data set, and not just for the data that’s been imported into the Appfigures account. It may not agree with actually summing up individual days because of inconsistencies in Google’s data.
Getting Simple Totals
Request
GET /reports/sales/?group_by={group_by}&start_date={start_date}&end_date=(end_date)&granularity={granularity}&products={product_ids}&countries={countries}&dataset={dataset}&include_inapps={include_inapps}&format={format}
Arguments
| Argument | Type | Description |
|---|---|---|
| start_date | Date | (yyyy-mm-dd) Date, inclusive, to start reporting from. If you specify a granularity other than daily this will be rounded down to the nearest period. default: a long, long time ago. |
| end_date | Date | (yyyy-mm-dd) Date, inclusive, to stop reporting. If you specify a granularity other than daily this will be rounded up to the nearest period. default: distant future. |
| group_by | List | One or more pivots separated by a comma (,). Available pivots: products, countries, dates, stores, and device. |
| granularity | Enum | (daily | weekly | monthly | yearly) How to group dates. This affects how start_date and end_date are rounded (they snap to lower and upper barriers of the type given by this parameter) default: daily Note: the daily and weekly granularities are limited to a maximum of 30 and 365 days per request respectively. |
| products | List | (productId | productId1, productId2, …) specific products to include in the response, default: all active products in account |
| countries | List | (isoCode | isoCode1;isoCode2;isoCodeN) Countries to limit the report to (can be taken from /data/countries, default: include all countries) |
| dataset | Enum | (none | financial ) If this is set to financial, use financial reports. This only applies to Apple products, default: none |
| devices | Enum | (handheld | tablet | desktop | tv) Filter results by device. Separate multiple devices with a comma. Watch is not currently supported. |
| include_inapps | Bool | (true | false) If set to true any products given in product_ids will have their children automatically selected as well. default: false) |
| format | Enum | Output format: JSON or CSV. Defaults to JSON. Note: When format=csv is given, complex fields will be serialized as ids or otherwise simplified representations to prevent excessive repetition. |
Response
| downloads | An int representing the total number of downloads. |
| net_downloads | An int representing the number of downloads – returns. |
| app_downloads | An int representing the number of downloads for the app, not including any in-app purchases (even if specified by ID). |
| re_downloads | An int representing the total number of downloads that were reinstalls or subsequent installs after an app was initially installed. |
| updates | An int representing the total number of updates. |
| revenue | A float representing the total revenue, after the store’s fee, in the user’s selected currency. |
| app_revenue | A float representing the total revenue from app sales (not including in-app purchases), after the store’s fee, in the user’s selected currency. |
| gross_revenue | A float representing the total revenue before the store’s fee, in the user’s selected currency. |
| gross_app_revenue | A float representing the total revenue from app sales (not including in-app purchases), before the store’s fee, in the user’s selected currency. |
| returns | An int representing the total number of returns. |
| app_returns | An int representing the total number of returns for apps, not including in-app purchases. |
| gifts | An int representing the number of times products in this report were gifted. |
| gift_redemptions | An int representing the number of times products in this report were gifted and then redeemed. |
| promos | An int representing the total number of promo codes used. |
| edu_downloads | An int representing the total number of educational downloads. |
| returns_amount | A float representing the amount of money refunded to customers, after the store’s fee, in the user’s selected currency. |
| app_returns_amount | A float representing the amount of money refunded to customers from app sales (not including in-app purchases), after the store’s fee, in the user’s selected currency. |
| gross_returns_amount | A float representing the amount of money refunded to customers, before the store’s fee, in the user’s selected currency. |
| gross_app_returns_amount | A float representing the amount of money refunded to customers from app sales (not including in-app purchases), before the store’s fee, in the user’s selected currency. |
| edu_revenue | A float representing the revenue from sales to educational institutions (usually discounted), after the store’s fee, in the user’s selected currency. |
| gross_edu_revenue | A float representing the revenue from sales to educational institutions (usually discounted), before the store’s fee, in the user’s selected currency. |
| uninstalls | The number of times the selected apps were removed from a device they were installed on.
Note: This metric is only available for Apple and Google Play. |
| business_downloads | An int representing the number of downloads received through Apple’s Volume Purchase for Business program. |
| business_revenue | A float representing revenue from downloads generated through Apple’s Volume Purchase for Business program, not including the store’s fee. |
| gross_business_revenue | A float representing revenue from downloads generated through Apple’s Volume Purchase for Business program, including the store’s fee. |
| standard_downloads | An int representing downloads generated via the store and not through any purchasing program. This equals downloads – edu_downloads – business_downloads. |
| standard_revenue | A float representing revenue, not including the store’s fee, generated via the store and not through any purchasing program. This equals revenue – edu_revenue – business_revenue. |
| gross_standard_revenue | A float representing revenue, including the store’s fee, generated via the store and not through any purchasing program. This equals gross_revenue – gross_edu_revenue – gross_business_revenue. |
| pre_orders | An int representing the number of orders for a pre-released app. Pre-orders do not count towards downloads until the app is released, at which point the downloads (and subsequent revenue, if applicable) will count towards downloads and revenue separately.. |
Example
// GET /reports/sales/
{
"downloads": 155299,
"re_downloads": 133092
"updates": 91156,
"returns": 56,
"net_downloads": 155243,
"promos": 2,
"revenue": "26188.63",
"gross_revenue": "37412.32",
"returns_amount": "609.21",
"edu_downloads": 54,
"gifts": 36,
"gift_redemptions": 0,
"edu_revenue": "0.00"
"gross_returns_amount": "0.00",
"gross_edu_revenue": "0.00",
"uninstalls": 1811,
}
Generating a Report By Product, Country, or Date
Request
GET /reports/sales/?group_by={group_by}&start_date={start_date}&end_date=(end_date)&granularity={granularity}&products={product_ids}&countries={countries}&dataset={dataset}&include_inapps={include_inapps}&format={format}
Arguments
| Argument | Type | Description |
|---|---|---|
| start_date | Date | (yyyy-mm-dd) Date, inclusive, to start reporting from. If you specify a granularity other than daily this will be rounded down to the nearest period. default: a long, long time ago. |
| end_date | Date | (yyyy-mm-dd) Date, inclusive, to stop reporting. If you specify a granularity other than daily this will be rounded up to the nearest period. default: distant future. |
| group_by | List | One or more pivots separated by a comma (,). Available pivots: products, countries, dates, stores, and device. |
| granularity | Enum | (daily | weekly | monthly | yearly) How to group dates. This affects how start_date and end_date are rounded (they snap to lower and upper barriers of the type given by this parameter) default: daily Note: the daily and weekly granularities are limited to a maximum of 30 and 365 days per request respectively. |
| products | List | (productId | productId1, productId2, …) specific products to include in the response, default: all active products in account |
| countries | List | (isoCode | isoCode1;isoCode2;isoCodeN) Countries to limit the report to (can be taken from /data/countries, default: include all countries) |
| dataset | Enum | (none | financial ) If this is set to financial, use financial reports. This only applies to Apple products, default: none |
| devices | Enum | (handheld | tablet | desktop | tv) Filter results by device. Separate multiple devices with a comma. Watch is not currently supported. |
| include_inapps | Bool | (true | false) If set to true any products given in product_ids will have their children automatically selected as well. default: false) |
| format | Enum | Output format: JSON or CSV. Defaults to JSON. Note: When format=csv is given, complex fields will be serialized as ids or otherwise simplified representations to prevent excessive repetition. |
Response
The response depends on the specified group_by given. No matter which group_by, the deepest part of the representation is the following leaf:
| downloads | An int representing the total number of downloads. |
| re_downloads | An int representing the total number of downloads that were reinstalls or subsequent installs after an app was initially installed. |
| net_downloads | An int representing the number of downloads – returns. |
| updates | An int representing the total number of updates. |
| revenue | A float representing the total revenue in the user’s selected currency. |
| gross_revenue | A float representing the total revenue before the store’s fee, in the user’s selected currency. |
| returns | An int representing the total number of returns. |
| gifts | An int representing the number of times products in this report were gifted. |
| gift_redemptions | An int representing the number of times products in this report were gifted and then redeemed. |
| promos | An int representing the total number of promo codes used. |
| edu_downloads | An int representing the total number of educational downloads. |
| returns_amount | A float representing the amount of money refunded to customers, after the store’s fee, in the user’s selected currency. |
| gross_returns_amount | A float representing the amount of money refunded to customers, before the store’s fee, in the user’s selected currency. |
| edu_revenue | A float representing the revenue from sales to educational institutions (usually discounted), after the store’s fee, in the user’s selected currency. |
| gross_edu_revenue | A float representing the revenue from sales to educational institutions (usually discounted), before the store’s fee, in the user’s selected currency. |
| uninstalls | An int representing the number of times the selected apps were uninstalled from a user’s device.
Note: This metric is only available for Android apps sold through Google Play. |
| date (optional) | A string (yyyy-MM-dd) representing the date of the leaf. This is only returned when the `group_by` includes `date`. |
| product_id (optional) | The product’s ID. This is only returned when the `group_by` includes `product`. |
| iso (optional) | The ISO code for the current leaf’s country. This is only returned when the `group_by` includes `country`. |
| country (optional) | The leaf’s country name. This is only returned when the `group_by` includes `country`. |
| product (optional) | A full representation of the leaf’s product. This is only returned when the `group_by` includes `product`. |
Example Response For Sales By Date Report
// GET /reports/sales/?group_by=dates
{
"2017-05-28": {
"downloads": 233,
"re_downloads": 150,
"updates": 2,
"returns": 0,
"net_downloads": 233,
"promos": 0,
"revenue": "246.97",
"gross_revenue": "341.21",
"returns_amount": "0",
"edu_downloads": 0,
"gifts": 0,
"gift_redemptions": 0,
"edu_revenue": "0.00"
"gross_returns_amount": "0.00",
"gross_edu_revenue": "0.00",
"uninstalls": 11,
"date": "2017-05-28"
},
. . .
"2017-06-07": {
"downloads": 64,
"re_downloads": 45,
"updates": 0,
"returns": 0,
"net_downloads": 64,
"promos": 0,
"revenue": "99.48",
"gross_revenue": "142.48",
"returns_amount": "0",
"edu_downloads": 0,
"gifts": 0,
"gift_redemptions": 0,
"edu_revenue": "0.00"
"gross_returns_amount": "0.00",
"gross_edu_revenue": "0.00",
"uninstalls": 8,
"date": "2017-06-07"
}
}
Example For Sales By Country Report
// GET /reports/sales/?group_by=countries
{
"AE": {
"downloads": 840,
"re_downloads": 700,
"updates": 271,
"returns": 0,
"net_downloads": 840,
"promos": 0,
"revenue": "268.28",
"gross_revenue": "418.11",
"returns_amount": "0",
"edu_downloads": 0,
"gifts": 0,
"gift_redemptions": 0,
"edu_revenue": "0.00"
"gross_returns_amount": "0.00",
"gross_edu_revenue": "0.00",
"uninstalls": 91,
"country": "UAE",
"iso": "AE"
},
"AG": {
"downloads": 4,
"re_downloads": 4,
"updates": 1,
"returns": 1,
"net_downloads": 4,
"promos": 0,
"revenue": "2.30",
"gross_revenue": "3.20",
"returns_amount": "0.99",
"edu_downloads": 0,
"gifts": 0,
"gift_redemptions": 0,
"edu_revenue": "0.00"
"gross_returns_amount": "0.00",
"gross_edu_revenue": "0.00",
"uninstalls": 0,
"country": "Antigua And Barbuda",
"iso": "AG"
},
. . .
}
Example For Sales By Product Report
// GET /reports/sales/?group_by=products&start=2017-05-20&end=2017-05-25
{
"12345": {
"downloads": 45,
"re_downloads": 30,
"updates": 0,
"returns": 45,
"net_downloads": 0,
"promos": 0,
"revenue": "0.64",
"gross_revenue": "0.99",
"returns_amount": "501.22",
"edu_downloads": 0,
"gifts": 0,
"gift_redemptions": 0,
"edu_revenue": "0.00"
"gross_returns_amount": "0.00",
"gross_edu_revenue": "0.00",
"uninstalls": 4,
"product_id": 12345,
"product": {
"id": 12345,
"name": "Awesome app",
"developer": "Jeff",
"icon": "https://lh3.ggpht.com/jeffs-icon",
"vendor_identifier": "com.jeff.mva",
"package_name": "com.jeff.mva",
"store_id": 2,
"store": "google_play",
"release_date": "2016-12-01T00:00:00",
"added_date": "2016-12-01T20:22:05",
"updated_date": "2017-06-04T03:00:00",
"version": "4.0.2",
"source": {
"external_account_id": 77,
"added_timestamp": "2012-02-27T19:09:36",
"active": true,
"hidden": false,
"type": "own"
},
"type": "unknown",
"devices": [
"Handheld"
],
"children": [],
"features": [],
"parent_id": null
}
},
. . .
}
Example For Sales By Product and Date Report
Response: structure of products mapped to dates mapped to sales information
// GET /reports/sales?group_by=products,dates&start_date=-30
{
"12345": {
"2020-09-03": {
"date": "2016-11-24",
"country": null,
"iso": null,
"product_id": 12345,
"downloads": 11,
"re_downloads": 10,
"net_downloads": 11,
"updates": 0,
"revenue": "0.00",
"gross_revenue": "0.00",
"returns_amount": "0",
"returns": 0,
"gift_redemptions": 0,
"promos": 0,
"edu_revenue": "0.00"
"gross_returns_amount": "0.00",
"gross_edu_revenue": "0.00",
"uninstalls": 0
},
...
},
"123456": {
"2020-09-03": {
"date": "2016-11-24",
"product_id": 123456,
"downloads": 28,
"re_downloads": 30,
"net_downloads": 29,
"updates": 6,
"revenue": "19.02",
"revenue": "27.20",
"returns_amount": "0",
"returns": 1,
"gift_redemptions": 0,
"promos": 0,
"edu_revenue": "0.00"
"gross_returns_amount": "0.00",
"gross_edu_revenue": "0.00",
"uninstalls": 2
},
...
}
}
Example For Sales By Date and Product Report
Response: structure of dates mapped to products mapped to sales information
// GET /reports/sales?group_by=dates,products?start_date=-30
{
"2020-09-03": {
"12345": {
"date": "2016-11-24",
"product_id": 12345,
"downloads": 11,
"re_downloads": 15,
"net_downloads": 11,
"updates": 0,
"revenue": "0.00",
"gross_revenue": "0.00",
"returns_amount": "0",
"returns": 0,
"gift_redemptions": 0,
"promos": 0,
"edu_revenue": "0.00"
"gross_returns_amount": "0.00",
"gross_edu_revenue": "0.00",
"uninstalls": 0,
},
...
},
"2020-09-04": {
"294956": {
"date": "2016-11-25",
"product_id": 123456,
"downloads": 10,
"re_downloads": 9,
"net_downloads": 10,
"updates": 1,
"revenue": "0.00",
"gross_revenue": "0.00",
"returns_amount": "0",
"returns": 0,
"gift_redemptions": 0,
"promos": 0,
"edu_revenue": "0.00"
"gross_returns_amount": "0.00",
"gross_edu_revenue": "0.00",
"uninstalls": 0,
},
...
},
...
}