| Name | keepa JSON |
| Version |
1.3.11
JSON |
| download |
| home_page | None |
| Summary | Interfaces with keepa.com's API. |
| upload_time | 2024-10-30 18:03:51 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.9 |
| license | None |
| keywords |
keepa
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
Python keepa Client Library
===========================
.. 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/>`_.
Requirements
------------
This library is compatible with Python >= 3.8 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 <https://keepa.com/#!api>`_.
Installation
------------
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 .
Brief Example
-------------
.. 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
Brief Example using async
-------------------------
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'
Detailed Examples
-----------------
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
Raw data
{
"_id": null,
"home_page": null,
"name": "keepa",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "keepa",
"author": null,
"author_email": "Alex Kaszynski <akascap@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/96/db/107fa5fe4bbd1190a14d2f892382adf5a4e119c12f94d0697c3e535f0ddf/keepa-1.3.11.tar.gz",
"platform": null,
"description": "Python keepa Client Library\n===========================\n\n.. image:: https://img.shields.io/pypi/v/keepa.svg?logo=python&logoColor=white\n :target: https://pypi.org/project/keepa/\n\n.. image:: https://github.com/akaszynski/keepa/actions/workflows/testing-and-deployment.yml/badge.svg\n :target: https://github.com/akaszynski/keepa/actions/workflows/testing-and-deployment.yml\n\n.. image:: https://readthedocs.org/projects/keepaapi/badge/?version=latest\n :target: https://keepaapi.readthedocs.io/en/latest/?badge=latest\n :alt: Documentation Status\n\n.. image:: https://codecov.io/gh/akaszynski/keepa/branch/main/graph/badge.svg\n :target: https://codecov.io/gh/akaszynski/keepa\n\n.. image:: https://app.codacy.com/project/badge/Grade/9452f99f297c4a6eac14e2d21189ab6f\n :target: https://www.codacy.com/gh/akaszynski/keepa/dashboard?utm_source=github.com&utm_medium=referral&utm_content=akaszynski/keepa&utm_campaign=Badge_Grade\n\n\nThis Python library allows you to interface with the API at `Keepa\n<https://keepa.com/>`_ to query for Amazon product information and\nhistory. It also contains a plotting module to allow for plotting of\na product.\n\nSee API pricing at `Keepa API <https://keepa.com/#!api>`_.\n\nDocumentation can be found on readthedocs at `keepa Documentation <https://keepaapi.readthedocs.io/en/latest/>`_.\n\n\nRequirements\n------------\nThis library is compatible with Python >= 3.8 and requires:\n\n- ``numpy``\n- ``aiohttp``\n- ``matplotlib``\n- ``tqdm``\n\nProduct history can be plotted from the raw data when ``matplotlib``\nis installed.\n\nInterfacing with the ``keepa`` requires an access key and a monthly\nsubscription from `Keepa API <https://keepa.com/#!api>`_.\n\nInstallation\n------------\nModule can be installed from `PyPi <https://pypi.org/project/keepa/>`_ with:\n\n.. code::\n\n pip install keepa\n\n\nSource code can also be downloaded from `GitHub\n<https://github.com/akaszynski/keepa>`_ and installed using::\n\n cd keepa\n pip install .\n\n\nBrief Example\n-------------\n.. code:: python\n\n import keepa\n accesskey = 'XXXXXXXXXXXXXXXX' # enter real access key here\n api = keepa.Keepa(accesskey)\n\n # Single ASIN query\n products = api.query('B0088PUEPK') # returns list of product data\n\n # Plot result (requires matplotlib)\n keepa.plot_product(products[0])\n\n.. figure:: https://github.com/akaszynski/keepa/raw/main/docs/source/images/Product_Price_Plot.png\n :width: 500pt\n\n Product Price Plot\n\n.. figure:: https://github.com/akaszynski/keepa/raw/main/docs/source/images/Product_Offer_Plot.png\n :width: 500pt\n\n Product Offers Plot\n\n\nBrief Example using async\n-------------------------\nHere's an example of obtaining a product and plotting its price and\noffer history using the ``keepa.AsyncKeepa`` class:\n\n.. code:: python\n\n >>> import asyncio\n >>> import keepa\n >>> product_parms = {'author': 'jim butcher'}\n >>> async def main():\n ... key = '<REAL_KEEPA_KEY>'\n ... api = await keepa.AsyncKeepa().create(key)\n ... return await api.product_finder(product_parms)\n >>> asins = asyncio.run(main())\n >>> asins\n ['B000HRMAR2',\n '0578799790',\n 'B07PW1SVHM',\n ...\n 'B003MXM744',\n '0133235750',\n 'B01MXXLJPZ']\n\nQuery for product with ASIN ``'B0088PUEPK'`` using the asynchronous\nkeepa interface.\n\n.. code:: python\n\n >>> import asyncio\n >>> import keepa\n >>> async def main():\n ... key = '<REAL_KEEPA_KEY>'\n ... api = await keepa.AsyncKeepa().create(key)\n ... return await api.query('B0088PUEPK')\n >>> response = asyncio.run(main())\n >>> response[0]['title']\n 'Western Digital 1TB WD Blue PC Internal Hard Drive HDD - 7200 RPM,\n SATA 6 Gb/s, 64 MB Cache, 3.5\" - WD10EZEX'\n\n\nDetailed Examples\n-----------------\nImport interface and establish connection to server\n\n.. code:: python\n\n import keepa\n accesskey = 'XXXXXXXXXXXXXXXX' # enter real access key here\n api = keepa.Keepa(accesskey)\n\n\nSingle ASIN query\n\n.. code:: python\n\n products = api.query('059035342X')\n\n # See help(api.query) for available options when querying the API\n\n\nYou can use keepa witch async / await too\n\n.. code:: python\n\n import keepa\n accesskey = 'XXXXXXXXXXXXXXXX' # enter real access key here\n api = await keepa.AsyncKeepa.create(accesskey)\n\n\nSingle ASIN query (async)\n\n.. code:: python\n\n products = await api.query('059035342X')\n\n\nMultiple ASIN query from List\n\n.. code:: python\n\n asins = ['0022841350', '0022841369', '0022841369', '0022841369']\n products = api.query(asins)\n\nMultiple ASIN query from numpy array\n\n.. code:: python\n\n asins = np.asarray(['0022841350', '0022841369', '0022841369', '0022841369'])\n products = api.query(asins)\n\nProducts 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>`_.\n\n.. code:: python\n\n # Available keys\n print(products[0].keys())\n\n # Print ASIN and title\n print('ASIN is ' + products[0]['asin'])\n print('Title is ' + products[0]['title'])\n\nThe raw data is contained within each product result. Raw data is stored as a dictionary with each key paired with its associated time history.\n\n.. code:: python\n\n # Access new price history and associated time data\n newprice = products[0]['data']['NEW']\n newpricetime = products[0]['data']['NEW_time']\n\n # Can be plotted with matplotlib using:\n import matplotlib.pyplot as plt\n plt.step(newpricetime, newprice, where='pre')\n\n # Keys can be listed by\n print(products[0]['data'].keys())\n\nThe product history can also be plotted from the module if ``matplotlib`` is installed\n\n.. code:: python\n\n keepa.plot_product(products[0])\n\nYou 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.\n\n.. code:: python\n\n products = api.query(asins, offers=20)\n product = products[0]\n offers = product['offers']\n\n # each offer contains the price history of each offer\n offer = offers[0]\n csv = offer['offerCSV']\n\n # convert these values to numpy arrays\n times, prices = keepa.convert_offer_history(csv)\n\n # for a list of active offers, see\n indices = product['liveOffersOrder']\n\n # with this you can loop through active offers:\n indices = product['liveOffersOrder']\n offer_times = []\n offer_prices = []\n for index in indices:\n csv = offers[index]['offerCSV']\n times, prices = keepa.convert_offer_history(csv)\n offer_times.append(times)\n offer_prices.append(prices)\n\n # you can aggregate these using np.hstack or plot at the history individually\n import matplotlib.pyplot as plt\n for i in range(len(offer_prices)):\n plt.step(offer_times[i], offer_prices[i])\n plt.show()\n\nIf you plan to do a lot of simulatneous query, you might want to speedup query using\n``wait=False`` arguments.\n\n.. code:: python\n\n products = await api.query('059035342X', wait=False)\n\n\nBuy Box Statistics\n~~~~~~~~~~~~~~~~~~\nTo load used buy box statistics, you have to enable ``offers``. This example\nloads in product offers and converts the buy box data into a\n``pandas.DataFrame``.\n\n.. code:: pycon\n\n >>> import keepa\n >>> key = '<REAL_KEEPA_KEY>'\n >>> api = keepa.Keepa(key)\n >>> response = api.query('B0088PUEPK', offers=20)\n >>> product = response[0]\n >>> buybox_info = product['buyBoxUsedHistory']\n >>> df = keepa.process_used_buybox(buybox_info)\n datetime user_id condition isFBA\n 0 2022-11-02 16:46:00 A1QUAC68EAM09F Used - Like New True\n 1 2022-11-13 10:36:00 A18WXU4I7YR6UA Used - Very Good False\n 2 2022-11-15 23:50:00 AYUGEV9WZ4X5O Used - Like New False\n 3 2022-11-17 06:16:00 A18WXU4I7YR6UA Used - Very Good False\n 4 2022-11-17 10:56:00 AYUGEV9WZ4X5O Used - Like New False\n .. ... ... ... ...\n 115 2023-10-23 10:00:00 AYUGEV9WZ4X5O Used - Like New False\n 116 2023-10-25 21:14:00 A1U9HDFCZO1A84 Used - Like New False\n 117 2023-10-26 04:08:00 AYUGEV9WZ4X5O Used - Like New False\n 118 2023-10-27 08:14:00 A1U9HDFCZO1A84 Used - Like New False\n 119 2023-10-27 12:34:00 AYUGEV9WZ4X5O Used - Like New False\n\nContributing\n------------\nContribute to this repository by forking this repository and installing in\ndevelopment mode with::\n\n git clone https://github.com/<USERNAME>/keepa\n pip install -e .[test]\n\nYou can then add your feature or commit your bug fix and then run your unit\ntesting with::\n\n pytest\n\nUnit testing will automatically enforce minimum code coverage standards.\n\nNext, to ensure your code meets minimum code styling standards, run::\n\n pre-commit run --all-files\n\nFinally, `create a pull request`_ from your fork and I'll be sure to review it.\n\n\nCredits\n-------\nThis Python module, written by Alex Kaszynski and several contribitors, is\nbased on Java code written by Marius Johann, CEO Keepa. Java source is can be\nfound at `keepacom/api_backend <https://github.com/keepacom/api_backend/>`_.\n\n\nLicense\n-------\nApache License, please see license file. Work is credited to both Alex\nKaszynski and Marius Johann.\n\n\n.. _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\n\n",
"bugtrack_url": null,
"license": null,
"summary": "Interfaces with keepa.com's API.",
"version": "1.3.11",
"project_urls": {
"Documentation": "https://keepaapi.readthedocs.io/en/latest/",
"Source": "https://github.com/akaszynski/keepa"
},
"split_keywords": [
"keepa"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "107f55d9f3ebdfada044bef93ba2224aef422b0a997e06c9347c4e57181dbd5b",
"md5": "188d0437282be95e5caaf2ccab42951b",
"sha256": "862a180c8e6e4efc2c32cc8690aaba038bbd45d03cb27acf3a93b11f9ba42243"
},
"downloads": -1,
"filename": "keepa-1.3.11-py3-none-any.whl",
"has_sig": false,
"md5_digest": "188d0437282be95e5caaf2ccab42951b",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 33342,
"upload_time": "2024-10-30T18:03:49",
"upload_time_iso_8601": "2024-10-30T18:03:49.949937Z",
"url": "https://files.pythonhosted.org/packages/10/7f/55d9f3ebdfada044bef93ba2224aef422b0a997e06c9347c4e57181dbd5b/keepa-1.3.11-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "96db107fa5fe4bbd1190a14d2f892382adf5a4e119c12f94d0697c3e535f0ddf",
"md5": "66ff755101663f5881293e82175e0518",
"sha256": "3a567dc5684027037da214a761f9e5ab73ababd4747b41919a3d1ee4ecc006b0"
},
"downloads": -1,
"filename": "keepa-1.3.11.tar.gz",
"has_sig": false,
"md5_digest": "66ff755101663f5881293e82175e0518",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 36449,
"upload_time": "2024-10-30T18:03:51",
"upload_time_iso_8601": "2024-10-30T18:03:51.960772Z",
"url": "https://files.pythonhosted.org/packages/96/db/107fa5fe4bbd1190a14d2f892382adf5a4e119c12f94d0697c3e535f0ddf/keepa-1.3.11.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-30 18:03:51",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "akaszynski",
"github_project": "keepa",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "keepa"
}
