Carrefour APIcarrefour.eu ↗
Search and retrieve Carrefour Belgium product data including prices, availability, Nutri-Score, and nutritional info via 2 structured endpoints.
What is the Carrefour API?
The Carrefour Belgium API provides access to the full Carrefour.be product catalog through 2 endpoints, covering search, category browsing, pricing, stock availability, and per-product nutritional data. The search_products endpoint returns paginated results with price, brand, and package info, while get_product_details exposes structured nutritional values, Nutri-Score grades, and ingredient descriptions for individual products.
curl -X GET 'https://api.parse.bot/scraper/ff0c0252-2e26-4e1c-9bfc-f1f76f2d3c33/search_products?page=0&query=lait&category_id=products' \ -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 carrefour-eu-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: Carrefour Belgium SDK — search products and inspect nutritional details."""
from parse_apis.carrefour_belgium_api import Carrefour, ProductNotFound
client = Carrefour()
# Search for dairy products — limit= caps total items fetched across all pages.
for product in client.products.search(query="lait", limit=5):
print(product.name, product.price, product.currency, product.availability)
# Drill into the first result's full details (description, nutrition).
product = client.products.search(query="chocolat", limit=1).first()
if product:
details = product.details()
print(details.name, details.brand, details.nutri_score)
for nutrient in details.nutritional_info[:3]:
print(nutrient.label, nutrient.value)
# Typed error handling: catch a missing product.
try:
bad = client.products.search(query="nonexistent_xyz_999", limit=1).first()
if bad:
bad.details()
except ProductNotFound as exc:
print(f"Product gone: {exc.url}")
print("exercised: products.search / product.details / ProductNotFound")
Search for products by keyword or browse by category. Returns a paginated list of products with prices, stock availability, and basic details. Results are returned 36 per page. Pagination is zero-indexed. At least one of query or category_id should be provided for meaningful results.
| Param | Type | Description |
|---|---|---|
| page | integer | Page number, 0-indexed. |
| query | string | Search keyword (e.g., 'lait', 'chocolat'). If omitted, browses the specified category. |
| category_id | string | Category ID to browse (e.g., 'ros002' for Crèmerie). Omitting returns all products. |
{
"type": "object",
"fields": {
"page": "integer current page number",
"products": "array of product objects with product_id, name, brand, price, currency, image_url, url, package_info, price_per_unit, and availability",
"page_size": "integer number of results per page (36)",
"total_count": "integer total number of matching products"
},
"sample": {
"data": {
"page": 0,
"products": [
{
"url": "https://www.carrefour.be/fr/lourson-gateaux-chocolat-fourre-lait-150g/04971931.html",
"name": "L'Ourson Gâteaux Chocolat Fourré Lait 150g",
"brand": "LU",
"price": 3.69,
"currency": "EUR",
"image_url": "https://cdn.carrefour.eu/420_04971931_T1.webp",
"product_id": "04971931",
"availability": 217,
"package_info": "La pièce",
"price_per_unit": "24,60 €/kg"
}
],
"page_size": 36,
"total_count": 387
},
"status": "success"
}
}About the Carrefour API
Search and Browse Products
The search_products endpoint accepts a query string (e.g., 'lait', 'chocolat') and/or a category_id (e.g., 'ros002' for Crèmerie) to return a paginated list of matching products. Each page contains up to 36 results, and pagination is zero-indexed via the page parameter. Each product object in the response includes product_id, name, brand, price, currency, image_url, url, package_info, price_per_unit, and availability status. The total_count field lets you calculate how many pages to fetch.
Product Detail and Nutritional Data
The get_product_details endpoint takes a full product page url — obtained from a search_products result — and returns extended product information. This includes a description with ingredient and usage details, a nutri_score field (grades A–E, or null when not present on the product page), and a nutritional_info array of label/value pairs covering standard values such as energy, fat, carbohydrates, protein, and salt.
Coverage and Scope
This API covers the Carrefour Belgium (carrefour.be) product catalog, with product text and categories served in French. Category IDs such as 'ros002' can be used to browse specific departments without a keyword query. Nutritional data is returned only when the product page itself carries that information — some products may return an empty nutritional_info array and a null nutri_score.
The Carrefour API is a managed, monitored endpoint for carrefour.eu — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when carrefour.eu 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.eu 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 for specific grocery products across Carrefour Belgium's catalog using
priceandprice_per_unitfields. - Build a nutrition comparison tool by fetching
nutritional_infoandnutri_scorefor products in a given category. - Aggregate stock availability data across product categories using the
availabilityfield fromsearch_products. - Populate a recipe ingredient shopping list with matched Carrefour products, prices, and package sizes.
- Monitor a specific product category (e.g., dairy via
category_id: 'ros002') for new product listings usingtotal_countand pagination. - Filter products by brand using the
brandfield returned from search results to compare private-label vs. named-brand pricing. - Extract ingredient lists and allergen-relevant descriptions from
get_product_detailsfor dietary filtering applications.
| 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 Carrefour have an official public developer API?+
What does `search_products` return beyond the product name and price?+
products array includes product_id, brand, currency, image_url, url, package_info (e.g., weight or volume), price_per_unit (unit pricing such as price per kg or liter), and an availability flag. The url field is what you pass to get_product_details for deeper information.Is nutritional data available for every product?+
nutritional_info array and nutri_score field in get_product_details are populated only when the product page itself contains that data. For products without nutritional labeling on their page — such as some non-food items or loosely described products — both fields will be empty or null.Does the API cover Carrefour stores in France, Spain, or other countries?+
carrefour.be) catalog. Other Carrefour country storefronts are not included. You can fork this API on Parse and revise it to add endpoints targeting other regional Carrefour domains.Can I retrieve customer reviews or promotions data for products?+
price field when a promotion is active on the product page, but there is no dedicated promotions endpoint. You can fork this API on Parse and revise it to add a promotions or reviews endpoint.