Featured

We track when and where your apps are featured in the app stores, along with ranks and reviews. This resource gives you four kinds of featured data:

Summary reports show which of your products are featured, and in which countries and categories.
Full featured reports show every feature for a product in a time span.
Counts reports count how many features each product has in a time period.
History reports show a product’s full history in one featured category.

Generating a Featured Summary Report

Request

GET /featured/summary/{start_date}/{end_date}?products={products}

Arguments

Argument	Description
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.

Each request uses five partner credits.

Response

The response maps each product_id to this object:

Field	Description
product_id	The product’s ID.
start	The first date in the period that the product has a feature.
end	The last date in the period that the product has a feature.
countries	Distinct countries the product has been featured in.
paths	List of paths the product has been featured in. Each path has multiple parts: 1. store 2. viewed_from (the device the feature is visible from; Unknown means iTunes) 3. device (the kind of device the feature is for) 4. subcategory (Free/Paid/TopGrossing) 5. category 6. Any further items are progressively deeper featured categories.

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}

Arguments

Argument	Description
product_id	(required) The product_id to get featured data for.
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.
countries	One or more ISO codes to filter the results by. The full name of each country is available in /data/countries. Defaults to all countries.

Response

The response is a JSON object with featured category IDs mapped to the following object:

Field	Description
country	The ISO code of the app store’s country. The full name of the country is available in /data/countries.
base_category	Representation of the category. See /data/categories for the format.
viewed_from	(handheld \| tablet \| desktop) Desktop means we saw this featured category in iTunes or the Mac App Store. Otherwise, we saw it in the App Store on that device type.
crumbs	An array of the path between the base_category and where we saw this featured page.
start_date	When we first saw the app in this featured category, within the requested dates.
end_date	When we last saw the app in this featured category, within the requested dates.
highest_position	The highest position in the time period.
lowest_position	The lowest position in the time period.
positions	List of featured positions in the 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 counts the featured pages a product is in. Entries are grouped by granularity: with daily, each entry covers a day; with weekly, each covers a week. Entries are sorted and paged by date, newest first. 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}

Arguments

Argument	Description
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 products in the account.
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 to show empty entries. If true, this call returns 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.

Field	Description
date_range	Tuple (array) of start_date and 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}

Arguments

Argument	Description
product_id	(required) The product_id to get featured data for.
featured_category_id	(required) ID from /featured/full/{product_id}.

Response

The response is a JSON object with featured category IDs mapped to the following object:

Field	Description
time	Timestamp of the entry.
position	Position at that time.

Example Response

// GET /featured/history/5923605/187899

[
  {
    "time": "2016-06-27T00:00:00",
    "position": 56
  }
]