Waitrose APIwaitrose.com ↗
Search the Waitrose & Partners grocery catalog, retrieve full product details, look up by barcode, and get autocomplete suggestions via 4 structured endpoints.
What is the Waitrose API?
The Waitrose API gives developers access to 4 endpoints covering the Waitrose & Partners online grocery catalog. Use search_products to run full-text queries that return pricing, brand, pack size, review summaries, promotion IDs, and category data across thousands of SKUs. get_product and search_by_barcode expose deeper fields including recyclability information, multi-resolution images, shelf life in days, and barcode arrays for any matched product.
curl -X GET 'https://api.parse.bot/scraper/19106a7a-0ebc-433a-8edc-8a83f701917d/search_products?page=1&size=5&query=coffee' \ -H 'X-API-Key: $PARSE_API_KEY'
Typed, relational, agent-ready
A generated client with real types, enums, and the links between objects — the structure a flat JSON response can't carry. Autocompletes in your editor and reads cleanly to coding agents.
- Fully typed · autocompletes
- Objects link to objects
- Typed errors & pagination
Typed Python client. Set up the SDK in your uv project, then pull this API’s typed client:
uv add parse-sdk uv run parse init uv run parse add --marketplace waitrose-com-api
uv run parse add --marketplace pulls a pinned snapshot of this canonical API — it won’t change underneath you. To customize it, subscribe and swap to your own copy.
"""Walkthrough: Waitrose Products SDK — bounded, re-runnable; every call capped."""
from parse_apis.Waitrose_Products_API import Waitrose, ProductNotFound
client = Waitrose()
# Get autocomplete suggestions for a prefix
suggestion = client.products.suggest(term="cof")
print(suggestion.term, suggestion.search_engine)
for s in suggestion.suggestions[:3]:
print(s)
# Search for products with pagination
for product_summary in client.products.search(query="coffee beans", size=5, limit=3):
print(product_summary.name, product_summary.price, product_summary.brand)
print(product_summary.reviews.average_rating, product_summary.reviews.review_count)
# Look up a product by barcode/line number
try:
full = client.products.find_by_barcode(barcode="481037")
print(full.name, full.price, full.brand)
print(full.description[:80])
print(full.bar_codes)
for cat in full.categories:
print(cat.id, cat.name)
except ProductNotFound as e:
print(f"not found: {e.product_id}")
# Drill into a search result's full details
item = client.products.search(query="organic milk", limit=1).first()
if item:
try:
detail = item.details()
print(detail.name, detail.storage_instruction)
print(detail.images.extra_large)
print(detail.weights.price_per_uom_qualifier)
except ProductNotFound as e:
print(f"gone: {e.product_id}")
print("exercised: products.search, products.suggest, products.find_by_barcode, ProductSummary.details")
Full-text search over Waitrose product catalog. Returns paginated results ordered by relevance. Each result includes pricing, brand, size, review summary, categories, and active promotion IDs. Pagination is page-based starting at 1; the server returns up to size items per page. Sponsored items appear alongside organic results with a flag.
| Param | Type | Description |
|---|---|---|
| page | integer | Page number for pagination (1-based). |
| size | integer | Number of results per page. |
| queryrequired | string | Search term for finding products. |
{
"type": "object",
"fields": {
"page": "integer - current page number",
"size": "integer - page size used",
"query": "string - the search term used",
"products": "array of product summaries with id, line_number, name, brand, size, price, price_per_unit, thumbnail, reviews, categories, promotions, sponsored",
"total_results": "integer - total number of matching products"
},
"sample": {
"data": {
"page": 1,
"size": 5,
"query": "coffee",
"products": [
{
"id": "981929-1-2",
"name": "Grind Craft Instant Coffee Smooth Barista Blend",
"size": "90g",
"brand": "Grind",
"price": "£6.80",
"reviews": {
"reviewCount": 20,
"averageRating": 4.4
},
"sponsored": true,
"thumbnail": "https://ecom-su-static-prod.wtrecom.com/images/products/9/LN_981929_BP_9.jpg",
"categories": [
{
"id": "10051",
"name": "Groceries"
}
],
"promotions": [],
"line_number": "981929",
"price_per_unit": "£75.56/kg"
}
],
"total_results": 380
},
"status": "success"
}
}About the Waitrose API
Product Search and Pagination
The search_products endpoint accepts a query string and returns paginated results (page-based, 1-indexed) with a configurable size parameter. Each item in the products array carries a composite id (in lineNumber-sku1-sku2 format), brand, size, price, price_per_unit, thumbnail, a reviews object with average rating and review count, a categories array, and active promotion IDs. The total_results integer lets you calculate how many pages exist before fetching them.
Full Product Detail
Pass any id from search results to get_product to retrieve the complete record. Additional fields include a summary string, a multi-resolution images object (extraLarge through small), a weights object containing a uoms array, pricePerUomQualifier, and sizeDescription, plus a bar_codes array and storage instructions. Promotion detail at this level includes description text, expiry date, and the previous (was) price, making it straightforward to display deal context alongside the current price.
Barcode and Line Number Lookup
search_by_barcode accepts either a standard EAN/UPC barcode string (e.g. 7613034065520) or a Waitrose line number (e.g. 481037). The response shape mirrors get_product, returning the full detail record when a match exists. This is useful for inventory tooling or retail apps that scan physical products and need to cross-reference Waitrose pricing and packaging data.
Autocomplete
suggest_terms takes a partial term and returns up to 10 suggested search strings ordered by relevance. The response also exposes a search_engine field indicating which search variant returned the results. This endpoint is suited for type-ahead UI components where you want to reflect the same suggestions a user would see on the Waitrose site.
The Waitrose API is a managed, monitored endpoint for waitrose.com — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when waitrose.com changes and a check fails, the API is automatically queued for repair and re-verified. It is built to keep working as the site underneath it changes.
This isn't an official waitrose.com API — it's an independent, maintained REST wrapper over public data. Where the source has no official API (or only a limited one), Parse gives you a stable contract over a source that never promised one, and keeps it current. Need a new endpoint or field? You can revise it yourself in plain English and the agent rebuilds it against the live site in minutes — contributing the change back to the shared API is free.
Will this API break when the source site changes?+
Is this an official API from the source site?+
Can I fix or extend this API myself if I need a new endpoint or field?+
What happens if I call an endpoint that has an issue?+
- Build a grocery price tracker that monitors
priceand promotion expiry fields across a list of product IDs. - Scan product barcodes in a mobile app and return Waitrose pricing and shelf life data via
search_by_barcode. - Populate a type-ahead search box using
suggest_termsto match the autocomplete experience on the Waitrose site. - Aggregate nutritional or packaging data (including recyclability fields from
get_product) for sustainability reporting tools. - Cross-reference Waitrose line numbers with an internal inventory system using the
bar_codesarray returned byget_product. - Pull category and brand metadata from
search_productsto build a structured grocery taxonomy or product comparison table. - Monitor active promotions by tracking promotion IDs and was-prices across repeated calls to
get_product.
| Tier | Price | Credits/month | Rate limit |
|---|---|---|---|
| Free | $0/mo | 200 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 100 req/min |
| Team | $300/mo | 20,000 | 300 req/min |
| Company | $1,000/mo | 100,000 | 500 req/min |
Each endpoint has a fixed posted price per successful call — most fall between 1 and 10 credits — shown on this API's page before you run it. Exceeding the rate limit returns a 429 response. Authenticate with the X-API-Key header.
Does Waitrose offer an official public developer API?+
What does `get_product` return beyond what `search_products` includes?+
search_products returns a summary record per product: id, name, brand, size, thumbnail, price, price_per_unit, reviews, categories, and promotion IDs. get_product expands on this with the full images object (four resolution tiers), a summary description, weights detail including the uoms array and qualifiers, bar_codes, storage instructions, shelf life in days, and full promotion detail including description text and expiry date.Does the API cover Waitrose store availability or stock levels?+
What format does the `product_id` parameter require for `get_product`?+
product_id must follow the composite format lineNumber-sku1-sku2 (for example, 123456-789-0). The id field returned in every search_products result is already in this format, so the typical workflow is to run a search first and pass the resulting id directly to get_product.Does the API return product reviews or only review aggregates?+
search_products and get_product return a reviews object containing averageRating and reviewCount, which are aggregate figures. Individual review text and per-reviewer data are not included in the current endpoints. You can fork this API on Parse and revise it to add an endpoint that returns individual review content.