Carrefour APIcarrefour.es ↗
Access Carrefour Spain supermarket data: store resolution by postal code, product categories, listings, full product details, and live promotional offers.
What is the Carrefour API?
This API exposes 5 endpoints covering the Carrefour Spain online supermarket at carrefour.es, returning store assignments, category trees, paginated product listings, and full product details including EAN barcodes and nutritional context. The get_product_detail endpoint alone returns 10 structured fields — from ean and unit_price to net_content and image_url — scoped to a specific store via postal code.
curl -X GET 'https://api.parse.bot/scraper/4af87ee7-ccf8-4b23-bb9d-40b57eed39e7/resolve_location?postal_code=28232' \ -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-es-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 Spain supermarket SDK — bounded, re-runnable; every call capped."""
from parse_apis.carrefour_es_api import CarrefourSpain, ProductNotFound
client = CarrefourSpain()
# Resolve a postal code to its assigned store and delivery zone.
location = client.locations.get(postal_code="28232")
print(location.store_name, location.sale_point, location.delivery_type)
# List top-level supermarket categories.
for cat in client.categories.list(limit=3):
print(cat.category_id, cat.name)
# Drill into a category's subcategories.
despensa = client.category(category_id="cat20001")
for sub in despensa.products(limit=2):
print(sub.name, sub.regular_price, sub.promotion_text)
# Get full product detail from a listing result.
item = despensa.products(limit=1).first()
if item:
try:
full = item.details()
print(full.name, full.ean, full.net_content, full.regular_price)
except ProductNotFound as e:
print(f"product gone: {e.product_id}")
# Browse current promotional offers.
for offer in client.categories.offers(limit=3):
print(offer.name, offer.promotion_text, offer.promotion_end_date)
print("exercised: locations.get / categories.list / category.products / product.details / categories.offers")
Resolves a Spanish postal code to the assigned Carrefour store, delivery zone, and geographic identifiers. Returns the store name, sale point code, region, and warehouse identifiers that scope product availability and pricing.
| Param | Type | Description |
|---|---|---|
| postal_coderequired | string | 5-digit Spanish postal code (e.g. 28232). |
{
"type": "object",
"fields": {
"werks_id": "string — warehouse works identifier",
"region_id": "string — geographic region identifier",
"sale_point": "string — store identifier code",
"store_name": "string — human-readable store name",
"postal_code": "string",
"delivery_type": "string — delivery method",
"allow_substitutions": "boolean",
"is_sell_pack_enabled": "boolean",
"nektria_warehouse_id": "string — logistics warehouse UUID"
},
"sample": {
"data": {
"werks_id": "0731",
"region_id": "5289",
"sale_point": "005290",
"store_name": "COL PINAR",
"postal_code": "28232",
"delivery_type": "A_DOMICILIO",
"allow_substitutions": true,
"is_sell_pack_enabled": true,
"nektria_warehouse_id": "e5069f93-bded-4904-b554-453e37c8075a"
},
"status": "success"
}
}About the Carrefour API
Store Resolution and Location Scoping
Product availability and pricing on carrefour.es vary by store. The resolve_location endpoint accepts a 5-digit Spanish postal code and returns the matched store's store_name, sale_point code, region_id, werks_id, and nektria_warehouse_id. Pass the resolved postal_code (or the raw code directly) to any other endpoint to ensure prices and stock reflect the correct fulfillment zone. The response also indicates the delivery_type and whether substitutions are permitted for that location.
Category Navigation
get_categories returns a flat list of category objects, each carrying a category_id, name, parent_category_id, and url. Omit parent_category_id to retrieve the top-level taxonomy; supply a category ID such as cat20001 to drill into subcategories. Chain calls to traverse the full tree before querying listings.
Product Listings and Detail
get_products_by_category paginates up to 24 products per page from any given category_id, returning total_results so you can calculate full iteration. Each product object in the products array includes pricing, availability, and promotion signals. For deeper data, pass a product_id or product_url from listing results to get_product_detail, which returns the ean (EAN-13), brand, sku_id, net_content, unit_price, image_url, and an observed_at ISO timestamp.
Promotional Offers
get_offers surfaces products currently featured in active campaigns without requiring a category ID. It accepts the same page, limit, and postal_code parameters as the category listing endpoint, returning a total_results count and an array of offer product objects with promotion and pricing data.
The Carrefour API is a managed, monitored endpoint for carrefour.es — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when carrefour.es 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.es 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 unit price changes across product categories for grocery price comparison tools.
- Build a promotional alert system using
get_offersto detect new campaigns by postal code. - Populate a product database with EAN barcodes and brand data via
get_product_detail. - Map Spanish postal codes to Carrefour store and warehouse identifiers for logistics research.
- Index category hierarchies from
get_categoriesto mirror the Carrefour supermarket taxonomy. - Monitor net content and unit price together to compute price-per-litre or price-per-kg metrics.
- Aggregate offer counts by region by calling
get_offersacross multiple resolved postal codes.
| 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 Spain provide an official developer API?+
What does `resolve_location` actually return, and why does it matter for other endpoints?+
resolve_location maps a 5-digit Spanish postal code to a specific store, returning fields like sale_point, werks_id, region_id, and nektria_warehouse_id. Carrefour's pricing and stock are store-specific, so passing the resolved postal_code to endpoints like get_products_by_category or get_product_detail ensures the response reflects that store's actual availability and prices rather than a generic default.Does `get_product_detail` return customer reviews or ratings?+
get_product_detail returns fields like ean, brand, unit_price, net_content, and image_url, but does not include review counts, star ratings, or user-generated content. You can fork the API on Parse and revise it to add a reviews endpoint if that data is needed.What is the maximum page size for product listings, and how do I paginate fully?+
get_products_by_category and get_offers both cap at 24 products per page via the limit parameter. The response includes total_results and page_size, so the total page count is ceil(total_results / page_size). Increment the page parameter (1-based) to walk through all results.Does the API cover Carrefour Spain non-food product categories such as electronics or clothing?+
/supermercado). Non-food departments like electronics, clothing, or home appliances sold on the main carrefour.es site are not covered by the current endpoints. You can fork the API on Parse and revise it to target those sections of the site.