Ranks show your standings in the app store, there are a two different ways to get that data from the API.
- Basic reports – show you ranks across selected countries and apps
- Snapshot reports let you see the full standings of a particular country and category.
Scope: All of the resources in this route require read access in the public scope (public:read).
Generating a ranks report
Request
GET /ranks/{product_ids}/{granularity}/{start_date}/{end_date}?countries={countries}&filter={filter}&tz={tz}&format={format}
Arguments
| Field | Type | Description |
|---|---|---|
| product_ids | Array | One or more product_ids to get ranks for. Separate multiple product_ids with a comma (,).
|
| granularity | String | Data granularity, either “hourly” or “daily”. |
| start_date | Date | Day to start the report on in format: yyyy-MM-dd. |
| end_date | Date | Day to end the report on in format: yyyy-MM-dd. |
| countries | Array | One or more countries to get ranks from. Separate multiple iso codes with a semicolon (;). If no country iso is specified ‘US’ will be used. Countries can be found here: /data/countries |
| tz | String | (user | utc | est) specifies which timezone to use, defaults to est |
| filter | Number | Limit results to ranks in the top N, with N being a number between 1 and 1,000. A filter value of 100 will only include records where the rank position is better than 100 (ex. 25). When blank this defaults to 400.
Not all stores/categories can go as deep as 1,000. |
| format | String | Output format: json or csv. Defaults to JSON. |
Response
This route returns a container with request metadata (start, end dates) and an inner containing the ranks for each series. A series represents a particular product’s movement through ranks over time with respect to a given country and category.
Container Representation:
| Field | Type | Description |
|---|---|---|
| start_date | Date | The start date of the report |
| end_date | Date | The end date of the report |
| dates | Array | Array of dates that are mapped against the series position/delta data below |
| data | Array | List of series entries(see below). Each series has a category, country, and product as well as the positions and deltas in array form that correspond to the above dates. |
Series Representation:
| Field | Type | Description |
|---|---|---|
| country | String | ISO code of the country this series is for. |
| category | Category | Representation of the category this series is for. |
| product_id | Number | The product that this series is for. |
| positions | List of rank positions (1-indexed) that map with the dates above | |
| deltas | List of rank changes that map with the dates above. The delta is always fromt the prior hour even if the granularity is daily |
Example Response
GET /ranks/41046955155/daily/2019-06-05/2019-06-07/?countries=gb,us
{
"start_date": "2017-06-05T00:00:00",
"end_date": "2017-06-07T00:00:00",
"dates": [
"2017-06-05T00:00:00",
"2017-06-06T00:00:00",
"2017-06-07T00:00:00"
],
"data": [
{
"country": "US",
"category": {
"store": "apple",
"store_id": 1,
"device": "handheld",
"device_id": 1,
"name": "Games/Family",
"subtype": "paid",
"id": 7009,
"parent_id": 6014
},
"product_id": 5923605,
"positions": [
186,
179,
null
],
"deltas": [
-3,
2,
null
]
},
. . .
}
Generating a ranks snapshot for a category
Request
GET /ranks/snapshots/{time}/{country}/{category}/{subcategory}/?top={top}
The Public Data API add-on is required for this route.
Arguments
| Field | Type | Description |
|---|---|---|
| time | string | “current” to get the most recent snapshot or a date with an hour that’s within the last 24 hours in format: yyyy-mm-ddTHH.
Important: Requests for dates/times not within the last 24 hours will result in a 404 response. If you need snapshots for earlier dates please contact us. |
| country | String | The iso code of the country you’d like to get a snapshot for. Countries can be found here: /data/countries |
| category | String | The category_id of the category to get a snapshot for. Categories can be found here: /data/categories |
| subcategory | String | The sub-category to get a snapshot for. Options: “free”, “paid”, “topgrossing”. |
| count | Number | Number of results to return between 1 – 1,000. This defaults to 400.
Not all stores/categories can go as deep as 1,000. |
| start | Number | Result index to start returning results from. Can be used with count to page through a larger resultset. |
Response
The response is a JSON object with the following properties:
| Field | Type | Description |
|---|---|---|
| category | Category | A representation of the category |
| country | string | The iso code of the country of the app store. The full name of the country is available in /data/countries. |
| timestamp | Date | The time that the snapshot was taken |
| page_count | Number | The number of results in this representation |
| page_start | Number | The index this page starts on. |
| total_count | Number | The total number of entries in this snapshot. |
| entries | Array | The top apps, in order |
Example Response
GET /ranks/snapshots/current/us/71/free?count=1000
{
"page_count": 10,
"page_start": 0,
"total_count": 400,
"country": "US",
"category": {
"store": "google_play",
"store_id": 2,
"device": "Handheld",
"device_id": 1,
"name": "Tools",
"subtype": "Free",
"id": 71
},
"timestamp": "2017-06-07T16:00:00",
"entries": [
{
"id": 5545649,
"name": "Brightest Flashlight Free™",
"developer": "GoldenShores Technologies, LLC",
"icon": "http://lh6.ggpht.com/oxdTH6PDCgkz-6TkodfJc6fK3-xFsz_voyqslO2blEbAP0pow8R32KlS4sTPWS4j3A",
"vendor_identifier": "goldenshorestechnologies.brightestflashlight.free",
"package_name": "goldenshorestechnologies.brightestflashlight.free",
"store_id": 2,
"store": "google_play",
"release_date": "2016-12-01T00:00:00-05:00",
"added_date": "2016-12-01T02:21:09-05:00",
"updated_date": "2017-06-04T03:00:00-04:00",
"version": "2.3.4",
"source": null,
"type": "app",
"devices": [
"Handheld"
],
"price": {
"currency": "USD",
"price": "0.00"
}
},
...
}