Waitrose APIwaitrose.com ↗
Search Waitrose grocery products, retrieve detailed product data including ingredients, nutrition, pricing, and promotions via 3 structured endpoints.
What is the Waitrose API?
The Waitrose API gives developers access to Waitrose & Partners' online grocery catalog through 3 endpoints covering product search, full product detail, and search autocomplete. The search_products endpoint returns paginated results with fields including brand, size, price, price per unit, thumbnail URLs, review scores, categories, and active promotion data — everything needed to browse or compare grocery items programmatically.
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.
from parse_apis.waitrose_products_api import Waitrose, ProductSummary, Product, Suggestion, ProductNotFound
waitrose = Waitrose()
# Get autocomplete suggestions for a prefix
suggestion = waitrose.products.suggest(term="cof")
print(suggestion.term, suggestion.search_engine)
for s in suggestion.suggestions:
print(s)
# Search for products with pagination
for product_summary in waitrose.products.search(query="coffee beans", size=5):
print(product_summary.name, product_summary.price, product_summary.brand)
print(product_summary.reviews.average_rating, product_summary.reviews.review_count)
# Drill into full product details
full_product = product_summary.details()
print(full_product.description, full_product.storage_instruction)
print(full_product.weights.price_per_uom_qualifier, full_product.weights.size_description)
for promo in full_product.promotions:
print(promo.description, promo.expiry_date)
for cat in full_product.categories:
print(cat.id, cat.name)
print(full_product.images.extra_large, full_product.images.small)
for pkg in full_product.packaging:
print(pkg.package_material, pkg.recyclable)
break
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
Endpoints and Data Coverage
The API exposes three endpoints. search_products accepts a query string along with optional page and size parameters for pagination and returns a list of product summaries. Each summary includes id, line_number, name, brand, size, price, price_per_unit, thumbnail, reviews (average rating and review count), categories, and any active promotions. total_results is returned alongside the current page and size so you can implement full pagination.
Full Product Detail
get_product takes a product_id in the format lineNumber-sku1-sku2 (obtainable from search_products results) and returns the complete record for a single item. Response fields include name, brand, size, price, summary, bar_codes, a reviews object, a weights object with unit-of-measure and price qualifier context, and an images object with four resolution tiers (extraLarge, large, medium, small). This endpoint is the right call when you need packaging or storage context not present in the search summary.
Search Suggestions
suggest_terms accepts a term prefix and returns up to 10 autocomplete suggestions as an array of strings, plus a search_engine identifier. This is useful for building typeahead search interfaces or for discovering how Waitrose's catalog organizes terminology before running a full search_products call.
Scope Notes
All three endpoints reflect the Waitrose online grocery catalog. Product IDs returned by search_products map directly into get_product, so the two endpoints are designed to be used together: search broadly, then fetch detail records for the items you need.
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?+
- Compare unit prices (
price_per_unit) across competing grocery products in the same category - Track active promotions on specific products over time using data from
search_products - Build a barcode lookup tool using
bar_codesfields fromget_product - Power a typeahead search widget in a meal-planning app using
suggest_terms - Aggregate review ratings across a product range using
averageRatingandreviewCount - Extract multi-resolution product imagery from the
imagesobject for a recipe or shopping app - Monitor price changes across a set of product IDs by polling
get_producton a schedule
| Tier | Price | Credits/month | Rate limit |
|---|---|---|---|
| Free | $0/mo | 100 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 100 req/min |
One credit = one API call regardless of which marketplace API you call. 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 the `get_product` endpoint return beyond what `search_products` provides?+
get_product adds fields not present in search summaries: summary (a text description of the item), bar_codes (an array of barcode strings), the full images object with four resolution URLs, and a weights object containing unit-of-measure and price qualifier details. It does not currently include structured ingredient lists or nutritional tables as discrete fields, though the summary field may contain descriptive text.How does pagination work in `search_products`?+
page (1-based integer) and size (results per page) as optional parameters. The response echoes back page, size, and total_results, so you can calculate the total number of pages. If page and size are omitted, the API returns a default page of results.Does the API cover Waitrose store availability or click-and-collect slot data?+
Are ingredients and nutritional information available as structured fields?+
get_product response includes a summary field and contextual weights data, but ingredients and nutritional breakdowns are not returned as separate parseable objects. You can fork this API on Parse and revise it to add a dedicated nutritional-data endpoint.