keepa.Keepa.query#

Keepa.query(items: str | Sequence[str], stats: int | None = None, domain: str | Domain = 'US', history: bool = True, offers: int | None = None, update: int | None = None, to_datetime: bool = True, rating: bool = False, out_of_stock_as_nan: bool = True, stock: bool = False, product_code_is_asin: bool = True, progress_bar: bool = True, buybox: bool = False, wait: bool = True, days: int | None = None, only_live_offers: bool | None = None, raw: bool = False, videos: bool = False, aplus: bool = False, typed: bool = False, extra_params: dict[str, Any] | None = None) → list[dict[str, Any]] | list[Product] | list[Response]#

Perform a product query of a list, array, or single ASIN.

Returns a list of product data with one entry for each product.

Parameters:
itemsstr, Sequence[str]

A list, array, or single asin, UPC, EAN, or ISBN-13 identifying a product. ASINs should be 10 characters and match a product on Amazon. Items not matching Amazon product or duplicate Items will return no data. When using non-ASIN items, set product_code_is_asin to False.

statsint or date, optional

No extra token cost. If specified the product object will have a stats field with quick access to current prices, min/max prices and the weighted mean values. If the offers parameter was used it will also provide stock counts and buy box information.

You can provide the stats parameter in two forms:

Last x days (positive integer value): calculates the stats of the last x days, where x is the value of the stats parameter. Interval: You can provide a date range for the stats calculation. You can specify the range via two timestamps (unix epoch time milliseconds) or two date strings (ISO8601, with or without time in UTC).

domainstr | keepa.Domain, default: ‘US’

A valid Amazon domain. See keepa.Domain.

historybool, optional

When set to True includes the price, sales, and offer history of a product. Set to False to reduce request time if data is not required. Default True

offersint, optional

Adds available offers to product data. Default 0. Must be between 20 and 100. Enabling this also enables the "buyBoxUsedHistory".

updateint, optional

If data is older than the input integer, keepa will update their database and return live data. If set to 0 (live data), request may cost an additional token. Default (None) will not update.

to_datetimebool, default: True

When True casts the time values of the product data (e.g. "AMAZON_TIME") to datetime.datetime. For example datetime.datetime(2025, 10, 24, 10, 40). When False, the values are represented as numpy "<M8[m]". This has no effect on pandas dataframes (e.g. "df_AMAZON").

ratingbool, default: False

When set to to True, includes the existing RATING and COUNT_REVIEWS history of the csv field.

out_of_stock_as_nanbool, default: True

When True, prices are NAN when price category is out of stock. When False, prices are -0.01.

stockbool, default: False

Can only be used if the offers parameter is also True. If True, the stock will be collected for all retrieved live offers. Note: We can only determine stock up 10 qty. Stock retrieval takes additional time, expect the request to take longer. Existing stock history will be included whether or not the stock parameter is used.

product_code_is_asinbool, default: True

The type of product code you are requesting. True when product code is an ASIN, an Amazon standard identification number, or ‘code’, for UPC, EAN, or ISBN-13 codes.

progress_barbool, default: True

Display a progress bar using tqdm.

buyboxbool, optional

Additional token cost: 2 per product). When true the product and statistics object will include all available buy box related data:

  • current price, price history, and statistical values

  • buyBoxSellerIdHistory

  • all buy box fields in the statistics object

The buybox parameter does not trigger a fresh data collection. If the offers parameter is used the buybox parameter is ignored, as the offers parameter also provides access to all buy box related data. To access the statistics object the stats parameter is required.

waitbool, default: True

Wait for available tokens before querying the keepa backend.

only_live_offersbool, optional

If set to True, the product object will only include live marketplace offers (when used in combination with the offers parameter). If you do not need historical offers use this to have them removed from the response. This can improve processing time and considerably decrease the size of the response.

daysint, optional

Any positive integer value. If specified and has positive value X the product object will limit all historical data to the recent X days. This includes the csv, buyBoxSellerIdHistory, salesRanks, offers and offers.offerCSV fields. If you do not need old historical data use this to have it removed from the response. This can improve processing time and considerably decrease the size of the response. The parameter does not use calendar days - so 1 day equals the last 24 hours. The oldest data point of each field may have a date value which is out of the specified range. This means the value of the field has not changed since that date and is still active.

rawbool, default; False

When True, return the raw request response. This is only available in the non-async class.

videosbool, default: False

Token Cost: No extra token cost

If True, the videos metadata will be provided when available. Using this parameter does not trigger an update to the videos data; it only gives access to our existing data if available. If you need up-to-date data, you have to use the offers parameter.

aplusbool, default: False

Token Cost: No extra token cost

If set to True the A+ content will be provided when available. Using this parameter does not trigger an update to the A+ content; it only gives access to our existing data if available. If you need up-to-date data, you have to use the offers parameter.

typedbool, default: False

When True, return products as keepa.models.backend.Product Pydantic models instead of dictionaries. Extra backend fields are preserved on the model. Cannot be combined with raw=True.

extra_paramsdict[str, Any], optional

Dictionary of parameters that are not specifically called out in the API. For example, a new parameter might be added to Request.java and not yet supported in this function. For example, extra_params={‘rental’: 1}.

Returns:
list

List of products when raw=False. By default, each product is a dictionary. The keys of each item may vary, so see the keys within each product for further details.

With history=True, products include a data attribute or key containing parsed history arrays. For the available fields see the notes section.

When raw=True, a list of unparsed responses are returned as requests.Response.

When typed=True, each product is returned as a permissive Pydantic model generated from the pinned Keepa backend schema. Use attribute access for known fields and model_dump(exclude_none=True, by_alias=True) to convert a typed response back to backend-compatible field names.

See: https://keepa.com/#!discuss/t/product-object/116

Notes

The following are some of the fields a product dictionary. For a full list and description, please see: product-object

AMAZON

Amazon price history

NEW

Marketplace/3rd party New price history - Amazon is considered to be part of the marketplace as well, so if Amazon has the overall lowest new (!) price, the marketplace new price in the corresponding time interval will be identical to the Amazon price (except if there is only one marketplace offer). Shipping and Handling costs not included!

USED

Marketplace/3rd party Used price history

SALES

Sales Rank history. Not every product has a Sales Rank.

LISTPRICE

List Price history

COLLECTIBLE

Collectible Price history

REFURBISHED

Refurbished Price history

NEW_FBM_SHIPPING

3rd party (not including Amazon) New price history including shipping costs, only fulfilled by merchant (FBM).

LIGHTNING_DEAL

3rd party (not including Amazon) New price history including shipping costs, only fulfilled by merchant (FBM).

WAREHOUSE

Amazon Warehouse Deals price history. Mostly of used condition, rarely new.

NEW_FBA

Price history of the lowest 3rd party (not including Amazon/Warehouse) New offer that is fulfilled by Amazon

COUNT_NEW

New offer count history

COUNT_USED

Used offer count history

COUNT_REFURBISHED

Refurbished offer count history

COUNT_COLLECTIBLE

Collectible offer count history

RATING

The product’s rating history. A rating is an integer from 0 to 50 (e.g. 45 = 4.5 stars)

COUNT_REVIEWS

The product’s review count history.

USED_NEW_SHIPPING

“Used - Like New” price history including shipping costs.

USED_VERY_GOOD_SHIPPING

“Used - Very Good” price history including shipping costs.

USED_GOOD_SHIPPING

“Used - Good” price history including shipping costs.

USED_ACCEPTABLE_SHIPPING

“Used - Acceptable” price history including shipping costs.

COLLECTIBLE_NEW_SHIPPING

“Collectible - Like New” price history including shipping costs.

COLLECTIBLE_VERY_GOOD_SHIPPING

“Collectible - Very Good” price history including shipping costs.

COLLECTIBLE_GOOD_SHIPPING

“Collectible - Good” price history including shipping costs.

COLLECTIBLE_ACCEPTABLE_SHIPPING

“Collectible - Acceptable” price history including shipping costs.

REFURBISHED_SHIPPING

Refurbished price history including shipping costs.

TRADE_IN

The trade in price history. Amazon trade-in is not available for every locale.

BUY_BOX_SHIPPING

The price history of the buy box. If no offer qualified for the buy box the price has the value -1. Including shipping costs. The buybox parameter must be True for this field to be in the data.

Examples

Query for product with ASIN 'B0088PUEPK' using the synchronous keepa interface.

>>> import keepa
>>> key = "<REAL_KEEPA_KEY>"
>>> api = keepa.Keepa(key)
>>> response = api.query("B0088PUEPK")
>>> response[0]["title"]
'Western Digital 1TB WD Blue PC Internal Hard Drive HDD - 7200 RPM,
SATA 6 Gb/s, 64 MB Cache, 3.5" - WD10EZEX'

Query for product with ASIN 'B0088PUEPK' using the asynchronous keepa interface.

>>> import asyncio
>>> import keepa
>>> async def main():
...     key = "<REAL_KEEPA_KEY>"
...     api = await keepa.AsyncKeepa.create(key)
...     return await api.query("B0088PUEPK")
...
>>> response = asyncio.run(main())
>>> response[0]["title"]
'Western Digital 1TB WD Blue PC Internal Hard Drive HDD - 7200 RPM,
SATA 6 Gb/s, 64 MB Cache, 3.5" - WD10EZEX'

Load in product offers and convert the buy box data into a pandas.DataFrame.

>>> import keepa
>>> key = "<REAL_KEEPA_KEY>"
>>> api = keepa.Keepa(key)
>>> response = api.query("B0088PUEPK", offers=20)
>>> product = response[0]
>>> buybox_info = product["buyBoxUsedHistory"]
>>> df = keepa.process_used_buybox(buybox_info)
               datetime         user_id         condition  isFBA
0   2022-11-02 16:46:00  A1QUAC68EAM09F   Used - Like New   True
1   2022-11-13 10:36:00  A18WXU4I7YR6UA  Used - Very Good  False
2   2022-11-15 23:50:00   AYUGEV9WZ4X5O   Used - Like New  False
3   2022-11-17 06:16:00  A18WXU4I7YR6UA  Used - Very Good  False
4   2022-11-17 10:56:00   AYUGEV9WZ4X5O   Used - Like New  False
..                  ...             ...               ...    ...
115 2023-10-23 10:00:00   AYUGEV9WZ4X5O   Used - Like New  False
116 2023-10-25 21:14:00  A1U9HDFCZO1A84   Used - Like New  False
117 2023-10-26 04:08:00   AYUGEV9WZ4X5O   Used - Like New  False
118 2023-10-27 08:14:00  A1U9HDFCZO1A84   Used - Like New  False
119 2023-10-27 12:34:00   AYUGEV9WZ4X5O   Used - Like New  False

Query a video with the “videos” metadata.

>>> response = api.query("B00UFMKSDW", history=False, videos=True)
>>> product = response[0]
>>> "videos" in product
True