.. image:: https://img.shields.io/pypi/v/keepa.svg?logo=python&logoColor=white :target: https://pypi.org/project/keepa/
.. image:: https://github.com/akaszynski/keepa/actions/workflows/testing-and-deployment.yml/badge.svg :target: https://github.com/akaszynski/keepa/actions/workflows/testing-and-deployment.yml
.. image:: https://readthedocs.org/projects/keepaapi/badge/?version=latest :target: https://keepaapi.readthedocs.io/en/latest/?badge=latest :alt: Documentation Status
.. image:: https://codecov.io/gh/akaszynski/keepa/branch/main/graph/badge.svg :target: https://codecov.io/gh/akaszynski/keepa
.. image:: https://app.codacy.com/project/badge/Grade/9452f99f297c4a6eac14e2d21189ab6f :target: https://www.codacy.com/gh/akaszynski/keepa/dashboard?utm_source=github.com&utm_medium=referral&utm_content=akaszynski/keepa&utm_campaign=Badge_Grade
This Python library allows you to interface with the API at Keepa <https://keepa.com/>_ to query for Amazon product information and
history. It also contains a plotting module to allow for plotting of
a product.
See API pricing at Keepa API <https://keepa.com/#!api>_.
Documentation can be found on readthedocs at keepa Documentation <https://keepaapi.readthedocs.io/en/latest/>_.
This library is compatible with Python >= 3.8 and requires:
numpyaiohttpmatplotlibtqdmProduct 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 <https://keepa.com/#!api>_.
Module can be installed from PyPi <https://pypi.org/project/keepa/>_ with:
.. code::
pip install keepa
Source code can also be downloaded from GitHub <https://github.com/akaszynski/keepa>_ and installed using::
cd keepa pip install .
.. code:: python
import keepa
accesskey = 'XXXXXXXXXXXXXXXX' # enter real access key here
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])
.. figure:: https://github.com/akaszynski/keepa/raw/main/docs/source/images/Product_Price_Plot.png :width: 500pt
Product Price Plot
.. figure:: https://github.com/akaszynski/keepa/raw/main/docs/source/images/Product_Offer_Plot.png :width: 500pt
Product Offers Plot
Here's an example of obtaining a product and plotting its price and
offer history using the keepa.AsyncKeepa class:
.. code:: 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 for product with ASIN 'B0088PUEPK' using the asynchronous
keepa interface.
.. code:: 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'
Import interface and establish connection to server
.. code:: python
import keepa
accesskey = 'XXXXXXXXXXXXXXXX' # enter real access key here
api = keepa.Keepa(accesskey)
Single ASIN query
.. code:: python
products = api.query('059035342X')
# See help(api.query) for available options when querying the API
You can use keepa witch async / await too
.. code:: python
import keepa
accesskey = 'XXXXXXXXXXXXXXXX' # enter real access key here
api = await keepa.AsyncKeepa.create(accesskey)
Single ASIN query (async)
.. code:: python
products = await api.query('059035342X')
Multiple ASIN query from List
.. code:: python
asins = ['0022841350', '0022841369', '0022841369', '0022841369']
products = api.query(asins)
Multiple ASIN query from numpy array
.. code:: python
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 <http://www.amazon.com>_.
.. code:: python
# 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.
.. code:: python
# 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
.. code:: python
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 <https://keepa.com/#!discuss/t/request-products/110/1>_ for further details.
.. code:: python
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.
.. code:: python
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``.
.. code:: pycon
>>> 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 <https://github.com/keepacom/api_backend/>`_.
License
-------
Apache License, please see license file. Work is credited to both Alex
Kaszynski and Marius Johann.
.. _create a pull request: https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request
FAQs
Interfaces with keepa.com's API.
We found that keepa demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Research
The Socket Research Team breaks down a malicious wrapper package that uses obfuscation to harvest credentials and exfiltrate sensitive data.
Research
Security News
Attackers used a malicious npm package typosquatting a popular ESLint plugin to steal sensitive data, execute commands, and exploit developer systems.
Security News
The Ultralytics' PyPI Package was compromised four times in one weekend through GitHub Actions cache poisoning and failure to rotate previously compromised API tokens.