In addition to ranks and reviews we also track when and where your apps are featured in the app store. This resource lets you get a few different kinds of data.
- Summary reports let you know which countries, categories, and products you have featured.
- Full featured reports let you see all of the featured for a given product in a particular timespan.
- Counts reports count up how many features products are in the given time period.
- History reports show the full history of a product in a given featured category
Scope: All of the resources in this route require read access in the public scope (public:read).
Contents
Generating a featured summary report
Request
GET /featured/summary/{start_date}/{end_date}?products={products}
Arguments
- start_date
- (required) Day to start the report on in format: yyyy-MM-dd.
- end_date
- (required) Day to end the report on in format: yyyy-MM-dd.
- products
- One or more product_ids to get featured data for. Separate multiple product_ids with a semicolon (;). Defaults to all active products in the account
The Public Data API add-on is required to access data for products that are not owned by your account. Free accounts must use the Public Data API, even for products that are in their account.
One request requires five (5) partner credits.
Response
The response is in the form product_id mapped to the following leaf:
| product_id | Straight forward. The product’s id. |
| start | First date in in the given period that the product has a feature. |
| end | Last date in the period where the product has a feature. |
| countries | Distinct countries the product has been featured in |
| paths | List of paths that the product has been featured in. Each set of paths has multiple parts:
|
Example Response
// GET /featured/summary/2016-01-01/2017-01-01
{
"5923605": {
"product_id": 5923605,
"start": "2016-06-22T00:00:00",
"end": "2016-12-09T00:00:00",
"countries": [
"ID",
"SA",
"TW"
],
"paths": [
[
"apple",
"Unknown",
"Handheld",
"Paid",
"Games/Family",
"what's hot"
],
[
"apple",
"Unknown",
"Handheld",
"Paid",
"Games/Kids",
"what's hot"
],
[
"apple",
"Unknown",
"Tablet",
"Paid",
"Games/Family (iPad)",
"what's hot"
],
[
"apple",
"Unknown",
"Tablet",
"Paid",
"Games/Kids (iPad)",
"what's hot"
]
]
},
. . .
}
Generating a full featured report
Request
GET /featured/full/{product_id}/{start_date}/{end_date}?countries={countries}
The Public Data API add-on is required for this route.
Arguments
Response
The response is a JSON object with featured category IDs mapped to the following object:
| country | The iso code of the country of the app store. The full name of the country is available in /data/countries. |
| base_category | Representation of the category. See here for format: /data/categories |
| viewed_from | (handheld | tablet | desktop) If desktop this featured category was seen in iTunes or the Mac App Store, otherwise it was seen in the App Store on that device type. |
| crumbs | An array that represents the path between the base_category and where this featured page was actually seen. |
| start_date | when the app was fist seen in this featured category (given the requested time constraints) |
| end_date | when the app was last seen in this featured category (given the requested time constraints) |
| highest_position | The highest position attained in the time period |
| lowest_position | The lowest position attained in the time period |
| positions | List of the featured positions throughout the given time span. Each entry has a start, end, and position. |
Example Response
// GET /featured/full/5923605/2016-06-22/2016-07-22
{
"187899": {
"country": "AR",
"base_category": {
"store": "apple",
"store_id": 1,
"device": "Handheld",
"device_id": 1,
"name": "Games/Family",
"subtype": "Paid",
"id": 7009
},
"viewed_from": "Desktop",
"crumbs": [
"what's hot"
],
"start_date": "2016-06-27T00:00:00",
"end_date": "2016-06-27T00:00:00",
"highest_position": 56,
"lowest_position": 56,
"positions": [
{
"start": "2016-06-27T00:00:00",
"end": "2016-06-27T00:00:00",
"position": 56
}
]
},
. . .
}
Getting counts for features
This route shows how many featured pages a product is in for the given request parameters. It breaks down by time and granularity.
For instance if granularity is daily each entry will be a grouping of a day, and if granularity is weekly each entry will be a grouping of a week.
The entries are sorted and paged by date descending. So if you request 5 entries with min=today you’ll get the last 5 days.
Request
GET /featured/counts?end={end}&products={products}&count={count}&granularity={granularity}&show_empty={show_empty}
The Public Data API add-on is required for this route.
Arguments
- end
- (required) Day to end the report on in format: yyyy-MM-dd. Defaults to today
- products
- One or more product_ids to get featured data for. Separate multiple product_ids with a semicolon (;). Defaults to all account products
- count
- Max number of entries to show. Defaults to 5.
- granularity
- (daily | weekly) Whether to group by day or week. Defaults to weekly
- show_empty
- (true | false) Whether show empty entries. If this is true, this call will return the last count periods whether or not they have data. Defaults to false
Response
The response is a list of objects grouped by date range.
| date_range | Tuple(array) of start_date, end_date for the period. |
| products | list of objects with product_id and featured_count properties. |
Example Response
// GET /featured/counts/?end=2017-03-20&count=1&granularity=daily
// notice how this date was pushed back because this is date
// that has data before and closest to the given end date
[
{
"date_range": [
"2016-11-05",
"2016-11-05"
],
"products": [
{
"product_id": 6567539,
"featured_count": 1
}
]
}
]
// GET /featured/counts/?end=2016-03-20&count=1
// &granularity=daily&show_empty=true
// notice how this time the date is equal to 'today'
// and there is no data now that show_empty = true/
[
{
"date_range": [
"2016-03-20",
"2016-03-20"
],
"products": []
}
]
Getting full history for a category and product
Request
GET /featured/history/{product_id}/{featured_category_id}
The Public Data API add-on is required for this route.
Arguments
Response
The response is a JSON object with featured category ids mapped to the following object:
| time | Timestamp of entry |
| position | Position at that time |
Example Response
// GET /featured/history/5923605/187899
[
{
"time": "2016-06-27T00:00:00",
"position": 56
}
]