Carrefour APIcarrefour.it ↗
Access Carrefour Italy product catalog, nutritional data, store locations, categories, and live promotions via a structured REST API. 6 endpoints.
What is the Carrefour API?
The Carrefour Italy API exposes 6 endpoints covering product search, category browsing, full product details (including nutrition and ingredients), store locations, and current promotions from carrefour.it. The get_product_details endpoint returns nutritional values, ingredient lists, EAN barcodes, and pricing in a single call, making it straightforward to build grocery apps, price trackers, or store finders against Italy's Carrefour catalog.
curl -X GET 'https://api.parse.bot/scraper/66821404-7878-4fb4-804b-c5c956470aff/search_products?page=1&limit=5&query=latte' \ -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-it-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.
from parse_apis.carrefour_italy_api import CarrefourItaly, Product, ProductDetail, Category, Store, Promotion, ProductNotFound
client = CarrefourItaly()
# Search for products by keyword
for product in client.products.search(query="pasta"):
print(product.name, product.price, product.brand, product.dimension52)
# List all grocery categories
for cat in client.categories.list():
print(cat.name, cat.slug)
# Browse products in a specific category via constructible Category
meat = client.category(slug="carne")
for item in meat.products():
print(item.name, item.price, item.metric19)
# Get full product details with nutrition info
detail = client.productdetails.get(product_slug="carrefour-classic-latte-uht-parzialmente-scremato-1000-ml", ean="8012666051267")
print(detail.id, detail.slug, detail.ingredients, detail.description)
# Find stores in a city
for store in client.stores.list(city="MILANO"):
print(store.name, store.address, store.city, store.type)
# Check current promotions
for promo in client.promotions.list():
print(promo.name, promo.price, promo.metric19, promo.brand)
Full-text search over Carrefour Italy's online grocery catalog. query matches product names; results are paginated with configurable page size. Each product includes name, EAN id, price, original price (metric19), brand, category slug, pack size (dimension52), and food/nonfood classification (dimension53).
| Param | Type | Description |
|---|---|---|
| page | integer | Page number (1-based) |
| limit | integer | Number of results per page |
| queryrequired | string | Search keyword (e.g. 'latte', 'pasta', 'birra') |
{
"type": "object",
"fields": {
"page": "integer — current page number",
"query": "string — the search keyword used",
"products": "array of product objects with name, id, price, metric19, brand, category, dimension52, dimension53",
"total_results": "integer — number of products returned on this page"
},
"sample": {
"data": {
"page": 1,
"query": "latte",
"products": [
{
"id": "8030705015322",
"name": "Polenghi Lombardo Latte 100% italiano Parzialmente Scremato 1 L",
"brand": "Polenghi Lombardo",
"price": "0.75",
"category": "latte_uht",
"metric19": "1.25",
"dimension52": "1000.0 ml",
"dimension53": "food"
}
],
"total_results": 25
},
"status": "success"
}
}About the Carrefour API
Product Search and Category Browsing
The search_products endpoint accepts a query string (e.g. 'pasta', 'latte') and returns a paginated list of matching products. Each item includes name, id, price, brand, category, and the dimension fields dimension52 and dimension53. Pagination is controlled with page (1-based) and limit parameters. To browse without a keyword, get_category_products takes a category_slug — such as 'frutta-e-verdura' or 'carne' — and returns all products listed under that category. Use get_online_grocery_categories first to retrieve the full list of valid slugs along with their name, slug, and url.
Product Details and Nutritional Data
get_product_details requires two inputs: a product_slug (the URL-friendly identifier) and an ean barcode string. The response includes the full data object with pricing and brand, a nutrition object with key-value pairs such as Grassi (fats), Proteine (proteins), and Sale (salt), an ingredients string, a description string, and an other_info object for manufacturer or origin data when available. If nutritional or ingredient data is not listed on the product page, those fields return as empty strings rather than null.
Store Locations and Promotions
get_store_locations returns Carrefour store details across Italy. An optional city parameter (case-insensitive) filters results to a specific city such as 'MILANO' or 'Torino'. Each store record includes name, address, city, province, cap (postal code), latitude, longitude, hours, type, and store_type. The total field tells you how many stores matched the filter. The get_promotions endpoint returns products currently on promotion; comparing price against metric19 (the original price field) reveals the active discount amount for each item.
The Carrefour API is a managed, monitored endpoint for carrefour.it — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when carrefour.it 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.it 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
pricevsmetric19fromget_promotionsto alert users when items go on sale. - Populate a nutrition database by pulling
nutritionandingredientsfields fromget_product_detailsusing EAN barcodes. - Create a store finder app using
get_store_locationswith city filtering andlatitude/longitudefor map rendering. - Aggregate category-level product catalogs via
get_category_productsfor comparison shopping or inventory analysis. - Track brand presence across Carrefour Italy's catalog by filtering the
brandfield insearch_productsresults. - Generate promotional deal digests by detecting discount depth from
priceandmetric19inget_promotionsresponses. - Sync product slugs and EANs from search results into a downstream pipeline feeding
get_product_detailsfor full data enrichment.
| 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 Italy have an official public developer API?+
What does `get_product_details` return, and how do I call it?+
data object with name, price, brand, and category; a nutrition object with per-nutrient key-value pairs; an ingredients string; a description string; and an other_info object. You must supply both the product_slug and the ean barcode as inputs — neither alone is sufficient. Both can be obtained from the id and slug fields returned by search_products or get_category_products.How does pagination work in `search_products`?+
page parameter (1-based integer) and a limit parameter to control page size. The response includes a total_results field reflecting the count of products returned on that page — not the grand total across all pages. To iterate through all results, increment page until total_results is less than limit.Does the API return user reviews or ratings for products?+
Are store hours returned in a structured format or as plain text?+
hours field in get_store_locations responses is returned as a string rather than a structured object. Parsing into day-by-day slots would need to be done on the client side. The endpoint does return type and store_type as separate fields to help distinguish hypermarkets from supermarkets and other formats.