Jumbo APIjumbo.com ↗
Search Jumbo supermarket products, browse the full category tree, and fetch autocomplete suggestions. Covers prices, promotions, brands, and facet filters.
What is the Jumbo API?
The Jumbo.com API gives developers structured access to the Dutch supermarket's product catalog across 3 endpoints, returning fields like product price, brand, promotions, and facet filters. The search_products endpoint supports keyword queries with sorting, pagination, and facet-based filtering — including a dedicated promotion filter to surface current deals. Category browsing and autocomplete suggestions are also available.
curl -X GET 'https://api.parse.bot/scraper/69134a22-5293-4e3a-b0e1-3227b1b42818/search_products?sort=rankA%2Bdesc&query=melk&offset=0&filters=Merken%3AJumbo' \ -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 jumbo-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: Jumbo Supermarket SDK — search products, browse categories, get suggestions."""
from parse_apis.jumbo_supermarket_products_api import Jumbo, Sort, ProductSearchFailed
client = Jumbo()
# Search for products sorted by price, capped at 5 items
for product in client.searchresults.search(query="kaas", sort=Sort.PRICE_ASC, limit=5):
print(product.title, product.brand, product.price)
# Browse top-level categories
for category in client.categories.list(depth=2, limit=5):
print(category.title, category.link)
for sub in category.subcategories[:2]:
print(f" └─ {sub.title}")
# Get autocomplete suggestions for a partial query
suggestion = client.suggestions.search(query="bro", limit=1).first()
if suggestion:
print(suggestion.query, suggestion.display_text)
# Typed error handling around a search call
try:
for p in client.searchresults.search(query="", limit=3):
print(p.title)
except ProductSearchFailed as exc:
print(f"Search failed for query={exc.query!r}: {exc}")
print("exercised: searchresults.search / categories.list / suggestions.search / ProductSearchFailed")
Full-text search over Jumbo supermarket products. Returns paginated results with product details (price, promotions, availability), available filter facets (brand, category, promotions), and sort options. Pagination is offset-based with ~24 products per page. Facets returned in the response enumerate the available filter values for narrowing results. Server-side filtering via the filters param uses the format 'FacetKey:FacetValue'.
| Param | Type | Description |
|---|---|---|
| sort | string | Sort order for results. |
| queryrequired | string | Search query term (e.g. 'melk', 'kaas', 'brood'). |
| offset | integer | Pagination offset. Each page returns ~24 products. |
| filters | string | Filter string in format 'FacetKey:FacetValue'. Use 'Aanbiedingen:Alle aanbiedingen' to show only promoted/discounted products. Use 'Merken:<brand>' to filter by brand. Available facets and values are returned in the response. |
{
"type": "object",
"fields": {
"facets": "array of available filter facets with their values and counts",
"header": "string - search result header text",
"offset": "integer - current pagination offset",
"products": "array of product objects with id, title, brand, price, promotions, etc.",
"total_count": "integer - total number of matching products",
"sort_options": "array of available sort options with text and value"
},
"sample": {
"data": {
"facets": [
{
"key": "category",
"name": "Categorieën",
"values": [
{
"id": "SG8",
"name": "Zuivel, boter en eieren",
"count": 382
}
]
}
],
"header": "Melk",
"offset": 0,
"products": [
{
"id": "590300PAK",
"link": "/producten/campina-verse-halfvolle-melk-voordeelpak-1,5-l-590300PAK",
"brand": "Campina",
"image": "https://www.jumbo.com/dam-images/fit-in/360x360/Products/27102025_1761557574402_1761557578943_8712800006398_1.png",
"price": 1.89,
"title": "Campina Verse Halfvolle Melk Voordeelpak 1,5 L",
"badges": [
"5+ dagen houdbaar"
],
"category": "Zuivel, boter en eieren",
"subtitle": "1.5 liter",
"available": true,
"freshness": "5+ dagen houdbaar",
"promotions": [],
"promo_price": null,
"price_per_unit": {
"unit": "l",
"price": 1.26
}
}
],
"total_count": 354,
"sort_options": [
{
"text": "Populariteit",
"value": "rankA+desc"
},
{
"text": "Prijs (laag-hoog)",
"value": "price+asc"
},
{
"text": "Prijs (hoog-laag)",
"value": "price+desc"
}
]
},
"status": "success"
}
}About the Jumbo API
Endpoints and What They Return
The search_products endpoint accepts a required query string and returns an array of product objects with fields including id, title, brand, price, and promotions. A total_count integer and offset field support paginated traversal of results — each page yields approximately 24 products. The facets array in the response lists available filter dimensions (brand, category, promotions) with per-value counts, so you can present dynamic filter UIs without a separate lookup call. The sort_options array tells you exactly which sort values the endpoint accepts at runtime.
Filtering and Sorting
Filters are passed as a single filters string using the format FacetKey:FacetValue. To restrict results to currently promoted products, pass Aanbiedingen:Alle aanbiedingen. The sort parameter accepts rankA+desc for popularity ordering, price+asc, and price+desc for price-based ordering. These can be combined with filters and offset for precise result slices.
Categories and Suggestions
get_categories returns the full Jumbo category tree as a nested array of objects, each carrying a title, link, and subcategories array. The optional depth parameter controls how many levels of the tree are returned. search_suggestions takes a partial query string and returns two separate arrays: keywords (suggested completions with query and display_text) and brands (brand-level matches that also include a link field). This makes it straightforward to build a typeahead that distinguishes between general keyword completion and direct brand navigation.
The Jumbo API is a managed, monitored endpoint for jumbo.com — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when jumbo.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 jumbo.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 promotion tracker that polls
search_productswith theAanbiedingen:Alle aanbiedingenfilter to monitor current Jumbo deals - Power a price comparison tool using
price+ascsorting and brand facet filters from thefacetsresponse field - Render a full category navigation menu from the nested
subcategoriestree returned byget_categories - Implement a search typeahead that separates brand suggestions from keyword suggestions using the
brandsandkeywordsarrays fromsearch_suggestions - Paginate through an entire product category using
offsetto build a local product index for offline analysis - Filter results by a specific brand using
FacetKey:FacetValueformat and sort by price to find the cheapest items from that brand
| 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 Jumbo have an official public developer API?+
What product fields does `search_products` actually return for each item?+
products array includes at minimum id, title, brand, price, and promotions. The facets array returned alongside products lists filter dimensions with value counts, and sort_options shows available sort values. The exact depth of nested price and promotion objects reflects what Jumbo exposes on the product listing level.Does the API return individual product detail pages — ingredients, nutritional info, or images?+
How does pagination work in `search_products`?+
offset integer parameter. Each response returns approximately 24 products. Set offset to 24, 48, 72, etc. to walk through subsequent pages. The total_count field in the response tells you the full number of matching products so you can calculate how many pages exist.