Ah APIah.be ↗
Search products, retrieve detailed product data, and list current weekly promotions from Albert Heijn Belgium (ah.be) via a simple REST API.
What is the Ah API?
The ah.be API gives developers access to Albert Heijn Belgium's product catalog and weekly promotions through 3 endpoints. Call search_products with a Dutch-language query to retrieve up to 30 matching products per request — including prices, brand, category, and image URLs — or use get_product to pull full metadata for a specific item by its numeric ID.
curl -X GET 'https://api.parse.bot/scraper/e34b541a-61a5-48ef-9c1a-ebbe0be2ed8c/search_products?query=melk' \ -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 ah-be-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: Albert Heijn Belgium SDK — search, detail drill-down, promotions."""
from parse_apis.ah_be_api import AlbertHeijn, ProductNotFound
client = AlbertHeijn()
# Search for products and print summary info
for product in client.product_summaries.search(query="melk", limit=5):
print(product.title, product.brand, product.price_now)
# Drill into the first search hit for full detail
hit = client.product_summaries.search(query="kaas", limit=1).first()
if hit is not None:
detail = hit.details()
print(detail.title, detail.summary)
print("Highlights:", detail.highlights)
print("Categories:", [c.name for c in detail.category_path])
# Point lookup by a known product ID (derived from search)
if hit is not None:
try:
full = client.products.get(product_id=str(hit.id))
print(full.title, full.price_now, full.sales_unit_size)
except ProductNotFound:
print("Product no longer available")
# Browse current promotions
for promo in client.promotions.list(limit=3):
print(promo.title, f"({promo.promotion_type})", len(promo.products), "products")
print("exercised: product_summaries.search / details / products.get / promotions.list")
Search for products by text query. Returns up to 30 matching products per call with pricing, images, and category information. The total_found field indicates how many products match overall.
| Param | Type | Description |
|---|---|---|
| queryrequired | string | Search term (e.g. 'melk', 'brood', 'kaas'). Supports Dutch product names, brands, and categories. |
{
"type": "object",
"fields": {
"products": "array of product objects with id, title, brand, prices, image, category",
"total_found": "total number of matching products (may exceed the 30 returned)"
},
"sample": {
"data": {
"products": [
{
"id": 1525,
"brand": "AH",
"icons": [
"NUTRISCORE_B",
"VEGETARIAN",
"AVAILABLE_IN_STORE"
],
"title": "AH Halfvolle melk",
"web_path": "/producten/product/wi1525/ah-halfvolle-melk",
"highlight": null,
"image_url": "https://static.ah.nl/dam/product/AHI_4354523130303337393339?revLabel=1&rendition=200x200_WEBP&fileType=binary",
"price_now": 1.49,
"price_was": 1.49,
"shop_type": "AH",
"is_orderable": true,
"category_path": [
{
"id": 21622,
"name": "Zuivel, eieren"
},
{
"id": 21495,
"name": "Melk"
},
{
"id": 21934,
"name": "Halfvolle melk"
}
],
"sales_unit_size": "1 l"
}
],
"total_found": 67
},
"status": "success"
}
}About the Ah API
Product Search and Details
The search_products endpoint accepts a query parameter (Dutch product names, brand names, or category terms such as 'melk' or 'kaas') and returns an array of product objects, each carrying an id, title, brand, prices, image, and category. The total_found field reflects the full count of matches on ah.be, which may exceed the 30 products returned per call — useful for knowing whether a broader or more specific query would yield better coverage.
The get_product endpoint takes a numeric product_id — sourced from search results or promotion listings — and returns a richer record: summary (product description text), highlights (feature bullet points), price_now and price_was in euros, image_large (800×800) and image_small (200×200) image URLs, and a category_path array that traces the product from broad category down to specific subcategory.
Promotions
The get_promotions endpoint requires no parameters and returns the current weekly bonus deals organised into segments. Each segment object includes an id, title, subtitle, and promotion_type, plus a products array listing the items on deal. Note that products returned inside promotion segments do not include pricing fields; to get price data for a promoted product, pass its ID to get_product.
Coverage Notes
All data reflects the Belgian Albert Heijn assortment (ah.be), which differs from the Dutch ah.nl range in product selection, pricing, and promotions. Promotion data reflects the current weekly cycle as published on the site, so results will shift week to week.
The Ah API is a managed, monitored endpoint for ah.be — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when ah.be 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 ah.be 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 Belgian grocery price tracker using
price_nowandprice_wasfields fromget_product - Aggregate weekly promotion deals by segment type using the
get_promotionsendpoint - Power a product search feature for a meal-planning app using
search_productswith Dutch ingredient queries - Compare Albert Heijn Belgium pricing across product categories using
category_pathfromget_product - Monitor availability and description changes for specific products by polling
get_productwith known IDs - Populate a grocery list app with product images, using
image_largeandimage_smallURLs from product detail responses
| 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 Albert Heijn Belgium provide an official developer API?+
Do promoted products in `get_promotions` include pricing data?+
price_now and price_was for a promoted item, take its ID and call get_product separately.Does the API support paginating through all matching products from a search query?+
search_products returns up to 30 products per call and exposes total_found so you know the full match count, but there is no page or offset parameter to retrieve results beyond the first 30. You can fork this API on Parse and revise it to add a pagination parameter if your use case requires full result sets.Does this API cover the Dutch ah.nl assortment, or only Belgian ah.be products?+
Can I retrieve historical pricing or past promotions?+
price_now and price_was, and promotions reflect the live weekly bonus cycle — no historical records are exposed. You can fork the API on Parse and revise it to log and store responses over time if you need a price history layer.