Keepa Python API

https://keepaapi.readthedocs.io/en/latest/
Admin
This Python library allows you to interface with the Keepa API to query for Amazon product...
Tokens:37,463
Snippets:192
Trust Score:8.3
Update:3 months ago
Show doc for...
Tokens:
Raw
### Product Finder Example

Source: https://keepaapi.readthedocs.io/en/latest/api_methods.html

Demonstrates how to use the `product_finder` method with `ProductParams` to search for products by author and sort the results.

```APIDOC
## Product Finder

### Description
This method allows you to find products based on specified parameters. It can be used with both synchronous and asynchronous Keepa API clients.

### Method
`api.product_finder(product_params, n_products)`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

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

### Response
#### Success Response
Returns a list of ASINs matching the search criteria.

#### Response Example
```
['B000HRMAR2', '0578799790', 'B07PW1SVHM', ...]
```
```

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

### Install keepa from Source

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

Install the keepa module from GitHub source code.

```bash
cd keepa
pip install .

```

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

### Install Keepa API in Development Mode

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

Clone the Keepa repository and install it in development mode with test dependencies. This setup is for contributing to the library.

```bash
git clone https://github.com/<USERNAME>/keepa
pip install -e .[test]
```

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

### Install keepa Python Library

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

Install the keepa module from PyPi using pip.

```bash
pip install keepa

```

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

### Query Product with Videos Metadata

Source: https://keepaapi.readthedocs.io/en/latest/api_methods.html

Query a product using its ASIN and request video metadata. This example checks if the 'videos' key exists in the response.

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

```

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

### Find Products by Author (Synchronous)

Source: https://keepaapi.readthedocs.io/en/latest/api_methods.html

Use the `product_finder` method with `ProductParams` to search for products by author. This example demonstrates a synchronous call.

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

```

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

### Find Products by Author (Asynchronous)

Source: https://keepaapi.readthedocs.io/en/latest/api_methods.html

Query for products using the asynchronous `AsyncKeepa` class. This example shows how to set up and run an asynchronous query for products by a specific author.

```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 (Synchronous)

Source: https://keepaapi.readthedocs.io/en/latest/api_methods.html

Use the synchronous Keepa interface to query product information using its ASIN. This example retrieves the product title.

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

```

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

### Query Product (Asynchronous)

Source: https://keepaapi.readthedocs.io/en/latest/api_methods.html

Utilize the asynchronous Keepa interface to query product information by ASIN. This example demonstrates fetching the product title in an async context.

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

```

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

### Retrieve Deals using Asynchronous Keepa API

Source: https://keepaapi.readthedocs.io/en/latest/api_methods.html

This snippet demonstrates how to retrieve deals asynchronously using the `AsyncKeepa` class. It also includes an example of searching for categories.

```python
>>> 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)
...     categories = await api.search_for_categories("movies")
...     return await api.deals(deal_parms)
... 
>>> asins = asyncio.run(main())
>>> asins
```

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

### Initialize ProductParams with Keywords

Source: https://keepaapi.readthedocs.io/en/latest/api_methods.html

Shows how to instantiate a `ProductParams` object by passing parameters as keyword arguments. This is a concise way to set parameters upon creation.

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

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

### Initialize Keepa API

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

Demonstrates how to import the Keepa library and establish a connection to the server using an access key.

```APIDOC
## Initialize Keepa API

### Description
Import the Keepa library and establish a connection to the server using your access key.

### Code
```python
import keepa
accesskey = 'XXXXXXXXXXXXXXXX' # enter real access key here
api = keepa.Keepa(accesskey)
```
```

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

### Import Keepa API and Establish Connection

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

Import the Keepa library and create an API instance using your access key. Ensure you replace 'XXXXXXXXXXXXXXXX' with your actual Keepa API key.

```python
import keepa
accesskey = 'XXXXXXXXXXXXXXXX' # enter real access key here
api = keepa.Keepa(accesskey)
```

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

### Search Categories

Source: https://keepaapi.readthedocs.io/en/latest/api_methods.html

Search for product categories on Amazon using a search term. This example prints category IDs and their names for the term 'science'.

```python
>>> import keepa
>>> key = "<REAL_KEEPA_KEY>"
>>> api = keepa.Keepa(key)
>>> categories = api.search_for_categories("science")
>>> for cat_id in categories:
...     print(cat_id, categories[cat_id]["name"])
... 
9091159011 Behavioral Sciences
8407535011 Fantasy, Horror & Science Fiction
8407519011 Sciences & Technology
12805 Science & Religion
13445 Astrophysics & Space Science
12038 Science Fiction & Fantasy
3207 Science, Nature & How It Works
144 Science Fiction & Fantasy

```

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

### Initialize ProductParams with Attributes

Source: https://keepaapi.readthedocs.io/en/latest/api_methods.html

Demonstrates how to create a `ProductParams` object and set an attribute using dot notation. This is useful for incrementally building parameter objects.

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

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

### Get Time to Refill Tokens

Source: https://keepaapi.readthedocs.io/en/latest/api_methods.html

Check the remaining time in seconds until API tokens are refilled. If tokens are currently available, this value should be 0.0.

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

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

### Async API Initialization and Query

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

Shows how to use the Keepa API asynchronously with `async`/`await`.

```APIDOC
## Async API Initialization and Query

### Description
Utilize the Keepa API asynchronously using `async` and `await` for non-blocking operations.

### Async Initialization
```python
import keepa
accesskey = 'XXXXXXXXXXXXXXXX' # enter real access key here
api = await keepa.AsyncKeepa.create(accesskey)
```

### Async Single ASIN Query
```python
products = await api.query('059035342X')
```

### Async Query with `wait=False`
If you plan to do a lot of simultaneous queries, you might want to speed up queries using the `wait=False` argument.

```python
products = await api.query('059035342X', wait=False)
```
```

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

### Query Multiple ASINs

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

Demonstrates how to query product data for multiple ASINs from a list or a NumPy array.

```APIDOC
## Query Multiple ASINs

### Description
Query product data for multiple ASINs from a list or a NumPy array.

### Method
`api.query(asins)`

### Parameters
- **asins** (list or numpy.ndarray) - Required - A list or NumPy array of ASINs.

### Request Example (List)
```python
asins = ['0022841350', '0022841369', '0022841369', '0022841369']
products = api.query(asins)
```

### Request Example (NumPy Array)
```python
asins = np.asarray(['0022841350', '0022841369', '0022841369', '0022841369'])
products = api.query(asins)
```

### Response
- **products** (list) - A list of dictionaries, where each dictionary contains product data for a successful result.
```

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

### Plot Product Data Using Keepa Module

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

Utilize the `keepa.plot_product` function to directly plot the product data if Matplotlib is installed. This provides a convenient way to visualize product history.

```python
keepa.plot_product(products[0])
```

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

### Lookup Root Categories (Synchronous)

Source: https://keepaapi.readthedocs.io/en/latest/api_methods.html

Retrieves root categories from the Keepa API. Pass `0` as the `category_id` to get a list of all root categories. Requires an initialized Keepa API object.

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

>>> list(categories.values())[0]
{'domainId': 1,
 'catId': 133140011,
 'name': 'Kindle Store',
 'children': [133141011,
  133143011,
  6766606011,
  7529231011,
  118656435011,
  2268072011,
  119757513011,
  358606011,
  3000677011,
  1293747011],
 'parent': 0,
 'highestRank': 6984155,
 'productCount': 6417325,
 'contextFreeName': 'Kindle Store',
 'lowestRank': 1,
 'matched': True}
```

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

### Import Keepa API for Async Operations

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

Import the Keepa library and create an asynchronous API instance using your access key. This is for use with async/await syntax.

```python
import keepa
accesskey = 'XXXXXXXXXXXXXXXX' # enter real access key here
api = await keepa.AsyncKeepa.create(accesskey)
```

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

### Category Best Sellers Query

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

Retrieve a list of best-selling products within a specific category. First, search for categories to get their IDs, then use the `best_sellers_query` method with a category ID.

```APIDOC
## Category Queries
You can retrieve an ASIN list of the most popular products based on sales in a specific category or product group. Here’s an example that assumes you’ve already setup your api.
```python
# get category id numbers for chairs
if test_categories:
    categories = api.search_for_categories('chairs')

    # print the first 5 catIds
    catids = list(categories.keys())
    for catid in catids[:5]:
        print(catid, categories[catid]['name'])

    # query the best sellers for "Arm Chairs"
    bestsellers = api.best_sellers_query('402283011')

print('\nBest Sellers:')
for bestseller in bestsellers:
    print(bestseller)

```

```
8728936011 Stools, Chairs & Seat Cushions
16053799011 Mamagreen Outdoor Dining Chairs
8297445011 Medical Chairs
3290537011 kitchen chairs
5769032011 Office Chairs

Best Sellers:
B00HGE0MT2
B006W6U006
B006Z8RD60
B006Z8S6UC
B009UVKXY8
B009FXIVMC
B0077LGFTK
B0078NISRY
B00ESI56B8
B00EOQ5W8G

```
```

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

### Query Single ASIN

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

Shows how to query product data for a single ASIN.

```APIDOC
## Query Single ASIN

### Description
Query product data for a single ASIN.

### Method
`api.query(asin)`

### Parameters
- **asin** (string) - Required - The Amazon Standard Identification Number (ASIN) of the product.

### Request Example
```python
products = api.query('059035342X')
```

### Response
- **products** (list) - A list of dictionaries, where each dictionary contains product data for a successful result.
```

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

### Use ProductParams in product_finder

Source: https://keepaapi.readthedocs.io/en/latest/api_methods.html

Illustrates how to use a configured `ProductParams` object within the `keepa.Keepa.product_finder()` method to search for products. Remember to replace '<ENTER_ACTUAL_KEY_HERE>' with your Keepa API key.

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

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

### Plot Product Price History with Matplotlib

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

Plots the price history of a product using matplotlib. Ensure matplotlib is installed. The data is best represented as a step plot due to its discontinuous nature.

```python
import matplotlib.pyplot as plt
key = 'TRADE_IN'
history = product['data']
plt.step(history[key], history[key + '_time'], where='pre')
```

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

### Get Category IDs and Best Sellers

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

Retrieves category IDs for a given search term and then queries for the best-selling products within a specific category. Requires an initialized Keepa API object.

```python
# get category id numbers for chairs
if test_categories:
    categories = api.search_for_categories('chairs')

    # print the first 5 catIds
    catids = list(categories.keys())
    for catid in catids[:5]:
        print(catid, categories[catid]['name'])

    # query the best sellers for "Arm Chairs"
    bestsellers = api.best_sellers_query('402283011')

print('\nBest Sellers:')
for bestseller in bestsellers:
    print(bestseller)
```

```text
8728936011 Stools, Chairs & Seat Cushions
16053799011 Mamagreen Outdoor Dining Chairs
8297445011 Medical Chairs
3290537011 kitchen chairs
5769032011 Office Chairs

Best Sellers:
B00HGE0MT2
B006W6U006
B006Z8RD60
B006Z8S6UC
B009UVKXY8
B009FXIVMC
B0077LGFTK
B0078NISRY
B00ESI56B8
B00EOQ5W8G
```

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

### query

Source: https://keepaapi.readthedocs.io/en/latest/api_methods.html

Queries for product information using an ASIN. Supports both synchronous and asynchronous interfaces. Can also load product offers and process buy box data into a pandas DataFrame.

```APIDOC
## query(asin: str, offers: int = None, history: bool = True, videos: bool = False)

### Description
Queries for product information using an ASIN. Supports both synchronous and asynchronous interfaces. Can also load product offers and process buy box data into a pandas DataFrame.

### Method
(Not specified, assumed to be part of a query)

### Endpoint
(Not specified, assumed to be part of a query)

### Parameters
* **asin** (str) - The ASIN of the product to query.
* **offers** (int, optional) - The number of offers to load. Defaults to None.
* **history** (bool, optional) - Whether to include history data. Defaults to True.
* **videos** (bool, optional) - Whether to include video metadata. Defaults to False.

### Request Example
```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'

```

### Response
(Not specified, but examples show a list of product dictionaries)

### Error Handling
(Not specified)
```

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

### Asynchronous Product Finder with Keepa

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

Find products based on author using the asynchronous keepa interface. Requires a real Keepa API key.

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

```

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

### Initialize Keepa API Object

Source: https://keepaapi.readthedocs.io/en/latest/api_methods.html

Create an instance of the Keepa API client. Requires a valid access key. The `check_key` parameter can be set to False to speed up initialization at the risk of using an invalid key.

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

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

### Find Products using Product Finder

Source: https://keepaapi.readthedocs.io/en/latest/api_methods.html

Query the Keepa product database to find products matching specific criteria. Results can be sorted by various product fields.

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

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

### Access and Print Product Information

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

Access basic product details like keys, ASIN, and title from the returned product data. The 'products' variable is a list of dictionaries, where each dictionary represents a product.

```python
# Available keys
print(products[0].keys())

# Print ASIN and title
print('ASIN is ' + products[0]['asin'])
print('Title is ' + products[0]['title'])
```

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

### Search Products by Author

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

Searches for products using the `product_finder` method with specific parameters, such as author. Ensure you replace 'ENTER_ACTUAL_KEY_HERE' with your valid Keepa API key.

```python
import keepa
api = keepa.Keepa('ENTER_ACTUAL_KEY_HERE')
product_parms = {'author': 'jim butcher'}
products = api.product_finder(product_parms)
```

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

### Query Product Data by ASIN

Source: https://keepaapi.readthedocs.io/en/latest/api_methods.html

Perform a product query for a list of ASINs. The result is a list of dictionaries, where each dictionary contains product details.

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

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

### Query Single Product by ASIN

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

Retrieve product data for a single ASIN. Refer to the API documentation for available query options.

```python
products = api.query('059035342X')

# See help(api.query) for available options when querying the API
```

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

### Query Multiple Products by NumPy Array

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

Retrieve product data for multiple ASINs provided as a NumPy array. This is an alternative to using a Python list for multiple ASIN queries.

```python
import numpy as np
asins = np.asarray(['0022841350', '0022841369', '0022841369', '0022841369'])
products = api.query(asins)
```

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

### Retrieve and Process Offer History

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

Fetch offer data for a product, convert offer history CSV data into time and price arrays, and plot individual active offers. The 'offers' parameter must be enabled in the query.

```python
import matplotlib.pyplot as plt

products = api.query(asins, offers=20)
product = products[0]
offers = product['offers']

# each offer contains the price history of each offer
offer = offers[0]
csv = offer['offerCSV']

# convert these values to numpy arrays
times, prices = keepa.convert_offer_history(csv)

# for a list of active offers, see
indices = product['liveOffersOrder']

# with this you can loop through active offers:
offer_times = []
offer_prices = []
for index in indices:
    csv = offers[index]['offerCSV']
    times, prices = keepa.convert_offer_history(csv)
    offer_times.append(times)
    offer_prices.append(prices)

# you can aggregate these using np.hstack or plot at the history individually
for i in range(len(offer_prices)):
    plt.step(offer_times[i], offer_prices[i])
plt.show()
```

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

### Query Product with Wait Disabled (Async)

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

Perform an asynchronous product query with the 'wait' parameter set to False. This can speed up queries if you are making many simultaneous requests.

```python
products = await api.query('059035342X', wait=False)
```

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

### Query Single Product by ASIN (Async)

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

Retrieve product data for a single ASIN using the asynchronous API instance. This method is non-blocking.

```python
products = await api.query('059035342X')
```

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

### Query Multiple Products by ASIN List

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

Retrieve product data for multiple ASINs provided in a Python list. Duplicate ASINs in the list will result in duplicate entries in the response.

```python
asins = ['0022841350', '0022841369', '0022841369', '0022841369']
products = api.query(asins)
```

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

### Run Pre-commit Hooks for Code Styling

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

Apply pre-commit hooks to format code and ensure it meets styling standards across all files. This is a required step before creating a pull request.

```bash
pre-commit run --all-files
```

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

### Buy Box Statistics

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

Demonstrates how to load and process used buy box statistics by enabling the `offers` parameter and converting the data to a pandas DataFrame.

```APIDOC
## Buy Box Statistics

### Description
Load and process used buy box statistics. This requires enabling the `offers` parameter and then converting the buy box data into a pandas DataFrame.

### Method
`api.query(asin, offers=N)`

### Parameters
- **offers** (integer) - Required - Set to a value greater than 0 to enable offer data retrieval.

### Request Example
```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)
print(df)
```

### Response Example (DataFrame)
```
              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 Method

Source: https://keepaapi.readthedocs.io/en/latest/api_methods.html

Details the `query` method for retrieving product data using ASINs or other product codes, with extensive parameter options for customization.

```APIDOC
## Query Product Data

### Description
Perform a product query of a list, array, or single ASIN. Returns a list of product data with one entry for each product.

### Method
`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_, _extra_params : dict[str, Any] | None = {}_) → list[dict[str, Any]]`

### Parameters
#### Path Parameters
None

#### Query Parameters
- **items** (str | Sequence[str]) - Required - 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`.
- **stats** (int | None) - 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. Can be last x days (positive integer) or a date range (unix epoch time milliseconds or ISO8601 date strings).
- **domain** (str | Domain, default: ‘US’) - A valid Amazon domain. See `keepa.Domain`.
- **history** (bool, default: True) - 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.
- **offers** (int, optional) - Adds available offers to product data. Default 0. Must be between 20 and 100. Enabling this also enables the `"buyBoxUsedHistory"`.
- **update** (int, 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_datetime** (bool, default: True) - When `True` casts the time values of the product data (e.g. `"AMAZON_TIME"`) to `datetime.datetime`. When `False`, the values are represented as `numpy` `"<M8[m]"`. This has no effect on pandas dataframes (e.g. `"df_AMAZON"`).
- **rating** (bool, default: False) - When set to to True, includes the existing RATING and COUNT_REVIEWS history of the csv field.
- **out_of_stock_as_nan** (bool, default: True) - When True, prices are NAN when price category is out of stock. When False, prices are -0.01.
- **stock** (bool, 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_asin** (bool, 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_bar** (bool, default: True) - Display a progress bar using `tqdm`.
- **buybox** (bool, optional) - Additional token cost: 2 per product). When true the product and statistics object will include all available buy box related data. 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.
- **wait** (bool, default: True) - Wait for results.
- **days** (int | None, optional) - Number of days for history.
- **only_live_offers** (bool | None, optional) - Filter for live offers only.
- **raw** (bool, default: False) - Return raw data.
- **videos** (bool, default: False) - Include video data.
- **aplus** (bool, default: False) - Include A+ content.
- **extra_params** (dict[str, Any] | None, default: {{}}) - Additional parameters to send with the request.

### Request Example
```python
>>> items = ["B000HRMAR2", "0578799790"]
>>> data = api.query(items, stats=30, history=False)
```

### Response
#### Success Response (200)
Returns a list of dictionaries, where each dictionary contains product data for a requested item.

#### Response Example
```json
[
  {
    "asin": "B000HRMAR2",
    "title": "Storm Front",
    "currentPrice": {
      "value": 7.99,
      "currency": "USD"
    },
    "history": [
      [1678886400000, 7.99],
      [1678972800000, 7.99]
    ]
    // ... other product data
  }
]
```
```

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

### Keepa Class Initialization

Source: https://keepaapi.readthedocs.io/en/latest/api_methods.html

Initializes the Keepa API client with your access key. You can optionally configure the timeout, logging level, and whether to check the key on initialization.

```APIDOC
## Keepa Class

### Description
Synchronous Python interface to keepa data backend. Initializes API with access key. Access key can be obtained by signing up for a reoccurring or one time plan. To obtain a key, sign up for one at Keepa Data.

### Parameters

#### accesskey (str)
64 character access key string.

#### timeout (float, default: 10.0)
Default timeout when issuing any request. This is not a time limit on the entire response download; rather, an exception is raised if the server has not issued a response for timeout seconds. Setting this to 0.0 disables the timeout, but will cause any request to hang indefiantly should keepa.com be down

#### logging_level (str, default: “DEBUG”)
Logging level to use. Default is “DEBUG”. Other options are “INFO”, “WARNING”, “ERROR”, and “CRITICAL”.

#### check_key (bool, default: True)
Check the keepa key on initialization and update the number of available tokens. This is a free check and does not cost any tokens, but does slow down the time to initialize. Disable this to speed up init at the risk of using an invalid key when querying for a product.

### Attributes

#### time_to_refill
Return the time to refill in seconds.

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

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

### Synchronous Keepa API Query and Plotting

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

Perform a single ASIN query and plot the product data using the synchronous keepa API. Requires matplotlib for plotting.

```python
import keepa
accesskey = 'XXXXXXXXXXXXXXXX' # enter real access key here from https://get.keepa.com/d7vrq
api = keepa.Keepa(accesskey)

# Single ASIN query
products = api.query('B0088PUEPK')  # returns list of product data

# Plot result (requires matplotlib)
keepa.plot_product(products[0])

```

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

### Product Finder Query

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

Search for products using various parameters with the `product_finder` method. Refer to `help(api.product_finder)` for a comprehensive list of available search parameters.

```APIDOC
## Product Search
You can search for products using `keepa` using the `product_finder` method. There are many parameters you can search using. See `help(api.product_finder)` or check the description of the function at keepa.Api Methods.
```python
# Query for all of Jim Butcher's books:

import keepa
api = keepa.Keepa('ENTER_ACTUAL_KEY_HERE')
product_parms = {'author': 'jim butcher'}
products = api.product_finder(product_parms)

```
```

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

### Process Buy Box Data into DataFrame

Source: https://keepaapi.readthedocs.io/en/latest/api_methods.html

Load product offers and convert buy box data into a pandas DataFrame for easier analysis. This snippet shows how to process used buy box information.

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


```

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

### product_finder

Source: https://keepaapi.readthedocs.io/en/latest/api_methods.html

Query the keepa product database to find products matching criteria.

```APIDOC
## product_finder

### Description
Query the keepa product database to find products matching criteria.

### Parameters

#### product_parms

#### domain

#### wait
```
Tokens:
Raw