Installation

First, you’ll need to install trundlerpy from PyPI.

pip3 install trundlerpy

If you want to keep up to date with the latest package developments, you can also install trundlerpy directly from GitHub.

pip3 install git+https://github.com/datawookie/trundlerpy

Authenticating

It’s a good idea to store your API key in an environment variable rather than hard-coded into a script.

import os

trundler_key = os.getenv('TRUNDLER_KEY')

Now, import the package and set your API key.

from trundlerpy import Trundler

# Set the API Key
tr = Trundler(key = trundler_key)

Retailers

You can use retailer() to return a Pandas DataFrame of retailers.

# Get retailers
retailer = tr.retailer()

# View the first 10 retailers
retailer.head(10)[["retailer_id", "retailer", "retailer_url", "currency"]]

   retailer_id          retailer                      retailer_url currency
0            1  EEM Technologies  https://www.eemtechnologies.com/      USD
1            2            Clicks             https://clicks.co.za/      ZAR
2            3           Dischem        https://www.dischem.co.za/      ZAR
3            4              Game           https://www.game.co.za/      ZAR
4            5        Woolworths     https://www.woolworths.co.za/      ZAR
5            6   Fortnum & Mason  https://www.fortnumandmason.com/      GBP
6            7        John Lewis        https://www.johnlewis.com/      GBP
7            8   Marks & Spencer  https://www.marksandspencer.com/      GBP
8            9       Pick 'n Pay            https://www.pnp.co.za/      ZAR
9           10             Makro          https://www.makro.co.za/      ZAR

You can use the currency field to focus on retailers from specific countries.

# Get South African retailers
retailer.loc[retailer.currency=='ZAR'].head(5)

   retailer_id     retailer                   retailer_url currency  visible
1            2       Clicks          https://clicks.co.za/      ZAR     True
2            3      Dischem     https://www.dischem.co.za/      ZAR     True
3            4         Game        https://www.game.co.za/      ZAR     True
4            5   Woolworths  https://www.woolworths.co.za/      ZAR     True
8            9  Pick 'n Pay         https://www.pnp.co.za/      ZAR     True

Products

The retailer_products() method yields a DataFrame with the products for a specific retailer, where each product is assigned a name, brand, model, SKU and barcode (if available).

# View first 5 products at a specific retailer
tr.retailer_products(5)[["product_id", "product", "sku"]].head(5)

   product_id                                     product            sku
0     2908316  BENJI + MOON Small Ceramic Pet Bowl - GREY  6009217220700
1     2908331                    Camp Braai Grid - SILVER  6009189947247
2     2908465                   Roaster with Lid - SILVER  6009182727549
3     2908466            Roasting Dish with Rack - SILVER  6009182727532
4     2908469                 Leather Braai Glove - BLACK  6009207271408

Products can also be filtered by name and brand.

product = tr.retailer_products(5, product = "coffee", brand = "nespresso").head(5)

To get details on a specific product, use the product_details() method and the product ID.

# Get details on an specific product
tr.product(711497)[["product_id", "product", "sku"]]

   product_id                                       product            sku
0      711497  Instant Coffee Café Gold Italian Sachets 50g  6009204582774

Prices

Finally, you can use product_prices() to get the price history for a particular product using its product ID.

# Get the price history for a specific product
tr.product_prices(711497).head(10)

   product_id                       time  price price_promotion available
0      711497  2020-05-13T14:46:55+00:00  53.99            None      None
1      711497  2020-05-12T10:41:52+00:00  53.99            None      None
2      711497  2020-05-11T18:15:54+00:00  53.99            None      None
3      711497  2020-05-10T23:25:28+00:00  49.99            None      None
4      711497  2020-05-09T13:03:59+00:00  49.99            None      None
5      711497  2020-05-08T11:50:41+00:00  49.99            None      None
6      711497  2020-05-07T14:16:00+00:00  49.99            None      None
7      711497  2020-05-06T15:35:29+00:00  49.99            None      None
8      711497  2020-05-05T14:33:10+00:00  49.99            None      None
9      711497  2020-05-04T14:58:00+00:00  49.99            None      None