Carrefour APIcarrefour.be ↗
Search Carrefour Belgium's grocery catalog, retrieve product details with nutritional info, browse categories, and fetch live promotions via a structured JSON API.
What is the Carrefour API?
The Carrefour Belgium API exposes 6 endpoints covering product search, full product detail pages, category browsing, and live promotions from carrefour.be. The get_product endpoint returns over a dozen fields per item including nutri-score, allergens, ingredients, unit pricing in EUR, and stock availability. search_products runs full-text queries across the entire catalog and returns paginated results of up to 36 products per page.
curl -X GET 'https://api.parse.bot/scraper/f1a661f8-c8b3-4d04-9900-830fe047b8d8/search_products?page=1&query=melk' \ -H 'X-API-Key: $PARSE_API_KEY'
Full-text search over Carrefour Belgium's product catalog. Returns paginated product listings with price, brand, unit price, and availability. Results are ordered by relevance. Each page returns up to 36 products.
| Param | Type | Description |
|---|---|---|
| page | integer | Page number (1-based). Each page returns up to 36 products. |
| queryrequired | string | Search query text (e.g. 'melk', 'pasta', 'chips'). |
{
"type": "object",
"fields": {
"page": "current page number",
"query": "submitted search query",
"products": "array of product summaries with id, name, brand, price, unit_price, image_url, product_url, available",
"total_pages": "total number of pages available",
"total_results": "total number of matching products"
},
"sample": {
"data": {
"page": 1,
"query": "melk",
"products": [
{
"name": "Ijs repen melk chocolade caramel 7-pack",
"brand": "Mars",
"price": 5.99,
"available": true,
"image_url": "https://cdn.carrefour.eu/420_05974531_T597.webp",
"product_id": "05974531",
"unit_price": "21,39 €/kg",
"product_url": "https://www.carrefour.be/nl/ijs-repen-melk-chocolade-caramel-7-pack/05974531.html"
}
],
"total_pages": 5,
"total_results": 170
},
"status": "success"
}
}About the Carrefour API
Product Search and Detail
search_products accepts a query string (e.g. 'melk', 'chips') and an optional 1-based page parameter, returning up to 36 product summaries per page. Each summary includes id, name, brand, price, unit_price, image_url, product_url, and available. total_results and total_pages let you paginate through the full result set. To retrieve the complete record for any item, pass its product_id to get_product, which adds allergens, nutri_score, description, an images array, and category.
Category Browsing
get_categories takes no parameters and returns every top-level category on the site as an array of objects with category_id, name, and url. Feed any category_id (e.g. 'ros002') into get_category_products to get the same paginated product summary format scoped to that category. Both browsing endpoints share the same 36-products-per-page structure and total_pages/total_results counters.
Promotions
get_promotions lists current promotional offers, grouped by promotion, with optional locale (nl-BE or fr-BE), page, page_size (1–100), and category_id filters. Each item in the items array contains a PromotionObservation (with promotion_id, title, mechanic_type, and valid_until) alongside an array of PromotionProductSummary objects. To resolve a single deal, pass its promotion_id to get_promotion, which returns up to 100 linked products in one call including retailer_product_id, offer, brand, and availability.
Data Coverage Notes
All pricing is in EUR and reflects the Belgian storefront. Product IDs are 8-digit numeric strings obtainable from search or category results. The unit_price field is a formatted string (e.g. '1,49 €/l') rather than a numeric value, so parse accordingly. Nutritional data and ingredients are returned only at the single-product level via get_product, not in list endpoints.
The Carrefour API is a managed, monitored endpoint for carrefour.be — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when carrefour.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 carrefour.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?+
- Track price changes on specific Belgian grocery products by polling
get_productwith known product IDs. - Build a nutri-score filter tool by retrieving products from a category and fetching allergen and nutri-score data per item.
- Aggregate current promotional offers across categories using
get_promotionswithcategory_idfiltering. - Populate a price-comparison tool with live unit prices (
unit_price) and standard prices from Carrefour Belgium. - Index the full Carrefour Belgium catalog by paginating through
get_categoriesandget_category_products. - Build a dietary filter by extracting
allergensandingredientsfromget_productresponses for matching products. - Send promotion alerts by monitoring
valid_untildates returned inPromotionObservationobjects fromget_promotion.
| 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 Carrefour Belgium have an official public developer API?+
What does `get_product` return that list endpoints do not?+
get_product adds allergens, nutri_score, description, a full images array, and the category ID to the base fields shared with list responses. Search and category endpoints return only summary fields: id, name, brand, price, unit_price, image_url, product_url, and available.How does locale affect the promotions endpoints?+
get_promotions and get_promotion both accept a locale parameter set to either nl-BE (Dutch) or fr-BE (French). This controls which language variant of the Carrefour Belgium site the promotion and product names are drawn from. If omitted, the API uses a default locale.Does the API cover Carrefour stores in other countries like France or Spain?+
Are store-level stock levels or click-and-collect availability returned?+
available field indicates whether a product is currently in stock at a catalog level, but per-store inventory or click-and-collect slot data is not returned by any endpoint. You can fork the API on Parse and revise it to add store-level availability if that data is accessible on the site.