Open price engine API

The Openpricengine is a resource that provides you with real-time & historical food and groceries, restaurant and retail energy prices. The engine provides a simple set of end points that allow you to query a global database of items & prices easily. You can also make use of the Swagger UI to interact and learn more about our API.

openpricengine API follows the OpenAPI v3 specifications.

OPE Swagger UI Example Usecase

Version: 0.3
Developer: The openpricengine Team

Created: 27 November, 2021
Modified: 17 July, 2024

If you have any questions that are beyond the scope of this help file, Please feel free to email via openpricengine@gmail.com.

Authentication

The openpricengine API uses API keys to authenticate requests. You can view and manage your API keys in Portal.

Create an API key in order to send requests to the openpricengine API. To create a key you need to use your email and a API key name.

Alternatively, you can refere to the Docs page to manage keys via the endpoints

Note: This API Key is free and valid for 2 weeks.

API base URL

The base URL you use to interact with the openpricengine api at the current version.

Your Base URL

This base URL will be used in the API documentation request examples.

Store Database

Country	Stores
Australia	FriendlyGrocerwaverton
United Kingdom	London Groceries, Abel and Cole, Planet Organic, AtoZgrocersonline
United States of America	Gusto Grocery, parthenon foods, Supermarketitaly
South Africa	Pnp, Spar, Pnpliqour, Woolworths, Fuel, House prices
Zimbabwe	TM Pick n Pay, Spar
Brazil	Bretas, Hortifruti
Denmark	Bretas, Hortifruti
Sweden	Delitea, Mathem
UAE	Choithrams
Qatar	Family Food centre, GrandHyper
Malaysia	Redtick, Superbuy
Lebanon	Click o mart
Netherlands	Tawfeer
Germany	Aldi
Oman	Muscat Food
Saudi Arabia	Grocery JY

Request example

curl -X 'GET' 'https://openpricengine.com/api/v0.3/stores/countries' -H 'accept: application/json' -H 'Authorization: api-key'

Example Response

The delivered price data is by default returned in a standard JSON format and can easily be reparsed in any programming language.

Example Response: See below an example of an API response that provides information about a specific shops product. The returned response has a information about the product in addition to the price and Date.

								  
          [
                  {
                    "Country": "England",
                    "Continent": "Europe",
                    "Currency": "GBP",
                    "Store": "London Grocery",
                    "Category": "Food and Groceries",
                    "Product Name": "Halal Chicken Feet 500gr",
                    "Product URL": "https://londongrocery.net/collections/chicken/products/chicken-feet",
                    "Price over time": [
                      {
                        "Date": "2023-07-20",
                        "Price": 7.9
                      }
                  ]
                }
              ]

Food & Groceries

Get stores

Get the stores availabe.

GET

/api/v0.3/stores

Returns a list of all the stores. No Parameters.

curl -X 'GET' 'https://openpricengine.com/api/v0.3/stores' -H 'accept: application/json' -H 'Authorization: api-key'

Get store short names

Get the short names you can use to send requests

GET

/api/v0.3/short_names

Returns a json of all the stores and their short names. No Parameters.

Get store countries

Get the stores available in a country

GET

/api/v0.3/stores/countries

Returns a json of all countries tracked by the engine and the respective stores.

								  
         {
          "All": [
            "All"
          ],
          "Australia": [
            "Friendly Grocerwaverton"
          ],
          "United Kingdom": [
            "London Groceries",
            "Abel and Cole",
            "Planet Organic",
            "AtoZgrocersonline"
          ],
          "United States of America": [
            "Gusto Grocery",
            "parthenon foods",
            "Supermarketitaly"
          ],
          ...
          }

Get stores from country

Get a list of stores from a country

GET

/api/v0.3/countries/query?country={country_code}

Returns a list of all the stores from a country.

Parameters

Parameter	Type	Example Value
country_code	String	ZA

Get store's currency

Get a json of stores and their respective currencies

GET

/api/v0.3/currency

Returns a json of currencies.

Get commercial information about a store

Get a json of a stores commercial information

GET

/api/v0.3/{store}

Get product names from a store

Returns a json of products from a store.
Takes in a List of strings

GET

/api/v0.3/stores/products?store={store_name}

Python Example


  import requests

  url = 'https://openpricengine.com/api/v0.3/stores/products'
  headers = {
      'accept': 'application/json',
      'Authorization': 'api-key'
  }
  params = {
      'stores': ['pnp', 'spar']
  }
  
  response = requests.get(url, headers=headers, params=params)
  print(response.json())

Get todays prices

Returns a json of products and todays prices

GET

/api/v0.3/{STORE_NAME}/products/today?productname={PRODUCT_NAME}& currency={CURRENCY_CODE}

Returns a list of all the stores from a country.

Parameters

Parameter	Type	Example Value
store	String	woolworths
productname	String	milk
currency	String	ZAR or Deafult

Get historical prices

Returns a list[dict] of historical prices

GET

/api/v0.3/{STORE_NAME}/products/query?productname={PRODUCT_NAME}& range={DATE_RANGE}& currency={CURRENCY_CODE}

Returns a list of all the stores from a country.

Parameters

Parameter	Type	Example Value
store	String	woolworths
productname	String	milk
range	String	2024-05-25to2024-06-24
currency	String	USD or Default

Python Example

				
        import requests

        url = 'https://openpricengine.com/api/v0.3/woolworths/products/query'
        headers = {
            'accept': 'application/json',
            'Authorization': 'api-key'
        }
        params = {
            'productname': 'milk',
            'range': '2024-06-25to2024-07-26',
            'currency': 'Default'
        }
        
        response = requests.get(url, headers=headers, params=params)
        
        
        print(response.json())

Get prices from multiple stores

Returns a list[dict] of historical prices from multiple stores

GET

/api/v0.3/all/products/query?stores={STORE_NAMES}& productname={PRODUCT_NAME}& range={DATE_RANGE}& currency={CURRENCY_CODE}

Returns a list of all the stores from a country.

Parameters

Parameter	Type	Example Value
stores	list	['woolworths','London Grocer']
productname	String	milk
range	String	2024-05-25to2024-06-24
currency	String	USD or Default

Python Example

				
        import requests
        
        url = 'https://openpricengine.com/api/v0.3/all/query'
        headers = {
            'accept': 'application/json',
            'Authorization': 'api-key'
        }
        
        # Define the parameters
        params = {
            'stores': ['woolworths', 'London Grocer'],
            'productname': 'milk',
            'range': '2024-06-25to2024-06-26',
            'currency': 'Default'
        }
        
        response = requests.get(url, headers=headers, params=params)

        print(response.json())

Restaurants

Restaurant Database

Country	No. Restaurants
Australia	100
United Kingdom	181
United States of America	135
South Africa	39
Canada	228
Singapore	118
Philippines	138
India	56

Example Response

				
             [
              {
                "Country": "South Africa",
                "Continent": "Africa",
                "Currency": "ZAR",
                "Store": "mcdonalds-menu",
                "Category": "Beef",
                "Product Name": "big mac",
                "Price over time": [
                  {
                    "Date": "2024-06-30",
                    "Price": 78.4
                  }
                ]
              },
              {
                "Country": "Indonesia",
                "Continent": "Asia",
                "Currency": "IDR",
                "Store": "mcdonalds-menu",
                "Category": "A La Carte & Paket",
                "Product Name": "big mac",
                "Price over time": [
                  {
                    "Date": "2024-06-30",
                    "Price": "p37.700"
                  }
                ]
              },
              ...

Get restaurants info

Get Restaurants Info

GET

/api/v0.3/restaurants/info

Returns a list[dict] of restaurants tracked. No Parameters.

curl -X 'GET' 'https://openpricengine.com/api/v0.3/restaurants/info' -H 'accept: application/json' -H 'Authorization: api-key'

Get restaurant countries

Get the countries where restaurants are tracked

GET

/api/v0.3/restaurants/countries

Returns a json of countries and country codes you can use to search. No Parameters.

Get restaurant names

Returns a dict of restaurants from the queried country

GET

/api/v0.3/restaurants/Restaurant_names/query?country={COUNTRY_NAME}

Returns a json with the countries and their restaurants.

Parameters

Parameter	Type	Example Value
Country	List	['za','usa']

Python Example

				
        import requests
        
        url = 'https://openpricengine.com/api/v0.3/restaurants/Restaurant_names'
        headers = {
            'accept': 'application/json',
            'Authorization': 'api-key'
        }
        
        # Define the parameters
        params = {
            'country': ['za', 'usa'],
        }
        
        response = requests.get(url, headers=headers, params=params)

        print(response.json())

Get Menu items

Returns a dict with a lists of menu items from the queried restaurant

GET

/api/v0.3/restaurants/menu_items?menu_names={RESTAURANT_NAME}&country={COUNTRY_NAME}

Returns a json with the restaurants and their food items.

Parameters

Parameter	Type	Example Value
menu_names	List	['kfc','mcdonalds']
Country	List	['za']

Example Response

				
        {
        "kfc-menu": [
          "snack burger",
          "crunch burger",
          "pops",
          "dunked pops",
          "regular chips",
          "wrapsta",
          "large pops",
          "nugget box buddy",
          "all star box with buddy bottle"
          ...
          ]
        }

Get menu item prices

Returns a dict with a lists of menu items from the queried restaurant

GET

api/v0.3/restaurants/menu/items?menu_item={FOOD_ITEM}&menu_names={RESTAURANT_NAME}&country={COUNTRY_NAME}& currency=Default

Returns a List[dict] with the restaurants and their food items with prices.

Parameters

Parameter	Type	Example Value
menu_names	List	['kfc']
menu_item	List	['wings','wrapsta']
Country	List	['za']
Currency	String	zar

Python Example

				
        import requests
        
        url = 'https://openpricengine.com/api/v0.3/restaurants/menu/items'
        headers = {
            'accept': 'application/json',
            'Authorization': 'api-key'
        }
        
        # Define the parameters
        params = {
            'menu_item': ['wings','wrapsta'],
            'menu_names': ['kfc']
            'country': ['za'],
            'currency':'Default'
        }
        
        response = requests.get(url, headers=headers, params=params)

        print(response.json())

Get any food item prices

Returns a dict with a lists of food items from all restaurants

GET

api/v0.3/restaurants/menu/all_menus?food_item={FOOD_ITEM} & currency=Default

Returns a List[dict] with all food items queried with prices.

Parameters

Parameter	Type	Example Value
food_item	List	['burger']
Currency	String	zar

Python Example

				
        import requests
        
        url = 'https://openpricengine.com/api/v0.3/restaurants/menu/all_menus'
        headers = {
            'accept': 'application/json',
            'Authorization': 'api-key'
        }
        
        # Define the parameters
        params = {
            'food_item': ['burger'],
            'currency':'Default'
        }
        
        response = requests.get(url, headers=headers, params=params)

        print(response.json())

Retail Energy

Energy Database

Country	Currency
South Africa	ZAR
Zimbabwe	ZWL
Nigeria	NGN
Egypt	EGP
Kenya	KES
Morocco	MAD
Ghana	GHS
Australia	AUD
New Zealand	NZD
Fiji	FJD
Papua New Guinea	PGK
Solomon Islands	SBD
China	CNY
India	INR
Tunisia	TND
Japan	JPY
South Korea	KRW
Indonesia	IDR
Germany	EUR
France	EUR
United Kingdom	GBP
Italy	EUR
Spain	EUR
Netherlands	EUR
Sweden	SEK
Belgium	EUR
USA	USD
Canada	CAD
Mexico	MXN
Cuba	CUP
Guatemala	GTQ
Brazil	BRL
Argentina	ARS
Chile	CLP
Colombia	COP
Peru	PEN

Example Response

				
        {
          "source": "https://www.globalpetrolprices.com",
          "description": "This JSON provides information about energy prices for various countries.",
          "data_available": {
            "countries": [
              "South Africa",
              "Zimbabwe",
              "Nigeria",
              ...
              "Indonesia",
              "Germany",
              "France",
              "United Kingdom",
              "Italy",
              "Spain",
              "Netherlands",
              "Sweden",
              "Belgium",
              "USA"
            ],
            "energy_types": [
              "electricity",
              "gasoline",
              "natural gas"
            ],
            "years_available": [
              2024
            ],
            "months_available": [
              "July 2024"
            ]
          }
        }

Get energy prices

Returns a dict of countries queried and their energy prices

GET

api/v0.3/energy/search?countries={COUNTRY_NAME}& year={YEAR}& month={MONTH}

Returns a dict with energy prices.

Parameters

Parameter	Type	Example Value
countries	String	south africa
year	String	2024
month	String	July

Python Example

				
        import requests
        
        url = 'https://openpricengine.com/api/v0.3/energy/search'
        headers = {
            'accept': 'application/json',
            'Authorization': 'api-key'
        }
        
        # Define the parameters
        params = {
            'countries':'south africa',
            'year': '2024',
            'month':'July'
        }
        
        response = requests.get(url, headers=headers, params=params)

        print(response.json())

Possible HTTP response status codes

This is a dictionary of some of the possible HTTP responses you can get when interacting with the engine.

200 Ok - Successful response
204 No Content - There is no content to send for this request, but the headers may be useful. The user agent may update its cached headers for this resource with the new ones.
300 Multiple Choices - The request has more than one possible response. The user agent or user should choose one of them. (There is no standardized way of choosing one of the responses, but HTML links to the possibilities are recommended so the user can pick.)
301 Moved Permanently - The URL of the requested resource has been changed permanently. The new URL is given in the response.
302 Found - This response code means that the URI of requested resource has been changed temporarily. Further changes in the URI might be made in the future. Therefore, this same URI should be used by the client in future requests.
303 See Other - The server sent this response to direct the client to get the requested resource at another URI with a GET request.
400 Bad Request - The server could not understand the request due to invalid syntax.
401 Unauthorized - The server could not understand the request due to invalid syntax.
402 Payment Required - This response code is reserved for future use. The initial aim for creating this code was using it for digital payment systems, however this status code is used very rarely and no standard convention exists.
403 Forbidden - The client does not have access rights to the content; that is, it is unauthorized, so the server is refusing to give the requested resource. Unlike 401 Unauthorized, the client's identity is known to the server.
404 Not Found - The server can not find the requested resource. In the browser, this means the URL is not recognized. In an API, this can also mean that the endpoint is valid but the resource itself does not exist. Servers may also send this response instead of 403 Forbidden to hide the existence of a resource from an unauthorized client. This response code is probably the most well known due to its frequent occurrence on the web.
405 Method Not Allowed - The request method is known by the server but is not supported by the target resource. For example, an API may not allow calling DELETE to remove a resource.
406 Not Acceptable - This response is sent when the web server, after performing server-driven content negotiation, doesn't find any content that conforms to the criteria given by the user agent.
414 URI Too LongThe URI requested by the client is longer than the server is willing to interpret.
422 Unprocessable EntityThe request was well-formed but was unable to be followed due to semantic errors.
429 Too Many RequestsThe user has sent too many requests in a given amount of time ("rate limiting").
500 Internal Server ErrorThe server has encountered a situation it does not know how to handle.
501 Not ImplementedThe request method is not supported by the server and cannot be handled. The only methods that servers are required to support (and therefore that must not return this code) are GET and HEAD.
502 Bad GatewayThis error response means that the server, while working as a gateway to get a response needed to handle the request, got an invalid response.

FAQ

A FAQ is a list of frequently asked questions (FAQs) and answers on a particular topic.

How long is the price date range?

Its difficult to say the exact range of price data we have. Some stores we have only recently started tracking, some we have over 8 months of data and other prices such as fuel we have over 10 years of data. Some stores we have lost the ability to track due to changes in their website structure. However, we are constantly adding new stores and products to our database. and doing our best to keep the data as structured as possible.

Is the API secure?

At this point all our data is free and accessible by anyone and there are no post requests made to our api that are a priority for us to secure.

What are some of the features to be implemented in the next version?

In the next version v0.3, we plan to increase the number of products as well as shops we track.

Is this API legal?

We publish this data strictly for the purpose of education, marketing and information. Our API cannot be used to harm any users or institutions which we collect this data from. Our API has no ability to influence the functionality of any website, application or outlet we recieve the data from.

Who owns and develops this API?

This API is currently owned and liscensed by the TechlabSoftwares IT based in South Africa.

Support

This API is now owned by ToofourproductsZA based in Southren Africa. All prices will be maintained and updated daily by our team of open source contributors.

Note: While we aim to provide the best support possible, please keep in mind that we run a small but talented team with limited resources.

Changelog

See what's new added, changed, fixed, improved or updated in the latest versions.

Version 0.3 (01 Aug, 2024)

Added https secure connection
Added New JSON format
Fixed Some minor bugs for browser compatibility
Added Restaurants
Added Energy
Updated New database attributes
Fixed Some minor bugs for responsive
Updated User interface

Version 0.4 (01 January, 2025)

Planned Release