keepa 1.3.2

Interfaces with keepa.com

This Python module 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.

See API pricing at Keepa API

Documentation can be found on readthedocs at keepa Documentation.

Requirements

Module is compatible with Python >= 3.6 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: python setup.py install or pip install .

Brief Example

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

Product Price Plot

Product Offers Plot

Brief Example using async

Here’s an example of obtaining a product and plotting its price and offer history using the async interface:

import keepa

# establish interface with keepa (this is not a real key)
mykey = '0000000000000000000000000000000000000000000000000000000000000000'
api = await keepa.AsyncKeepa.create(mykey)

# plot product request
request = 'B0088PUEPK'
products = await api.query(request)
product = products[0]
keepa.plot_product(product)

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)

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 api_backend.

License

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