keepa.Keepa.deals#

Keepa.deals(deal_parms: dict[str, Any] | DealRequest, domain: str | Domain = 'US', wait: bool = True, typed: bool = False) → dict[str, Any] | DealResponse#

Query the Keepa API for product deals.

You can find products that recently changed and match your search criteria. A single request will return a maximum of 150 deals. Try out the deals page to first get accustomed to the options: https://keepa.com/#!deals

For more details please visit: https://keepa.com/#!discuss/t/browsing-deals/338

Parameters:
deal_parmsdict, DealRequest

Dictionary or generated keepa.models.backend.DealRequest containing one or more of the following keys:

  • "page": int

  • "domainId": int

  • "excludeCategories": list

  • "includeCategories": list

  • "priceTypes": list

  • "deltaRange": list

  • "deltaPercentRange": list

  • "deltaLastRange": list

  • "salesRankRange": list

  • "currentRange": list

  • "minRating": int

  • "isLowest": bool

  • "isLowestOffer": bool

  • "isOutOfStock": bool

  • "titleSearch": String

  • "isRangeEnabled": bool

  • "isFilterEnabled": bool

  • "hasReviews": bool

  • "filterErotic": bool

  • "sortType": int

  • "dateRange": int

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 a keepa.models.backend.DealResponse Pydantic model instead of a dictionary.

Returns:
dict[str, Any] | DealResponse

Dictionary containing the deals, or a keepa.models.backend.DealResponse when typed=True. The response includes the following fields:

  • 'dr' - Ordered array of all deal objects matching your query.

  • 'categoryIds' - Contains all root categoryIds of the matched deal products.

  • 'categoryNames' - Contains all root category names of the matched deal products.

  • 'categoryCount' - Contains how many deal products in the respective root category are found.

Examples

Return deals from category 16310101 using the synchronous keepa.Keepa class

>>> import keepa
>>> key = "<REAL_KEEPA_KEY>"
>>> api = keepa.Keepa(key)
>>> deal_parms = {
...     "page": 0,
...     "domainId": 1,
...     "excludeCategories": [1064954, 11091801],
...     "includeCategories": [16310101],
... }
>>> deals = api.deals(deal_parms)

Get the title of the first deal.

>>> deals["dr"][0]["title"]
'Orange Cream Rooibos, Tea Bags - Vanilla, Orange | Caffeine-Free,
Antioxidant-rich, Hot & Iced | The Spice Hut, First Sip Of Tea'

Conduct the same query with the asynchronous keepa.AsyncKeepa class.

>>> import asyncio
>>> import keepa
>>> deal_parms = {
...     "page": 0,
...     "domainId": 1,
...     "excludeCategories": [1064954, 11091801],
...     "includeCategories": [16310101],
... }
>>> async def main():
...     key = "<REAL_KEEPA_KEY>"
...     api = await keepa.AsyncKeepa.create(key)
...     return await api.deals(deal_parms)
...
>>> deals = asyncio.run(main())
>>> deals["dr"][0]["asin"]
'B0BF3P5XZS'