Skip to main content

Interfaces with keepa.com's API.

Project description

https://img.shields.io/pypi/v/keepa.svg?logo=python&logoColor=white https://github.com/akaszynski/keepa/actions/workflows/testing-and-deployment.yml/badge.svg Documentation Status https://codecov.io/gh/akaszynski/keepa/branch/main/graph/badge.svg https://app.codacy.com/project/badge/Grade/9452f99f297c4a6eac14e2d21189ab6f

This Python library allows you to interface with the API at Keepa to query for Amazon product information and history. It also contains a plotting module to allow for plotting of a product.

Sign up for Keepa Data Access.

Documentation can be found at Keepa Documentation.

Requirements

This library is compatible with Python >= 3.9 and requires:

  • numpy

  • aiohttp

  • matplotlib

  • tqdm

Product history can be plotted from the raw data when matplotlib is installed.

Interfacing with the keepa requires an access key and a monthly subscription from Keepa API.

Installation

Module can be installed from PyPi with:

pip install keepa

Source code can also be downloaded from GitHub and installed using:

cd keepa
pip install .

Brief Example

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])
https://github.com/akaszynski/keepa/raw/main/docs/source/images/Product_Price_Plot.png

Product Price Plot

https://github.com/akaszynski/keepa/raw/main/docs/source/images/Product_Offer_Plot.png

Product Offers Plot

Brief Example using async

Here’s an example of obtaining a product and plotting its price and offer history using the keepa.AsyncKeepa class:

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

Detailed Examples

Import interface and establish connection to server

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

Single ASIN query

products = api.query('059035342X')

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

You can use keepa witch async / await too

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

Single ASIN query (async)

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

Multiple ASIN query from List

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

Multiple ASIN query from numpy array

asins = np.asarray(['0022841350', '0022841369', '0022841369', '0022841369'])
products = api.query(asins)

Products is a list of product data with one entry per successful result from the Keepa server. Each entry is a dictionary containing the same product data available from Amazon.

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

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

The raw data is contained within each product result. Raw data is stored as a dictionary with each key paired with its associated time history.

# Access new price history and associated time data
newprice = products[0]['data']['NEW']
newpricetime = products[0]['data']['NEW_time']

# Can be plotted with matplotlib using:
import matplotlib.pyplot as plt
plt.step(newpricetime, newprice, where='pre')

# Keys can be listed by
print(products[0]['data'].keys())

The product history can also be plotted from the module if matplotlib is installed

keepa.plot_product(products[0])

You can obtain the offers history for an ASIN (or multiple ASINs) using the offers parameter. See the documentation at Request Products for further details.

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:
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.show()

If you plan to do a lot of simulatneous query, you might want to speedup query using wait=False arguments.

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

Buy Box Statistics

To load used buy box statistics, you have to enable offers. This example loads in product offers and converts 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

Contributing

Contribute to this repository by forking this repository and installing in development mode with:

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

You can then add your feature or commit your bug fix and then run your unit testing with:

pytest

Unit testing will automatically enforce minimum code coverage standards.

Next, to ensure your code meets minimum code styling standards, run:

pre-commit run --all-files

Finally, create a pull request from your fork and I’ll be sure to review it.

Credits

This Python module, written by Alex Kaszynski and several contribitors, is based on Java code written by Marius Johann, CEO Keepa. Java source is can be found at keepacom/api_backend.

License

Apache License, please see license file. Work is credited to both Alex Kaszynski and Marius Johann.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

keepa-1.3.15.tar.gz (41.2 kB view details)

Uploaded Source

Built Distribution

keepa-1.3.15-py3-none-any.whl (38.3 kB view details)

Uploaded Python 3

File details

Details for the file keepa-1.3.15.tar.gz.

File metadata

  • Download URL: keepa-1.3.15.tar.gz
  • Upload date:
  • Size: 41.2 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.12.9

File hashes

Hashes for keepa-1.3.15.tar.gz
Algorithm Hash digest
SHA256 ec2323e9e0e43c77d04eec6a1050245123beb510182f36445b506b6a43b69e69
MD5 52a1c8278d20475c17fd53c90720f8e0
BLAKE2b-256 9b6ab5bbbb386c38c13cd9921f06319135a3527501bf5f38a0bd9f60647e6aca

See more details on using hashes here.

Provenance

The following attestation bundles were made for keepa-1.3.15.tar.gz:

Publisher: testing-and-deployment.yml on akaszynski/keepa

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file keepa-1.3.15-py3-none-any.whl.

File metadata

  • Download URL: keepa-1.3.15-py3-none-any.whl
  • Upload date:
  • Size: 38.3 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.12.9

File hashes

Hashes for keepa-1.3.15-py3-none-any.whl
Algorithm Hash digest
SHA256 ae6fa9443872d054a5287442bcb571c5904e6df2ac8c7d96dd954c7cabb8e8f5
MD5 0bf708389dfa6d68bbc87e89fb003d0c
BLAKE2b-256 b5c2ef4b39552b0d157be2ffc12fe9f591c85f865decc672cb22c65dff1ef783

See more details on using hashes here.

Provenance

The following attestation bundles were made for keepa-1.3.15-py3-none-any.whl:

Publisher: testing-and-deployment.yml on akaszynski/keepa

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page