Keepa

https://keepaapi.readthedocs.io/en/stable
Admin
Keepa is a Python client library that interfaces with the Keepa API to query Amazon product...
Tokens:26,708
Snippets:358
Trust Score:8.3
Update:2 months ago
Show doc for...
Tokens:
Raw
### Install Keepa Client

Source: https://keepaapi.readthedocs.io/en/stable/index.html

Install the package using pip.

```bash
pip install keepa
```

--------------------------------

### Initialize and Query Asynchronous Keepa Client

Source: https://keepaapi.readthedocs.io/en/stable/product_query.html

Setup and usage of the asynchronous Keepa client to fetch product data.

```python
async_api = await keepa.AsyncKeepa.create("<REAL_KEEPA_KEY>")
products = await async_api.query("B0088PUEPK")
```

--------------------------------

### Initialize Synchronous Keepa Client

Source: https://keepaapi.readthedocs.io/en/stable/product_query.html

Basic setup for the synchronous Keepa API client using an access key.

```python
import keepa

api = keepa.Keepa("<REAL_KEEPA_KEY>")
```

--------------------------------

### Configure Notification Channels

Source: https://keepaapi.readthedocs.io/en/stable/api/backend/models/keepa.models.backend.Tracking.html

Example showing how to enable specific notification channels using a boolean array indexed by the NotificationType enum.

```java
boolean[] notificationType = new boolean[Tracking.NotificationType.values.length];
notificationType[Tracking.NotificationType.API.ordinal()] = true;
```

--------------------------------

### Initialize and Query AsyncKeepa

Source: https://keepaapi.readthedocs.io/en/stable/async_client.html

Demonstrates how to instantiate the asynchronous client and perform a basic product query.

```python
import keepa

api = await keepa.AsyncKeepa.create("<REAL_KEEPA_KEY>")
products = await api.query("B0088PUEPK")
```

--------------------------------

### Initialize and Configure ProductParams

Source: https://keepaapi.readthedocs.io/en/stable/api/types/keepa.ProductParams.html

Demonstrates creating a ProductParams instance and setting attributes, or initializing with keyword arguments.

```python
>>> import keepa
>>> product_params = keepa.ProductParams()
>>> product_params.author = "J. R. R. Tolkien"
```

```python
>>> product_params = keepa.ProductParams(author="J. R. R. Tolkien")
```

--------------------------------

### Query products by author using AsyncKeepa

Source: https://keepaapi.readthedocs.io/en/stable/api/async/keepa.AsyncKeepa.html

Demonstrates how to use the product_finder method to search for books by a specific author asynchronously.

```python
>>> import asyncio
>>> import keepa
>>> product_parms = {"author": "jim butcher"}
>>> async def main():
...     key = "<REAL_KEEPA_KEY>"
...     api = await keepa.AsyncKeepa.create(key)
...     return await api.product_finder(product_parms)
...
>>> asins = asyncio.run(main())
>>> asins
['B000HRMAR2',
 '0578799790',
 'B07PW1SVHM',
...
 'B003MXM744',
 '0133235750',
 'B01MXXLJPZ']
```

--------------------------------

### Query product details by ASIN using AsyncKeepa

Source: https://keepaapi.readthedocs.io/en/stable/api/async/keepa.AsyncKeepa.html

Demonstrates how to retrieve product information for a specific ASIN using the query method.

```python
>>> 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'
```

--------------------------------

### AsyncKeepa.create()

Source: https://keepaapi.readthedocs.io/en/stable/api/async/keepa.AsyncKeepa.create.html

Initializes a new instance of the AsyncKeepa client.

```APIDOC
## AsyncKeepa.create(accesskey, timeout=10.0)

### Description
Creates an asynchronous Keepa client instance without making an initial API request.

### Signature
`async classmethod AsyncKeepa.create(accesskey: str, timeout: float = 10.0) -> AsyncKeepa`

### Parameters
- **accesskey** (str) - Required - The API access key for authentication.
- **timeout** (float) - Optional - The timeout duration in seconds. Defaults to 10.0.
```

--------------------------------

### Asynchronous Client Implementation

Source: https://keepaapi.readthedocs.io/en/stable/backend_models.html

Shows how to initialize the asynchronous Keepa client and perform a product query.

```python
import asyncio

async def main():
    api = await keepa.AsyncKeepa.create("<REAL_KEEPA_KEY>")
    products = await api.query("B0088PUEPK", typed=True)
    return products[0].title

title = asyncio.run(main())
```

--------------------------------

### Query products with synchronous Keepa

Source: https://keepaapi.readthedocs.io/en/stable/api/async/keepa.AsyncKeepa.product_finder.html

Demonstrates querying the first 100 products by author with sorting using the synchronous Keepa class.

```python
>>> import keepa
>>> api = keepa.Keepa("<ENTER_ACTUAL_KEY_HERE>")
>>> product_parms = {
...     "author": "jim butcher",
...     "sort": [["current_SALES", "asc"]],
... }
>>> asins = api.product_finder(product_parms, n_products=100)
>>> asins
['B000HRMAR2',
 '0578799790',
 'B07PW1SVHM',
...
 'B003MXM744',
 '0133235750',
 'B01MXXLJPZ']
```

```python
>>> product_parms = keepa.ProductParams(
...     author="jim butcher",
...     sort=[["current_SALES", "asc"]],
... )
>>> asins = api.product_finder(product_parms, n_products=100)
```

--------------------------------

### Query product with synchronous and asynchronous interfaces

Source: https://keepaapi.readthedocs.io/en/stable/api/async/keepa.AsyncKeepa.query.html

Demonstrates how to query product data using both the standard synchronous Keepa interface and the asynchronous AsyncKeepa interface.

```python
>>> 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'
```

```python
>>> 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'
```

--------------------------------

### keepa.Keepa.__init__

Source: https://keepaapi.readthedocs.io/en/stable/api/sync/keepa.Keepa.html

Initializes the Keepa API client with the provided access key and configuration settings.

```APIDOC
## keepa.Keepa(accesskey, timeout=10.0, logging_level='DEBUG', check_key=False)

### Description
Initializes the Keepa API client. This object is required to perform any subsequent queries to the Keepa backend.

### Parameters
- **accesskey** (str) - Required - 64 character access key string.
- **timeout** (float) - Optional - Default 10.0. Timeout in seconds for server responses.
- **logging_level** (str) - Optional - Default 'DEBUG'. Logging level (DEBUG, INFO, WARNING, ERROR, CRITICAL).
- **check_key** (bool) - Optional - Default False. Whether to validate the key and update token count on initialization.
```

--------------------------------

### AsyncKeepa.product_finder

Source: https://keepaapi.readthedocs.io/en/stable/api/async/keepa.AsyncKeepa.html

Queries the Keepa product database based on specific criteria.

```APIDOC
## AsyncKeepa.product_finder(product_parms, domain=None)

### Description
Finds products matching the provided search criteria.

### Parameters
- **product_parms** (dict) - Required - Dictionary containing search parameters (e.g., author, category).
```

--------------------------------

### AsyncKeepa.create

Source: https://keepaapi.readthedocs.io/en/stable/api/async/keepa.AsyncKeepa.html

Initializes an asynchronous Keepa client instance.

```APIDOC
## AsyncKeepa.create(accesskey, timeout=10.0)

### Description
Creates an asynchronous Keepa client instance using the provided access key.

### Parameters
- **accesskey** (str) - Required - 64 character access key string.
- **timeout** (float) - Optional - Default timeout in seconds for requests.
```

--------------------------------

### Fetch full product data from ASINs

Source: https://keepaapi.readthedocs.io/en/stable/product_finder.html

Passes the ASINs retrieved from product_finder to the query method to obtain full product details.

```python
asins = api.product_finder(parameters)
products = api.query(asins, history=False)
```

--------------------------------

### Query Product Data

Source: https://keepaapi.readthedocs.io/en/stable/api/sync/keepa.Keepa.html

Retrieve product information for a list of ASINs.

```python
>>> products = api.query(["0439064872", "1426208081"])
```

--------------------------------

### AsyncKeepa.query

Source: https://keepaapi.readthedocs.io/en/stable/api/async/keepa.AsyncKeepa.html

Performs a product query for a list or single ASIN.

```APIDOC
## AsyncKeepa.query(items, stats=None, domain=None, history=None)

### Description
Retrieves product information for a list, array, or single ASIN.

### Parameters
- **items** (str/list) - Required - The ASIN or list of ASINs to query.
```

--------------------------------

### AsyncKeepa.seller_query(seller_id, domain='US', to_datetime=True, storefront=False, update=None, wait=True, typed=False)

Source: https://keepaapi.readthedocs.io/en/stable/api/async/keepa.AsyncKeepa.seller_query.html

Retrieves seller information for a given seller ID or list of IDs. Token cost is 1 per requested seller.

```APIDOC
## AsyncKeepa.seller_query

### Description
Receive seller information for a given seller id or ids. If a seller is not found, no tokens will be consumed.

### Parameters
- **seller_id** (str | list[str]) - Required - The seller id of the merchant. For batch requests, you may submit a list of 100 seller_ids.
- **domain** (str | keepa.Domain) - Optional - A valid Amazon domain. Default: 'US'.
- **to_datetime** (bool) - Optional - When True, casts time values to datetime.datetime. Default: True.
- **storefront** (bool) - Optional - If True, the seller object will contain additional information about items the seller is listing. Default: False.
- **update** (int) - Optional - Positive integer. If the last live data collection is older than update hours, force a new collection.
- **wait** (bool) - Optional - Wait for available tokens before querying the keepa backend. Default: True.
- **typed** (bool) - Optional - When True, return sellers as keepa.models.backend.Seller Pydantic models. Default: False.

### Returns
- **dict[str, dict[str, Any]] | dict[str, Seller]** - One entry per input seller_id.

### Example
```python
>>> import keepa
>>> key = "<REAL_KEEPA_KEY>"
>>> api = keepa.Keepa(key)
>>> seller_info = api.seller_query("A2L77EE7U53NWQ", "US")
>>> seller_info["A2L77EE7U53NWQ"]["sellerName"]
'Amazon Warehouse'
```
```

--------------------------------

### Query Product Data

Source: https://keepaapi.readthedocs.io/en/stable/index.html

Retrieve product information using an ASIN. Dictionary responses are the default, while typed=True provides Pydantic models.

```python
import keepa

api = keepa.Keepa("<REAL_KEEPA_KEY>")
products = api.query("B0088PUEPK", history=True, stats=90)
product = products[0]

print(product["title"])
print(product["stats_parsed"]["current"].get("AMAZON"))
```

```python
typed_product = api.query("B0088PUEPK", typed=True)[0]
print(typed_product.title)
print(typed_product.asin)
```

--------------------------------

### api.query(asin, history=False, stats=None, typed=False)

Source: https://keepaapi.readthedocs.io/en/stable/index.html

Fetches product data for one or more ASINs. Returns product dictionaries or Pydantic models if typed=True.

```APIDOC
## api.query(asin, history=False, stats=None, typed=False)

### Description
Retrieves product information for specified ASINs. Supports optional history data and statistical analysis.

### Parameters
- **asin** (str or list) - Required - The ASIN or list of ASINs to query.
- **history** (bool) - Optional - Whether to include price history data.
- **stats** (int) - Optional - The number of days for statistical analysis.
- **typed** (bool) - Optional - If True, returns Pydantic models instead of dictionaries.
```

--------------------------------

### Explore Catalog and Categories

Source: https://keepaapi.readthedocs.io/en/stable/index.html

Perform discovery using product finder parameters or category-based queries.

```python
params = keepa.ProductParams(
    author="jim butcher",
    current_SALES_lte=50_000,
    sort=[["current_SALES", "asc"]],
    perPage=100,
)
asins = api.product_finder(params)
products = api.query(asins[:10], history=False, typed=True)
```

```python
categories = api.search_for_categories("office chairs", typed=True)
category_id = next(iter(categories))
best_sellers = api.best_sellers_query(category_id, typed=True)
print(best_sellers.asinList[:10])
```

--------------------------------

### AsyncKeepa.query(asin, **kwargs)

Source: https://keepaapi.readthedocs.io/en/stable/api/async/keepa.AsyncKeepa.query.html

Queries the Keepa API for product information using an ASIN. Supports various parameters to control the data returned, such as offers, history, and metadata.

```APIDOC
## AsyncKeepa.query(asin, **kwargs)

### Description
Retrieves product data from Keepa for a given ASIN. This method is part of the asynchronous interface and returns product details including price history and metadata.

### Method
Python Method

### Parameters
- **asin** (string) - Required - The Amazon Standard Identification Number (ASIN) of the product.
- **offers** (int) - Optional - Number of offers to load.
- **history** (bool) - Optional - Whether to include price history data.
- **videos** (bool) - Optional - Whether to include video metadata.
- **buybox** (bool) - Optional - Whether to include buy box data.

### Example
```python
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())
```
```

--------------------------------

### Query deals with synchronous Keepa class

Source: https://keepaapi.readthedocs.io/en/stable/api/async/keepa.AsyncKeepa.deals.html

Demonstrates how to fetch deals using the synchronous Keepa client with specific category filters.

```python
>>> 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)
```

--------------------------------

### Perform a basic product search

Source: https://keepaapi.readthedocs.io/en/stable/product_finder.html

Uses a dictionary to define search parameters, including author, sorting, and results per page.

```python
parameters = {
    "author": "jim butcher",
    "sort": [["current_SALES", "asc"]],
    "perPage": 100,
}
asins = api.product_finder(parameters)
```

--------------------------------

### Query a single product

Source: https://keepaapi.readthedocs.io/en/stable/product_data.html

Retrieve data for a single product using its ASIN or ISBN-10. The result is always returned as a list.

```python
products = api.query("059035342X", history=False)
product = products[0]
print(product["asin"], product.get("title"))
```

--------------------------------

### api.query(asin, typed=True)

Source: https://keepaapi.readthedocs.io/en/stable/backend_models.html

Queries product information by ASIN.

```APIDOC
## api.query(asin, typed=True)

### Description
Fetches product details for a given ASIN.

### Parameters
- **asin** (str) - Required - The Amazon Standard Identification Number.
- **typed** (bool) - Optional - If True, returns typed model objects.
```

--------------------------------

### AsyncKeepa.deals(deal_parms, domain='US', wait=True, typed=False)

Source: https://keepaapi.readthedocs.io/en/stable/api/async/keepa.AsyncKeepa.deals.html

Queries the Keepa API for product deals asynchronously. Returns a dictionary or a DealResponse object containing the matched deals and category information.

```APIDOC
## AsyncKeepa.deals

### Description
Query the Keepa API for product deals that match specific search criteria. A single request returns a maximum of 150 deals.

### Parameters
- **deal_parms** (dict | DealRequest) - Required - Dictionary or DealRequest object containing search filters (e.g., page, domainId, includeCategories, priceTypes, etc.).
- **domain** (str | Domain) - Optional - A valid Amazon domain (default: 'US').
- **wait** (bool) - Optional - Whether to wait for available tokens before querying (default: True).
- **typed** (bool) - Optional - If True, returns a DealResponse Pydantic model instead of a dictionary (default: False).

### Returns
- **dict | DealResponse** - Contains 'dr' (array of deal objects), 'categoryIds', 'categoryNames', and 'categoryCount'.
```

--------------------------------

### Retrieve seller information

Source: https://keepaapi.readthedocs.io/en/stable/api/async/keepa.AsyncKeepa.seller_query.html

Demonstrates how to initialize the Keepa API and query information for a specific seller ID.

```python
>>> import keepa
>>> key = "<REAL_KEEPA_KEY>"
>>> api = keepa.Keepa(key)
>>> seller_info = api.seller_query("A2L77EE7U53NWQ", "US")
>>> seller_info["A2L77EE7U53NWQ"]["sellerName"]
'Amazon Warehouse'
```

--------------------------------

### Import and Verify Backend Models

Source: https://keepaapi.readthedocs.io/en/stable/backend_models.html

Access generated models from the backend_models module and verify model instances.

```python
from keepa import backend_models

assert isinstance(product, backend_models.Product)
print(backend_models.BACKEND_COMMIT)
```

--------------------------------

### Initialize Keepa API

Source: https://keepaapi.readthedocs.io/en/stable/api/sync/keepa.Keepa.html

Create an instance of the Keepa API object using a valid access key.

```python
>>> import keepa
>>> key = "<REAL_KEEPA_KEY>"
>>> api = keepa.Keepa(key)
```

--------------------------------

### Perform a basic deal search

Source: https://keepaapi.readthedocs.io/en/stable/deal_queries.html

Uses a dictionary to define search parameters and retrieves the first ASIN from the response.

```python
parameters = {
    "page": 0,
    "domainId": 1,
    "includeCategories": [16310101],
    "priceTypes": [0],
}
deals = api.deals(parameters)
first_asin = deals["dr"][0]["asin"]
```

--------------------------------

### Retrieve Offer Stock Data

Source: https://keepaapi.readthedocs.io/en/stable/offer_queries.html

Enable stock=True to request current stock data for live offers. Backend reporting for stock is capped at 10 units.

```python
product = api.query("1454857935", offers=20, stock=True)[0]

for index in product.get("liveOffersOrder", []):
    offer = product["offers"][index]
    stock_history = offer.get("stockCSV")
    latest_stock = offer.get("stock")
```

--------------------------------

### Perform an asynchronous deal request

Source: https://keepaapi.readthedocs.io/en/stable/deal_queries.html

Demonstrates the awaitable syntax for the deals endpoint when using the asynchronous API client.

```python
response = await async_api.deals(request, typed=True)
```

--------------------------------

### Print Item Details

Source: https://keepaapi.readthedocs.io/en/stable/api/sync/keepa.Keepa.html

Access and display specific fields like ASIN and title from the returned product data.

```python
>>> print("Item 1")
>>> print("\t ASIN: {:s}".format(products[0]["asin"]))
>>> print("\t Title: {:s}".format(products[0]["title"]))
```

--------------------------------

### Async Category and Best-Seller Queries

Source: https://keepaapi.readthedocs.io/en/stable/category_queries.html

Demonstrates asynchronous usage for category searching and best-seller queries.

```python
categories = await async_api.search_for_categories("chairs", typed=True)
best_sellers = await async_api.best_sellers_query("402283011", typed=True)
```

--------------------------------

### Query product metadata

Source: https://keepaapi.readthedocs.io/en/stable/api/async/keepa.AsyncKeepa.query.html

Retrieves product information with specific metadata flags enabled, such as video content.

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

--------------------------------

### AsyncKeepa.best_sellers_query(category, rank_avg_range=0, variations=False, sublist=False, domain='US', wait=True, typed=False)

Source: https://keepaapi.readthedocs.io/en/stable/api/async/keepa.AsyncKeepa.best_sellers_query.html

Retrieves an ASIN list of the most popular products based on sales in a specific category or product group.

```APIDOC
## AsyncKeepa.best_sellers_query

### Description
Retrieve an ASIN list of the most popular products based on sales in a specific category or product group. Lists are updated daily and ordered by sales performance.

### Parameters
- **category** (str) - Required - The category node id of the category to request.
- **rank_avg_range** (int) - Optional - Specifies sales rank average: 0 (current), 30 (30-day), 90 (90-day), or 180 (180-day). Default is 0.
- **variations** (bool) - Optional - If True, returns all variations. If False, returns the representative variation. Default is False.
- **sublist** (bool) - Optional - If True, requests best seller list based on sub-category sales rank. Default is False.
- **domain** (str | Domain) - Optional - The Amazon domain to query. Default is 'US'.
- **wait** (bool) - Optional - If True, waits for available tokens before querying. Default is True.
- **typed** (bool) - Optional - If True, returns the full BestSellers Pydantic model. If False, returns a list of ASINs. Default is False.

### Returns
- **list[str | None] | BestSellers** - A list of ASINs or the full BestSellers model depending on the 'typed' parameter.
```

--------------------------------

### keepa.Keepa.product_finder(product_parms, domain='US', wait=True, n_products=50)

Source: https://keepaapi.readthedocs.io/en/stable/api/sync/keepa.Keepa.product_finder.html

Queries the Keepa product database to find products matching the provided criteria. Returns a list of ASINs.

```APIDOC
## Method: product_finder

### Description
Queries the Keepa product database to find products matching specific criteria. Almost all product fields can be searched for and sorted.

### Parameters
- **product_parms** (dict | ProductParams | ProductFinderRequest) - Required - Dictionary, keepa.ProductParams, or generated keepa.models.backend.ProductFinderRequest containing search criteria.
- **domain** (str | Domain) - Optional - A valid Amazon domain (default: 'US').
- **wait** (bool) - Optional - Whether to wait for available tokens before querying the backend (default: True).
- **n_products** (int) - Optional - Maximum number of matching products to return (default: 50).

### Returns
- **list[str]** - A list of ASINs matching the product parameters.

### Usage Example
```python
import keepa
api = keepa.Keepa("<ENTER_ACTUAL_KEY_HERE>")
product_parms = {
    "author": "jim butcher",
    "sort": [["current_SALES", "asc"]],
}
asins = api.product_finder(product_parms, n_products=100)
```
```

--------------------------------

### await async_api.deals(request, typed=True)

Source: https://keepaapi.readthedocs.io/en/stable/deal_queries.html

Asynchronous version of the deals retrieval method.

```APIDOC
## await async_api.deals(request, typed=True)

### Description
Asynchronously retrieves deal data matching the provided request model.

### Parameters
- **request** (DealRequest) - Required - The request object.
- **typed** (bool) - Optional - Set to True to receive a typed response.

### Example
```python
response = await async_api.deals(request, typed=True)
```
```

--------------------------------

### Query products with dictionary parameters

Source: https://keepaapi.readthedocs.io/en/stable/api/sync/keepa.Keepa.product_finder.html

Uses a dictionary to define search criteria and sort order for the synchronous Keepa client.

```python
>>> import keepa
>>> api = keepa.Keepa("<ENTER_ACTUAL_KEY_HERE>")
>>> product_parms = {
...     "author": "jim butcher",
...     "sort": [["current_SALES", "asc"]],
... }
>>> asins = api.product_finder(product_parms, n_products=100)
>>> asins
['B000HRMAR2',
 '0578799790',
 'B07PW1SVHM',
...
 'B003MXM744',
 '0133235750',
 'B01MXXLJPZ']
```

--------------------------------

### api.query

Source: https://keepaapi.readthedocs.io/en/stable/offer_queries.html

Retrieves product data including marketplace offers. Setting the offers parameter between 20 and 100 enables offer data retrieval.

```APIDOC
## api.query(asin, offers=None, stock=False)

### Description
Queries product data. Setting `offers` between 20 and 100 includes marketplace offers in the response. Setting `stock=True` requests current offer stock data for live offers.

### Parameters
- **asin** (string) - Required - The ASIN of the product.
- **offers** (int) - Optional - Number of offers to retrieve (20-100).
- **stock** (bool) - Optional - Whether to refresh and include current stock data for live offers.
```

--------------------------------

### Download a basic product graph image

Source: https://keepaapi.readthedocs.io/en/stable/api/async/keepa.AsyncKeepa.download_graph_image.html

Downloads a graph image for a specific ASIN showing Amazon price, new price, and sales rank.

```python
>>> from keepa import Keepa
>>> api = Keepa("<YOUR_API_KEY>")
>>> api.download_graph_image(
...     asin="B09YNQCQKR",
...     filename="product_graph.png",
...     amazon=1,
...     new=1,
...     salesrank=1,
... )
```

--------------------------------

### Query Product Offers

Source: https://keepaapi.readthedocs.io/en/stable/offer_queries.html

Retrieve product offers by setting the offers parameter between 20 and 100. Note that these queries consume more tokens than standard metadata requests.

```python
product = api.query("1454857935", offers=20)[0]
offers = product.get("offers", [])
```

--------------------------------

### Perform batch product queries

Source: https://keepaapi.readthedocs.io/en/stable/product_data.html

Pass a sequence of codes to retrieve multiple products at once. Iterate over the returned list to access individual product data.

```python
asins = ["0022841350", "0022841369"]
products = api.query(asins, history=False)

for product in products:
    print(product["asin"], product.get("title"))

products_by_asin = {product["asin"]: product for product in products}
```

--------------------------------

### keepa.AsyncKeepa.query

Source: https://keepaapi.readthedocs.io/en/stable/api/async/keepa.AsyncKeepa.query.html

The query method is used to retrieve product data. It supports parameters to filter historical data, include metadata like videos or A+ content, and control the return format.

```APIDOC
## keepa.AsyncKeepa.query

### Description
Retrieves product data from the Keepa API. This method supports filtering historical data, including additional metadata, and returning results as dictionaries or Pydantic models.

### Parameters
- **only_live_offers** (bool) - Optional - If True, includes only live marketplace offers.
- **days** (int) - Optional - Limits historical data to the specified number of recent days.
- **raw** (bool) - Optional - If True, returns the raw request response (only available in non-async class).
- **videos** (bool) - Optional - If True, includes available video metadata.
- **aplus** (bool) - Optional - If True, includes available A+ content.
- **typed** (bool) - Optional - If True, returns products as Pydantic models instead of dictionaries.
- **extra_params** (dict[str, Any]) - Optional - Dictionary for additional API parameters not explicitly supported.

### Returns
- **list** - A list of products. By default, items are dictionaries. If typed=True, items are Pydantic models. If raw=True, items are requests.Response objects.
```

--------------------------------

### Process product offers and buy box data

Source: https://keepaapi.readthedocs.io/en/stable/api/async/keepa.AsyncKeepa.query.html

Retrieves product offers and converts the used buy box history into a pandas DataFrame for analysis.

```python
>>> 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
```

--------------------------------

### api.product_finder(params)

Source: https://keepaapi.readthedocs.io/en/stable/index.html

Performs a product discovery query based on specific filters.

```APIDOC
## api.product_finder(params)

### Description
Queries the product catalog using complex filters defined in a ProductParams object.

### Parameters
- **params** (keepa.ProductParams) - Required - The filter parameters for the product search.
```

--------------------------------

### keepa.Keepa.deals(deal_parms, domain='US', wait=True, typed=False)

Source: https://keepaapi.readthedocs.io/en/stable/api/sync/keepa.Keepa.deals.html

Queries the Keepa API for product deals matching the provided criteria.

```APIDOC
## keepa.Keepa.deals

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

### Parameters
- **deal_parms** (dict | DealRequest) - Required - Dictionary or generated keepa.models.backend.DealRequest containing search filters such as page, domainId, categories, price types, and ranges.
- **domain** (str | keepa.Domain) - Optional - A valid Amazon domain. Defaults to 'US'.
- **wait** (bool) - Optional - Wait for available tokens before querying the keepa backend. Defaults to True.
- **typed** (bool) - Optional - When True, return a keepa.models.backend.DealResponse Pydantic model instead of a dictionary. Defaults to False.

### Returns
- **dict | DealResponse** - Dictionary containing the deals, or a DealResponse object. Includes fields: 'dr' (array of deal objects), 'categoryIds', 'categoryNames', and 'categoryCount'.
```

--------------------------------

### Enable Typed Responses

Source: https://keepaapi.readthedocs.io/en/stable/backend_models.html

Initialize the Keepa API and query products with typed=True to receive Pydantic models instead of dictionaries.

```python
import keepa

api = keepa.Keepa("<REAL_KEEPA_KEY>")
products = api.query("B0088PUEPK", typed=True)
product = products[0]

print(product.asin)
print(product.title)
```

--------------------------------

### Apply complex backend filters

Source: https://keepaapi.readthedocs.io/en/stable/product_finder.html

Demonstrates the use of range suffixes like _lte and list-based filters for specific fields.

```python
request = keepa.ProductParams(
    buyBoxSellerId=["A2L77EE7U53NWQ", "ATVPDKIKX0DER"],
    partNumber=["MX-1000", "MX-1001"],
    current_SALES_lte=50000,
    sort=[["current_SALES", "desc"]],
)
asins = api.product_finder(request)
```

--------------------------------

### Query products with ProductParams object

Source: https://keepaapi.readthedocs.io/en/stable/api/sync/keepa.Keepa.product_finder.html

Uses the ProductParams helper class to structure search parameters for the product_finder method.

```python
>>> product_parms = keepa.ProductParams(
...     author="jim butcher",
...     sort=[["current_SALES", "asc"]],
... )
>>> asins = api.product_finder(product_parms, n_products=100)
```

--------------------------------

### Retrieve root categories using category_lookup

Source: https://keepaapi.readthedocs.io/en/stable/api/async/keepa.AsyncKeepa.category_lookup.html

Demonstrates initializing the Keepa API and fetching all root categories by passing 0 as the category_id.

```python
>>> import keepa
>>> key = "<REAL_KEEPA_KEY>"
>>> api = keepa.Keepa(key)
>>> categories = api.category_lookup(0)
```

--------------------------------

### Query product using non-ASIN codes

Source: https://keepaapi.readthedocs.io/en/stable/product_data.html

Use UPC, EAN, or ISBN-13 by setting the product_code_is_asin parameter to False.

```python
products = api.query("978-0786222728", product_code_is_asin=False)
```

--------------------------------

### Perform asynchronous product search

Source: https://keepaapi.readthedocs.io/en/stable/product_finder.html

Uses the await keyword to perform the search asynchronously.

```python
asins = await async_api.product_finder(parameters)
```

--------------------------------

### Use ProductParams in product_finder

Source: https://keepaapi.readthedocs.io/en/stable/api/types/keepa.ProductParams.html

Shows how to pass a configured ProductParams object to the Keepa API's product_finder method.

```python
>>> import keepa
>>> api = keepa.Keepa("<ENTER_ACTUAL_KEY_HERE>")
>>> product_params = keepa.ProductParams(author="J. R. R. Tolkien")
>>> asins = api.product_finder(product_parms, n_products=100)
```

--------------------------------

### Download a customized product graph image

Source: https://keepaapi.readthedocs.io/en/stable/api/async/keepa.AsyncKeepa.download_graph_image.html

Downloads a highly customized graph image with specific data points, time range, dimensions, and color settings.

```python
>>> api.download_graph_image(
...     asin="B09YNQCQKR",
...     filename="product_graph_365.png",
...     domain="US",
...     amazon=1,
...     new=1,
...     used=1,
...     bb=1,
...     fba=1,
...     range=365,
...     width=800,
...     height=400,
...     cBackground="ffffff",
...     cAmazon="FFA500",
...     cNew="8888dd",
...     cUsed="444444",
...     cBB="ff00b4",
...     cFBA="ff5722",
... )
```

--------------------------------

### Accessing Amazon Domain Regions

Source: https://keepaapi.readthedocs.io/en/stable/api/types/keepa.Domain.html

Demonstrates how to import the keepa module and access a specific domain constant.

```python
>>> import keepa
>>> keepa.Domain.US
<Domain.US: 'US'>
```

--------------------------------

### api.query()

Source: https://keepaapi.readthedocs.io/en/stable/product_data.html

Retrieves product data for one or more product codes. Supports various product code types and response formats.

```APIDOC
## api.query(codes, history=True, stats=None, offers=None, update=False, days=None, videos=False, aplus=False, product_code_is_asin=True, typed=False, raw=False)

### Description
Queries the Keepa API for product information. Accepts a single product code or a sequence of codes and returns a list of product data.

### Parameters
- **codes** (str | list | tuple | numpy.ndarray) - Required - The product code(s) to query (ASIN, ISBN-10, UPC, EAN, or ISBN-13).
- **history** (bool) - Optional - Include and parse product history. Default is True.
- **stats** (int) - Optional - Include summary statistics for the specified number of days.
- **offers** (int) - Optional - Include marketplace offers (valid range: 20-100).
- **update** (bool) - Optional - Request fresher data from Keepa.
- **days** (int) - Optional - Limit returned history to the most recent number of days.
- **videos** (bool) - Optional - Include video metadata.
- **aplus** (bool) - Optional - Include A+ content metadata.
- **product_code_is_asin** (bool) - Optional - Set to False if using UPC, EAN, or ISBN-13. Default is True.
- **typed** (bool) - Optional - If True, returns Pydantic models instead of dictionaries.
- **raw** (bool) - Optional - If True, returns unparsed HTTP responses (synchronous client only).

### Response
- **Returns** (list) - A list of product data objects or Pydantic models.
```

--------------------------------

### Query Best Sellers Asynchronously

Source: https://keepaapi.readthedocs.io/en/stable/api/async/keepa.AsyncKeepa.best_sellers_query.html

Retrieve a list of ASINs for a specific category using the asynchronous AsyncKeepa interface.

```python
>>> 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',
...
```

--------------------------------

### api.deals(params, typed=True)

Source: https://keepaapi.readthedocs.io/en/stable/backend_models.html

Queries for current deals based on provided parameters.

```APIDOC
## api.deals(params, typed=True)

### Description
Retrieves a list of deals based on the provided filter parameters.

### Parameters
- **params** (dict) - Required - Dictionary containing query parameters such as 'page' and 'domainId'.
- **typed** (bool) - Optional - If True, returns typed model objects.
```

--------------------------------

### Access Product History Data

Source: https://keepaapi.readthedocs.io/en/stable/product_history.html

Retrieves product history data and iterates through the first ten entries of new prices and their corresponding timestamps.

```python
product = api.query("059035342X")[0]
history = product.get("data", {})
new_prices = history.get("NEW", [])
new_times = history.get("NEW_time", [])

for timestamp, price in list(zip(new_times, new_prices))[:10]:
    print(timestamp, price)
```

--------------------------------

### Search using backend request models

Source: https://keepaapi.readthedocs.io/en/stable/product_finder.html

Uses the backend-specific ProductFinderRequest model to mirror the API schema exactly.

```python
request = keepa.backend_models.ProductFinderRequest(
    author=["jim butcher"],
    current_SALES_lte=50000,
)
asins = api.product_finder(request)
```

--------------------------------

### AsyncKeepa.time_to_refill

Source: https://keepaapi.readthedocs.io/en/stable/api/async/keepa.AsyncKeepa.time_to_refill.html

Returns the time to refill in seconds.

```APIDOC
## AsyncKeepa.time_to_refill

### Description
Returns the time remaining until the API token bucket refills, measured in seconds.

### Property
`AsyncKeepa.time_to_refill`

### Type
float
```

--------------------------------

### AsyncKeepa.download_graph_image(asin, filename, domain='US', wait=True, **graph_kwargs)

Source: https://keepaapi.readthedocs.io/en/stable/api/async/keepa.AsyncKeepa.download_graph_image.html

Downloads the graph image of a specific ASIN from Keepa and saves it to the provided file path.

```APIDOC
## AsyncKeepa.download_graph_image

### Description
Downloads the graph image of an ASIN from Keepa. Graph images are cached for 90 minutes on a per-user basis.

### Parameters
- **asin** (str) - Required - The ASIN of the product.
- **filename** (str | pathlib.Path) - Required - Path to save the png to.
- **domain** (str | keepa.Domain) - Optional - A valid Amazon domain (default: 'US').
- **wait** (bool) - Optional - Wait for available tokens before querying the keepa backend (default: True).
- **graph_kwargs** (dict[str, Any]) - Optional - Optional graph keyword arguments for customization.

### Example
```python
>>> api.download_graph_image(
...     asin="B09YNQCQKR",
...     filename="product_graph.png",
...     amazon=1,
...     new=1,
...     salesrank=1
... )
```
```

--------------------------------

### Keepa.seller_query(seller_id, domain='US', to_datetime=True, storefront=False, update=None, wait=True, typed=False)

Source: https://keepaapi.readthedocs.io/en/stable/api/sync/keepa.Keepa.seller_query.html

Retrieves seller information for a given seller ID or list of IDs. Token cost is 1 per requested seller.

```APIDOC
## Keepa.seller_query

### Description
Receive seller information for a given seller id or ids. If a seller is not found, no tokens will be consumed.

### Parameters
- **seller_id** (str | list[str]) - Required - The seller id of the merchant. Batch requests support up to 100 seller_ids.
- **domain** (str | keepa.Domain) - Optional - A valid Amazon domain. Default: 'US'.
- **to_datetime** (bool) - Optional - When True, casts time values to datetime.datetime. Default: True.
- **storefront** (bool) - Optional - If True, includes additional information about items the seller is listing. Default: False.
- **update** (int) - Optional - Positive integer to force a new collection if the last live data is older than the specified hours.
- **wait** (bool) - Optional - Wait for available tokens before querying. Default: True.
- **typed** (bool) - Optional - When True, returns sellers as Pydantic models instead of dictionaries. Default: False.

### Returns
- **dict[str, dict[str, Any]] | dict[str, Seller]** - One entry per input seller_id.

### Example
```python
import keepa
key = "<REAL_KEEPA_KEY>"
api = keepa.Keepa(key)
seller_info = api.seller_query("A2L77EE7U53NWQ", "US")
print(seller_info["A2L77EE7U53NWQ"]["sellerName"])
# Output: 'Amazon Warehouse'
```
```

--------------------------------

### Execute a typed deal request

Source: https://keepaapi.readthedocs.io/en/stable/deal_queries.html

Constructs a request using DealRequest models and retrieves a typed DealResponse object.

```python
request = keepa.backend_models.DealRequest(
    page=0,
    domainId=1,
    includeCategories=[16310101],
    priceTypes=[0],
)
response = api.deals(request, typed=True)
asins = [deal.asin for deal in response.dr or [] if deal is not None]
```

--------------------------------

### Access Product Histories

Source: https://keepaapi.readthedocs.io/en/stable/index.html

Extract price and offer history arrays for use with data analysis libraries.

```python
history = product.get("data", {})
new_prices = history.get("NEW")
new_times = history.get("NEW_time")

stats = product.get("stats_parsed", {})
current_sales_rank = stats.get("current", {}).get("SALES")
```

--------------------------------

### Plotting Product History

Source: https://keepaapi.readthedocs.io/en/stable/product_history.html

Shows how to use the built-in plotter to visualize product history data.

```APIDOC
keepa.plot_product(product)
```
Tokens:
Raw