Carrefour APIcarrefour.es ↗
Access Carrefour Spain product data: categories, product listings, pricing, EAN lookups, promotional offers, and store resolution by postal code.
What is the Carrefour API?
This API exposes 6 endpoints covering the Carrefour Spain online supermarket at carrefour.es, returning product details, category trees, promotional offers, and store assignments. The get_product_detail endpoint returns 10 structured fields per product including EAN-13 barcode, brand, net content, unit price, and a high-resolution image URL. Store-scoped pricing and availability can be applied to most endpoints by passing a Spanish 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, InputNotFound
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 specific category's products via constructible lookup.
despensa = client.category(category_id="cat20001")
for item in despensa.products(limit=2):
print(item.name, item.regular_price, item.promotion_text)
# Navigate from a listing hit to full product detail.
hit = despensa.products(limit=1).first()
if hit is not None:
try:
full = hit.details()
print(full.name, full.ean, full.net_content, full.regular_price)
except InputNotFound:
print("product no longer available")
# Look up a product by its EAN barcode (derived from the detail above).
if hit is not None:
full = hit.details()
if full.ean is not None:
by_barcode = client.products.get_by_ean(ean=full.ean)
print(by_barcode.name, by_barcode.brand)
# 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 / details / get_by_ean / 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 Context
The resolve_location endpoint accepts a 5-digit Spanish postal code and returns the Carrefour store assigned to that zone. The response includes a sale_point store code, region_id, werks_id, nektria_warehouse_id, and delivery metadata such as delivery_type and allow_substitutions. This store context flows into the other endpoints via the optional postal_code parameter, which adjusts product availability and pricing to reflect what a customer at that location would see.
Category Tree and Product Listings
get_categories returns the full category hierarchy. Call it without parent_category_id to get top-level categories, each carrying a category_id, name, and url. Pass a category_id back as parent_category_id to drill into subcategories. Feed those IDs into get_products_by_category, which returns paginated product arrays (up to 24 per page) with pricing, promotion flags, and availability. The total_results field lets you calculate how many pages to walk for a full category export.
Product Detail and EAN Lookup
get_product_detail accepts either a product_id or a product_url from listing results and returns a full record: ean, name, brand, sku_id, category from the breadcrumb, image_url, unit_price, net_content, and an observed_at ISO timestamp. If you already have a barcode, get_product_by_ean accepts an 8-to-14-digit EAN/GTIN and returns the same detail payload, making it straightforward to cross-reference Carrefour listings against an external product database.
Promotional Offers
get_offers returns products currently featured in active Carrefour Spain promotions. Like the category endpoint, it supports page, limit, and postal_code parameters. The total_results field indicates the size of the active offer pool at the time of the request.
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 over time for specific EANs using
get_product_by_eanand theobserved_attimestamp. - Build a store-aware price comparison tool by resolving competing postal codes with
resolve_locationand comparingunit_priceacross zones. - Export a full category product catalog by walking subcategories from
get_categoriesand paginating throughget_products_by_category. - Monitor active promotions with
get_offersto detect new deals or measure how many products are on promotion at a given time. - Enrich an internal product database with brand, net content, and image data by batch-calling
get_product_detailusing known product URLs. - Cross-reference a list of barcodes against Carrefour Spain pricing by batch-querying
get_product_by_eanfor each EAN.
| 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 Spain have an official public developer API?+
What does `resolve_location` actually return, and why does the postal code matter for other endpoints?+
resolve_location maps a 5-digit Spanish postal code to a specific Carrefour store and returns fields like sale_point, werks_id, region_id, delivery_type, and nektria_warehouse_id. Passing the same postal_code to endpoints like get_products_by_category or get_product_detail scopes pricing and availability to that store's assortment, since Carrefour Spain prices and stock can vary by location.Does the API return customer reviews or ratings for products?+
What is the maximum page size for `get_products_by_category` and `get_offers`?+
limit parameter with a maximum of 24 products per page. Use the total_results field in the response to calculate the number of pages required to retrieve a full result set.