ah APIah.nl ↗
Access Albert Heijn supermarket data via API: search products, fetch nutritional details, browse weekly bonus offers, explore categories, and retrieve supplier info.
What is the ah API?
The Albert Heijn API gives developers structured access to the ah.nl supermarket catalog across 5 endpoints, covering product search, detailed nutritional and allergen data, current bonus promotions, category taxonomy, and supplier contact information. The get_product_details endpoint alone returns over a dozen fields including allergens, packaging recyclability, net weight, and dietary properties alongside live pricing.
curl -X POST 'https://api.parse.bot/scraper/43420567-6847-4f31-98a5-fc8877e481b0/search_products' \
-H 'X-API-Key: $PARSE_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"page": "0",
"size": "5",
"query": "melk",
"sort_by": "price",
"bonus_only": "False"
}'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-nl-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 supermarket SDK — search products, check details, browse deals."""
from parse_apis.albert_heijn_supermarket_api import AlbertHeijn, Sort, ProductNotFound
client = AlbertHeijn()
# Search for products with sort preference. limit= caps total items fetched.
for product in client.productsummaries.search(query="pasta", sort_by=Sort.PRICE, limit=5):
print(product.title, product.brand, product.price, product.nutriscore)
# Drill into one product's full details via the summary→detail navigation.
summary = client.productsummaries.search(query="melk", limit=1).first()
if summary:
detail = summary.details()
print(detail.title, detail.price, detail.sales_unit_size)
for contact in detail.supplier_contacts:
print(contact.name, contact.address)
# Browse current bonus/discount products.
for bonus in client.bonusproducts.list(category="bier", limit=3):
print(bonus.title, bonus.original_price, bonus.bonus_mechanism)
for label in bonus.discount_labels:
print(label.code, label.description)
# Fetch a product by ID directly and handle not-found gracefully.
try:
detail = client.products.get(product_id="441199")
print(detail.title, detail.brand, detail.nutriscore)
except ProductNotFound as exc:
print(f"Product not found: {exc.product_id}")
# List all top-level store categories.
for cat in client.categories.list(limit=5):
print(cat.name, cat.slug, cat.nix18)
print("exercised: productsummaries.search / details / bonusproducts.list / products.get / categories.list")
Search for products in the Albert Heijn supermarket. Returns product listings with prices, images, categories, bonus/discount status, and more. Paginates via a 0-based page counter. Each page returns up to `size` products (max 50). Supports filtering by bonus status and category taxonomy ID.
| Param | Type | Description |
|---|---|---|
| page | integer | Page number (0-based) |
| size | integer | Number of results per page (max 50) |
| queryrequired | string | Search query (e.g., 'melk', 'pasta', 'bier') |
| sort_by | string | Sort order for results. |
| bonus_only | boolean | Filter to only show bonus/discount products |
| category_id | string | Filter by taxonomy/category ID (e.g., '2390' for Halfvolle melk) |
{
"type": "object",
"fields": {
"filters": "array of available filter options (brand, taxonomy, intolerance)",
"products": "array of product objects with id, title, brand, prices, bonus info, images, nutriscore",
"pagination": "object with page, size, total_elements, total_pages",
"taxonomy_nodes": "array of category nodes with id, name, images"
}
}About the ah API
Product Search and Bonus Promotions
The search_products endpoint accepts a required query string (Dutch or brand name, e.g. 'melk', 'pasta') and returns an array of product objects with fields including id, title, brand, prices, bonus status, and image URLs. Pagination is 0-based via page and size (up to 50 per page), and results can be sorted by price or bonus. Set bonus_only: true to restrict results to currently discounted items, or pass a category_id to scope the search to a specific taxonomy node. The get_bonus_products endpoint provides a dedicated view of active promotions, returning original and discounted prices alongside promotion periods and discount details for every item currently on offer.
Product Details and Nutritional Data
get_product_details takes a single product_id (e.g. '4164') and returns a full data record including allergens (structured array), packaging (materials and recyclability flags), measurements (net content and weight), and a properties object covering dietary and lifestyle attributes such as vegan or lactose-free status. This makes it suitable for building nutrition trackers, label-compliance tools, or shopping assistants that need to surface ingredient transparency data.
Categories and Suppliers
get_categories returns the full top-level category tree with each entry's id, name, slug, image, and nix18 flag (indicating age-restricted categories like alcohol). Passing a category_id switches the response to show filters, nested taxonomy_nodes, and a total_products count for that node — useful for building browsable category pages.
get_suppliers is queried either by passing comma-separated product_ids or a free-text query. It returns unique supplier objects with name, address, gln (Global Location Number), communication_channels, and a products list showing which items each supplier is linked to, plus a product_supplier_mapping array that pairs every product back to its supplier.
The ah API is a managed, monitored endpoint for ah.nl — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when ah.nl 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.nl 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 price-tracking tool that monitors ah.nl bonus promotions using
get_bonus_productsand alerts users when specific items go on discount. - Populate a nutrition database with allergen arrays, net weight, and dietary properties from
get_product_detailsfor meal-planning or label-compliance apps. - Create a grocery comparison widget that fetches live prices and bonus status via
search_productswithbonus_onlyfiltering. - Index the full Albert Heijn category taxonomy with
get_categoriesto power a browsable grocery directory with age-restriction (nix18) flags. - Identify and contact product manufacturers by resolving supplier
glncodes andcommunication_channelsfromget_suppliersfor B2B procurement workflows. - Filter packaging recyclability data from
get_product_detailsto help consumers or retailers find products with sustainable packaging. - Aggregate brand-level product counts across categories by combining
search_productswithcategory_idfiltering and thebrandfield on each product.
| 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 Albert Heijn have an official public developer API?+
What does get_product_details return beyond basic price and title?+
price and title, the endpoint returns structured allergens, a packaging object with material types and recyclability flags, a measurements object (net content and weight), a properties object covering dietary attributes (e.g. vegan, lactose-free), images, and the is_bonus flag with full discount information when applicable.Does the API cover product reviews or customer ratings?+
How does pagination work across endpoints, and are there size limits?+
search_products and get_bonus_products both use 0-based page indexing and accept a size parameter capped at 50 results per page. Each response includes a pagination object with total_elements and total_pages so callers can iterate the full result set. get_suppliers has a size limit of 20 when using query-based lookup.