Barcode Lookup API in Python: Get Product Details from UPC, EAN, and ISBN Codes
Three cells in a spreadsheet are the whole dataset this guide needs. One is 3017620422003 copied off a jar. One is 9780747532699 copied off a used hardcover. The third is the word nutella. The Barcode Lookup API exposes a single operation, search-product-details. All three values go in as query. What comes back under data is not one object with optional fields — it is two shapes, and a miss uses the search shape even when you sent digits.
Sign in, copy a key from the dashboard, and keep it in OPENDATA_API_KEY on the server. Curl below uses YOUR_API_KEY. The key rides in the query string, so those URLs do not belong in tickets or browser apps. Opening this page or copying a snippet does not send a lookup.
One code on the desk
Start with the jar, because that is the shape most scan-to-add flows expect:
curl --get 'https://api.opendata-api.com/api/project/barcodes-lookup/search-product-details?key=YOUR_API_KEY' \
--data-urlencode 'query=3017620422003'
Leave page off. It belongs to search mode.
Transport is the first layer: HTTP 4xx/5xx means the call did not run. The second layer is the gateway envelope {code, message, data}. code 200 means the platform accepted the request. It does not mean a product was found. On a barcode hit, data holds a product object. On a barcode the catalog has never seen, data looks like a search miss: results is [] and nextPage is null. Branch on which key is present, not on HTTP 200.
The hardcover uses the same parameter. ISBN-10 and ISBN-13 are not a second endpoint:
curl --get 'https://api.opendata-api.com/api/project/barcodes-lookup/search-product-details?key=YOUR_API_KEY' \
--data-urlencode 'query=9780747532699'
UPC-A, EAN-13, JAN and ISBN all sit in query. product.barcode_formats is where the catalog tells you which forms it matched (ean_13, upc_a, isbn_10, isbn_13 as applicable).
A small Python guard is the whole barcode mode — unwrap the envelope, then ask for product:
import os
import requests
KEY = os.environ["OPENDATA_API_KEY"].strip()
URL = "https://api.opendata-api.com/api/project/barcodes-lookup/search-product-details"
def lookup(query):
resp = requests.get(URL, params={"key": KEY, "query": query}, timeout=30)
resp.raise_for_status() # HTTP layer: 4xx/5xx is transport or quota
envelope = resp.json()
if str(envelope.get("code")) != "200":
raise RuntimeError(envelope.get("message"))
data = envelope.get("data") or {}
product = data.get("product")
if isinstance(product, dict):
return product # barcode hit
return None # miss, or a search payload you did not unwrap here
What data.product actually contains
When product is present, walk it as a catalog card, not as a store shelf.
title and description are listing copy. They can be long, truncated, or oddly specific to one retailer condition — a book title may include used-grade tags in the string itself. category is a path array, broadest first (food might run Food, Beverages & Tobacco → Food Items → Dips & Spreads; a book Media → Books). Join it for a PIM path; do not assume a fixed depth.
brand and manufacturer are independent, and either can be null on an otherwise famous item. Do not fill a brand column from title without an explicit fallback rule.
attributes is usually a map: mpn, asin, size, dimensions, weight, sometimes model. Treat asin as enrichment when present, not as a UPC-to-ASIN converter. On some records the same field arrives as an empty array [] instead of {} — test for a dict before calling .get. features is a list of bullets for listing prefill, and it can be empty.
images is a list of image URLs. Search hits use singular image instead; that is a different object. author / artist show up on books and media; food records leave them null. nutrition_facts and ingredients are food-only and still often null. When nutrition_facts is present it may be a single string, not a keyed table — branch on type.
online_stores is an array of {name, price, url} when the catalog has offers. price is a display string with a currency mark, not a decimal in one currency. The field is also null on records that otherwise look complete. barcode_formats echoes the codes tied to this card.
Nothing in that list is required except that product itself is a dict. Prefill a receiving form from title, category, manufacturer and images when they exist; send the rest through a presence check.
When the same parameter becomes search
Type nutella instead of digits and the operation switches mode. There is no extra flag.
curl --get 'https://api.opendata-api.com/api/project/barcodes-lookup/search-product-details?key=YOUR_API_KEY' \
--data-urlencode 'query=nutella'
data now has results and nextPage. Each hit is a thin row: barcode, title, category, image, manufacturer, sometimes brand / author as nulls. It is not data.product. There is no attributes, no online_stores, no images array. If you need the rich card, take barcode from a hit and call again in barcode mode — that is a second request, not a field you missed.
nextPage is a cursor. Echo it as page. Values in this API often look like ordinary integers; still do not increment on your own, and do not send page on a barcode lookup.
curl --get 'https://api.opendata-api.com/api/project/barcodes-lookup/search-product-details?key=YOUR_API_KEY' \
--data-urlencode 'query=nutella' \
--data-urlencode 'page=2'
Stop when nextPage is null. Deduplicate across pages on barcode. A keyword page can be accessories that merely mention the term; search is not a GTIN resolver.
Sparse records and missing stores
Field depth follows how well the catalog knows the item, not how famous the brand is.
A beverage EAN can come back with a one-word title, brand null, online_stores null, and nutrition_facts as a packed string. A spread jar can come back with a long description, a full attributes map, several store offers — and still nutrition_facts: null, ingredients: null, brand: null. A book can carry author, cover images and a used-market online_stores list while attributes is [] and manufacturer is null.
For scan-to-add that means:
productmissing,resultsempty → not in the catalog. Writefound: false. Do not retry in a tight loop; HTTP 200 with an empty list is a business miss.productpresent,online_storesnull or empty → you have identity, not a comparison table.productpresent,attributesnot a dict → skip ASIN/MPN rather than crashing.- Food scan with no
nutrition_facts→ store the title and keep a hole for later; do not invent zeros.
CSV enrichment is the same walk over a column of codes: keep the original barcode, a found flag, and only the keys that survived the presence checks.
Do not treat this as live inventory
This JSON is a catalog snapshot. It is not on-hand quantity, not a shelf price in your currency, and not a promise the offer URL still sells that SKU.
Do not treat HTTP 200 or gateway code 200 as “we found it” — look for data.product. Do not pass page on a numeric barcode, or invent page numbers in search mode. Do not feed a search hit into a listing template that expects attributes, features and online_stores. Do not parse online_stores[].price as a float in one currency without stripping the symbol, or show those prices as “now”. Do not use attributes.asin as a guaranteed UPC→ASIN map. Do not retry empty results as if the transport failed. Do not put the platform key in a mobile scan app or a public repository; query URLs leak it.
Use the operation to prefill a receiving form, to attach a category path and images to a PIM row, or to collect candidate barcodes from a keyword. For stock counts, checkout prices and “is this in the warehouse”, keep your own system of record.