keepa.AsyncKeepa.best_sellers_query#

async AsyncKeepa.best_sellers_query(category: str, rank_avg_range: Literal[0, 30, 90, 180] = 0, variations: bool = False, sublist: bool = False, domain: str | Domain = 'US', wait: bool = True, typed: bool = False) → list[str | None] | BestSellers#

Retrieve an ASIN list of the most popular products.

This is based on sales in a specific category or product group. See “search_for_categories” for information on how to get a category.

Root category lists (e.g. “Home & Kitchen”) or product group lists contain up to 100,000 ASINs.

Sub-category lists (e.g. “Home Entertainment Furniture”) contain up to 3,000 ASINs. As we only have access to the product’s primary sales rank and not the ones of all categories it is listed in, the sub-category lists are created by us based on the product’s primary sales rank and do not reflect the actual ordering on Amazon.

Lists are ordered, starting with the best selling product.

Lists are updated daily. If a product does not have an accessible sales rank it will not be included in the lists. This in particular affects many products in the Clothing and Sports & Outdoors categories.

We can not correctly identify the sales rank reference category in all cases, so some products may be misplaced.

See the keepa documentation at Request Best Sellers for additional details.

Parameters:
categorystr

The category node id of the category you want to request the best sellers list for. You can find category node ids via the category search Keepa.search_for_categories().

rank_avg_rangeint, default: 0

Optionally specify to retrieve a best seller list based on a sales rank average instead of the current sales rank. Valid values:

  • 0: Use current rank

  • 30: 30-day average

  • 90: 90-day average

  • 180: 180-day average

variationsbool, default: False

Restrict list entries to a single variation for items with multiple variations. The variation returned will be the one with the highest monthly units sold (if that data point is available). When False (default), do not include variations. When True, return all variations.

By default we return one variation per parent. If the variations share the same sales rank, the representative is the variation with the highest monthly units sold. If monthly sold data is missing or tied, the representative falls back to randomly picked one.

sublistbool, default: False

By default (False), the best seller list for sub-categories is created based on the product’s primary sales rank, if available. To request a best seller list based on the sub-category sales rank (classification rank), set this parameter to True. Note that not all products have a primary sales rank or a sub-category sales rank and not all sub-category levels have sales ranks.

domainstr | keepa.Domain, default: ‘US’

A valid Amazon domain. See keepa.Domain.

waitbool, default: True

Wait for available tokens before querying the keepa backend.

typedbool, default: False

When True, return the full keepa.models.backend.BestSellers Pydantic model instead of only its ASIN list.

Returns:
list[str | None] | BestSellers

List of best seller ASINs by default and the full keepa.models.backend.BestSellers model when typed=True.

Examples

Query for the best sellers among the "movies" category.

>>> import keepa
>>> key = "<REAL_KEEPA_KEY>"
>>> api = keepa.Keepa(key)
>>> categories = api.search_for_categories("movies")
>>> category = list(categories.items())[0][0]
>>> asins = api.best_sellers_query(category)
>>> asins
['B0BF3P5XZS',
 'B08JQN5VDT',
 'B09SP8JPPK',
 '0999296345',
 'B07HPG684T',
 '1984825577',
...

Query for the best sellers among the "movies" category using the asynchronous keepa interface.

>>> import asyncio
>>> import keepa
>>> async def main():
...     key = "<REAL_KEEPA_KEY>"
...     api = await keepa.AsyncKeepa.create(key)
...     categories = await api.search_for_categories("movies")
...     category = list(categories.items())[0][0]
...     return await api.best_sellers_query(category)
...
>>> asins = asyncio.run(main())
>>> asins
['B0BF3P5XZS',
 'B08JQN5VDT',
 'B09SP8JPPK',
 '0999296345',
 'B07HPG684T',
 '1984825577',
...