### Install keepa from Source

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

Installs the keepa Python library by downloading the source code from GitHub and running the setup script. This method is useful for development or when needing the latest unreleased changes.

```bash
cd keepa
pip install .

```

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

### Install Keepa API in Development Mode

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

This command demonstrates how to set up the Keepa API repository for development. It involves cloning the repository and then installing it in editable mode with testing dependencies. This is a prerequisite for contributing to the project.

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

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

### Plot Active Offer History (Python)

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

This example shows how to plot the history of active offers for a product. It retrieves active offer indices, processes their CSV data to get time and price histories, and then uses matplotlib to create a step plot.

```python
# for a list of active offers, use
indices = product['liveOffersOrder']

# with this you can loop through active offers:
indices = product['liveOffersOrder']
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
import matplotlib.pyplot as plt
for i in range(len(offer_prices)):
    plt.step(offer_times[i], offer_prices[i])

plt.xlabel('Date')
plt.ylabel('Offer Price')
plt.show()
```

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

### Install keepa Python Library

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

Installs the keepa Python library using pip from PyPI. This is the standard method for adding the library to your Python environment.

```bash
pip install keepa

```

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

### Product Finder Query (Python)

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

This example shows how to use the Keepa API's `product_finder` method to search for products. It initializes the API with a key and then performs a search based on provided parameters, such as 'author'.

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

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

### Find Products using Async Keepa API (Python)

Source: https://keepaapi.readthedocs.io/en/stable/api_methods

Explains how to find products asynchronously using the `keepa.AsyncKeepa.product_finder` method. This example sets up an asynchronous main function to initialize the API client and then calls the `product_finder` method with specified search parameters. It utilizes the `asyncio` library for execution.

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

```
```

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

### Instantiate Product Parameters with Keywords in Python

Source: https://keepaapi.readthedocs.io/en/stable/api_methods

Shows an alternative way to instantiate the ProductParams class by passing attribute values as keyword arguments. This provides a concise method for setting initial parameter values.

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

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

### GET /update_status

Source: https://keepaapi.readthedocs.io/en/stable/api_methods

Update available tokens.

```APIDOC
## GET /update_status

### Description
Update available tokens.

### Method
GET

### Endpoint
/update_status

### Parameters
No parameters required.

### Request Example
```
GET /update_status
```

### Response
#### Success Response (200)
- **tokens_available** (int) - The number of available tokens.

#### Response Example
```json
{
  "tokens_available": 100
}
```
```

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

### Retrieve Deals using Async Keepa API (Python)

Source: https://keepaapi.readthedocs.io/en/stable/api_methods

Illustrates how to fetch product deals asynchronously using the `keepa.AsyncKeepa` class. This example includes setting up an asynchronous function to initialize the API client, search for categories, and retrieve deals. It requires the `asyncio` library.

```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
['B0BF3P5XZS',
 'B08JQN5VDT',
 'B09SP8JPPK',
 '0999296345',
 'B07HPG684T',
 '1984825577',
...
```

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

### GET /search_for_categories

Source: https://keepaapi.readthedocs.io/en/stable/api_methods

Search for categories from Amazon.

```APIDOC
## GET /search_for_categories

### Description
Search for categories from Amazon.

### Method
GET

### Endpoint
/search_for_categories

### Parameters
#### Query Parameters
- **searchterm** (str) - Required - The term to search for categories.
- **domain** (str) - Optional - Default: 'US'. The domain to query.
- **wait** (bool) - Optional - Default: True. Whether to wait for tokens if none are available.

### Request Example
```
GET /search_for_categories?searchterm=harry potter
```

### Response
#### Success Response (200)
- **name** (str) - The name of the category.
- **id** (str) - The category node id.

#### Response Example
```json
[
  {
    "name": "Books",
    "id": "1000"
  },
  {
    "name": "Movies & TV",
    "id": "1001"
  }
]
```
```

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

### GET /download_graph_image

Source: https://keepaapi.readthedocs.io/en/stable/api_methods

Download the graph image of an ASIN from Keepa.

```APIDOC
## GET /download_graph_image

### Description
Download the graph image of an ASIN from Keepa.

### Method
GET

### Endpoint
/download_graph_image

### Parameters
#### Query Parameters
- **asin** (str) - Required - The ASIN of the product.
- **filename** (str) - Required - The filename to save the image to.
- **domain** (str) - Optional - Default: 'US'. The domain to query.
- **wait** (bool) - Optional - Default: True. Whether to wait for tokens if none are available.

### Request Example
```
GET /download_graph_image?asin=B00005N5O3&filename=product_graph.png
```

### Response
#### Success Response (200)
- **status** (str) - Indicates if the download was successful.

#### Response Example
```json
{
  "status": "success"
}
```
```

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

### Asynchronous Product Finder Query

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

Shows an example of using the asynchronous keepa API to find products based on parameters like author. It initializes an AsyncKeepa instance, performs the search, and returns a list of ASINs. This requires an event loop to run.

```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)
asyncio.run(main())

```

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

### GET /deals

Source: https://keepaapi.readthedocs.io/en/stable/api_methods

Query the Keepa API for product deals.

```APIDOC
## GET /deals

### Description
Query the Keepa API for product deals.

### Method
GET

### Endpoint
/deals

### Parameters
#### Query Parameters
- **deal_parms** (object) - Required - Parameters for the deal query.
- **domain** (str) - Optional - Default: 'US'. The domain to query.
- **wait** (bool) - Optional - Default: True. Whether to wait for tokens if none are available.

### Request Example
```json
{
  "deal_parms": {
    "type": "LIGHTNING_DEAL",
    "min_discount": 20
  }
}
```

### Response
#### Success Response (200)
- **deal_id** (str) - The ID of the deal.
- **product_asin** (str) - The ASIN of the product in the deal.
- **start_time** (str) - The start time of the deal.
- **end_time** (str) - The end time of the deal.

#### Response Example
```json
[
  {
    "deal_id": "12345",
    "product_asin": "B00005N5O3",
    "start_time": "2023-10-27T10:00:00Z",
    "end_time": "2023-10-27T18:00:00Z"
  }
]
```
```

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

### Use Product Parameters in Keepa API Product Finder in Python

Source: https://keepaapi.readthedocs.io/en/stable/api_methods

Illustrates how to integrate ProductParams with the Keepa API's product_finder method. This example shows the complete workflow from initializing the API client to performing a product search with custom parameters.

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