Carrefour APIcarrefour.fr ↗
Access Carrefour.fr grocery products, pricing, nutrition info, ingredients, NutriScore, and store locations across France via 4 structured endpoints.
What is the Carrefour API?
The Carrefour.fr API provides 4 endpoints to search grocery products, retrieve full product details by EAN barcode, browse category-level featured listings, and find store locations across France. The get_product_details endpoint returns over a dozen fields including ingredients, nutritional values, regulated name, and category hierarchy. The search_products endpoint supports free-text queries and returns pricing, NutriScore, packaging, and customer review data for up to 30 matching products per call.
curl -X GET 'https://api.parse.bot/scraper/a7ed411e-b2aa-462d-a179-bb55f7aaae1e/search_products?query=lait' \ -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-fr-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.fr Grocery API — search products, get details, browse categories, find stores."""
from parse_apis.carrefour_fr_grocery_api import Carrefour, CategorySlug, ProductNotFound
client = Carrefour()
# Search for dairy products — limit caps total items fetched.
for product in client.productsummaries.search(query="lait", limit=5):
print(product.title, product.brand, product.price.price)
# Drill into the first result for full nutritional detail.
item = client.productsummaries.search(query="fromage", limit=1).first()
if item:
detail = item.details()
print(detail.title, detail.ingredients, detail.regulated_name)
# Browse a category using the enum.
for product in client.category(CategorySlug.CREMERIE).products(limit=3):
print(product.title, product.price.per_unit_label)
# Find stores — filter by city.
for store in client.stores.list(city="Lyon", limit=5):
print(store.name, store.address, store.has_drive)
# Typed error handling: catch a missing product by EAN.
try:
missing = client.products.get(ean="0000000000000")
print(missing.title)
except ProductNotFound as exc:
print(f"Product not found: EAN {exc.ean}")
print("exercised: productsummaries.search / details / category.products / stores.list / products.get")
Full-text search over Carrefour.fr grocery products. Returns a list of matching products with pricing, packaging, promotions, and customer review data. Results are ordered by relevance. Typically returns 10-30 products per query.
| Param | Type | Description |
|---|---|---|
| queryrequired | string | Search keyword (e.g., 'lait', 'pain', 'fromage', 'beurre') |
{
"type": "object",
"fields": {
"total": "integer — number of products returned",
"products": "array of product objects with ean, title, brand, slug, image, price, packaging, format, nutriscore, customer_reviews"
},
"sample": {
"data": {
"total": 21,
"products": [
{
"ean": "3428271240029",
"slug": "lait-demi-ecreme-vitamine-1-mg-lactel",
"brand": "LACTEL",
"image": "https://media.carrefour.fr/medias/754dfff63d1441d497d97ac49e916d18/p_FORMAT/03428271240029_H1L1_s02.png",
"price": {
"unit": "L",
"price": 7.08,
"unit_price": 1.18,
"per_unit_label": "1.18 € / L"
},
"title": "Lait Demi-Ecrémé Vitaminé 1% MG LACTEL",
"format": "6x1l",
"packaging": "le pack de 6 briques d'1L",
"nutriscore": null,
"customer_reviews": {
"count": 6221,
"rates": {
"1": 0,
"2": 1,
"3": 5,
"4": 28,
"5": 66
},
"average": 4.58
}
}
]
},
"status": "success"
}
}About the Carrefour API
Product Search and Detail
The search_products endpoint accepts a query string — such as lait, fromage, or beurre — and returns a list of matching grocery products. Each product object includes ean, title, brand, slug, image, price, packaging, format, nutriscore, and customer_reviews. Results are ordered by relevance and typically number between 10 and 30 per query.
For deeper data on a specific item, get_product_details takes a required ean barcode and an optional slug to resolve any ambiguity. The response includes a price object with unit_price, unit, and per_unit_label; a nutrition object with per-portion values; a full ingredients string; a description; a regulated_name; and a categories array with id, label, slug, uri, type, and level fields for each node in the hierarchy.
Category Browsing and Store Locations
The browse_category_products endpoint accepts a category_slug such as cremerie, boissons, or fruits-et-legumes and returns 20–30 products that Carrefour promotes for that category. The response shape mirrors search_products, making it straightforward to handle both in the same code path.
The get_store_locations endpoint returns up to 100 French Carrefour stores. Each store object exposes store_id, name, banner, address, city, zipcode, phone, website, services, has_drive, latitude, and longitude. An optional city parameter filters results to a specific municipality such as Paris or Lyon. When city is omitted, the endpoint returns stores up to its default cap.
The Carrefour API is a managed, monitored endpoint for carrefour.fr — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when carrefour.fr 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.fr 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 grocery price tracker that monitors
priceandunit_pricechanges for specific EAN barcodes over time. - Populate a nutrition database using
ingredients,nutriscore, and per-portionnutritionvalues fromget_product_details. - Find which Carrefour stores in a given city offer drive-through service using the
has_driveandcityfields fromget_store_locations. - Aggregate category-level assortment data by iterating category slugs through
browse_category_productsto see which brands Carrefour features per category. - Match product EANs from a receipt or barcode scanner to full product records including regulated name and category hierarchy.
- Filter search results by
nutriscoreto surface healthier alternatives within a product search result set. - Map store GPS coordinates from
latitudeandlongitudeto visualize Carrefour's retail footprint across French cities.
| 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.fr have an official public developer API?+
What does `get_product_details` return beyond what `search_products` already provides?+
search_products returns summary fields: ean, title, brand, price, packaging, format, nutriscore, and customer_reviews. get_product_details adds ingredients, a per-portion nutrition object, description, regulated_name, and a full categories array with hierarchy level, URI, and type for each category node.Can I paginate through all products in a category, not just the featured 20–30?+
browse_category_products returns a curated set of promoted products for a category slug and does not expose pagination parameters. For broader coverage within a category, search_products with category-specific keywords returns up to 30 results per query. You can fork this API on Parse and revise it to add a paginated category-listing endpoint.Does the API cover Carrefour stores outside France, such as Spain or Belgium?+
get_store_locations endpoint covers Carrefour locations in France only. International store data is not currently included. You can fork this API on Parse and revise it to add endpoints targeting Carrefour's country-specific sites.