Featured

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).

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 account products


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.

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:
  1. store
  2. viewed_from (what device the feature is visible from– Unknown is iTunes)
  3. device (what kind of device the feature is for)
  4. subcategory (Free/Paid/TopGrossing)
  5. category
  6. any other items in this list are progressively deeper featured categories

Example Response

// GET /featured/summary/2010-01-01/2013-01-01

{
  "5923605": {
    "product_id": 5923605,
    "start": "2011-06-22T00:00:00",
    "end": "2011-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

product_id
(required) 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
Filter the results to countries given by the iso code or iso codes in this parameter. The full name of the 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:

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/2011-06-22/2011-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": "2011-06-27T00:00:00",
    "end_date": "2011-06-27T00:00:00",
    "highest_position": 56,
    "lowest_position": 56,
    "positions": [
      {
        "start": "2011-06-27T00:00:00",
        "end": "2011-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=2013-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": [
      "2012-11-05",
      "2012-11-05"
    ],
    "products": [
      {
        "product_id": 6567539,
        "featured_count": 1
      }
    ]
  }
]
// GET /featured/counts/?end=2013-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": [
      "2013-03-20",
      "2013-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

product_id
(required) product_id to get featured data for.


featured_category_id
(required) ID retrieved from /featured/full/{product_id}


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": "2011-06-27T00:00:00",
    "position": 56
  }
]