Carrefour KSA APIcarrefourksa.com ↗
Fetch structured product data from Carrefour Saudi Arabia. Returns title, prices, barcode, brand, images, availability, and warranty in SAR via one endpoint.
What is the Carrefour KSA API?
The Carrefour KSA API exposes 1 endpoint — get_product — that returns 10 structured fields for any product on carrefourksa.com, including current and regular prices in SAR, EAN barcode, brand, full image gallery, stock status, warranty text, and seller ID. Pass a product page URL in Arabic or English and get back a normalized product record ready for price tracking, catalog sync, or inventory monitoring.
curl -X GET 'https://api.parse.bot/scraper/bef7a272-6f45-48d6-b498-d6530e37f585/get_product?product_url=https%3A%2F%2Fwww.carrefourksa.com%2Fmafsau%2Far%2Fwhite-eggs%2Fqaryah-white-eggs-special-30-pcs%2Fp%2F752711' \ -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 carrefourksa-com-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 KSA product lookup with typed fields and error handling."""
from parse_apis.carrefourksa_com_api import CarrefourKSA, ProductNotFound
client = CarrefourKSA()
# Fetch a product by its full page URL.
try:
product = client.products.get(
product_url="https://www.carrefourksa.com/mafsau/ar/white-eggs/qaryah-white-eggs-special-30-pcs/p/752711"
)
except ProductNotFound:
print("Product page does not exist or was removed.")
raise SystemExit
print(product.title, "|", product.product_id)
print("barcode:", product.barcode)
# Pricing is null when the item is out of stock.
if product.current_price is not None:
print(f"price: {product.current_price} {product.currency}")
if product.discount_percentage is not None:
print(f" discount: {product.discount_percentage}% (saves {product.discount_value})")
else:
print("price unavailable (out of stock)")
print("in stock:", product.in_stock, "—", product.stock_status)
# Walk category breadcrumbs.
for crumb in product.breadcrumbs:
print(f" category: {crumb.name} ({crumb.id})")
# Quick-glance attributes (pack size, sold-by, etc.).
for attr in product.quick_glance:
print(f" {attr.name}: {attr.value}")
# Grouped specifications (non-empty for electronics, empty for grocery).
for spec in product.specifications:
print(f" [{spec.group_name}]")
for feat in spec.features:
print(f" {feat.name}: {feat.value}")
print("exercised: products.get")
Returns the structured details of one Carrefour Saudi Arabia product given its product page URL. One page fetch per call. Output includes the product ID, title (in the language of the URL, ar or en), current and regular price in SAR (both null when the product is out of stock, since the site does not publish a price for unavailable items), EAN/GTIN barcode, brand (null when the site lists no brand for the item), main image URL plus the gallery, availability (in_stock, stock_status, available_quantity), seller, warranty, category breadcrumbs, quick-glance attributes and the grouped product specifications (an empty array when the site shows no specification table, common for grocery items). A URL whose product ID does not exist yields a stale_input error.
| Param | Type | Description |
|---|---|---|
| product_urlrequired | string | Full product page URL on carrefourksa.com, of the form https://www.carrefourksa.com/mafsau/<ar|en>/<category>/<slug>/p/<product_id>. Only the store, language and product ID segments are used. |
{
"type": "object",
"fields": {
"url": "canonical product page URL",
"brand": "brand name, null when the site lists none",
"title": "product name in the URL's language",
"images": "array of all gallery image URLs",
"barcode": "EAN/GTIN barcode string",
"currency": "ISO currency code of the prices (SAR)",
"in_stock": "boolean availability",
"warranty": "warranty text or null",
"image_url": "main product image URL",
"seller_id": "seller ID string",
"brand_code": "site brand code, null when absent",
"categories": "array of category codes",
"product_id": "string product ID (the number after /p/ in the URL)",
"breadcrumbs": "array of {id, name} category breadcrumbs",
"seller_name": "seller display name",
"product_type": "FOOD or NONFOOD",
"quick_glance": "array of {name, value} short attributes (pack size, sold by, ...)",
"stock_status": "site stock label, e.g. outOfStock or low; null when the site gives none for an in-stock item",
"current_price": "number, selling price; null when out of stock",
"regular_price": "number, price before discount (equals current_price when not discounted); null when out of stock",
"discount_value": "number, absolute discount amount, or null",
"specifications": "array of specification groups {group_code, group_name, features:[{name, value}]}",
"available_quantity": "integer purchasable quantity or null",
"discount_percentage": "number or null",
"is_marketplace_product": "boolean, true when sold by a third-party seller"
},
"sample": {
"data": {
"url": "https://www.carrefourksa.com/mafsau/ar/p/750353",
"brand": "Samsung",
"title": "سامسونج جالكسي إس 25 ألترا، ذاكرة داخلية 256 جيجابايت",
"images": [
"https://cdn.mafrservices.com/pim-content/SAU/media/product/750353/1747920603/750353_main.jpg"
],
"barcode": "2000007503533",
"currency": "SAR",
"in_stock": true,
"warranty": "مجاناً سنتان",
"image_url": "https://cdn.mafrservices.com/pim-content/SAU/media/product/750353/1747920603/750353_main.jpg",
"seller_id": "21393",
"brand_code": "05352",
"categories": [
"nfksa1200000",
"nfksa1220000",
"nfksa1220200"
],
"product_id": "750353",
"breadcrumbs": [
{
"id": "NFKSA1220200",
"name": "الهواتف الذكية"
}
],
"seller_name": "alhadaf store co",
"product_type": "NONFOOD",
"quick_glance": [],
"stock_status": "low",
"current_price": 3139,
"regular_price": 5399,
"discount_value": 2260,
"specifications": [
{
"features": [
{
"name": "لون",
"value": "تيتانيوم رمادي"
}
],
"group_code": "11003",
"group_name": "التصميم"
}
],
"available_quantity": 6,
"discount_percentage": 42,
"is_marketplace_product": true
},
"status": "success"
}
}About the Carrefour KSA API
What the API Returns
The get_product endpoint accepts a single required parameter — product_url — which must be a full carrefourksa.com product page URL in the form https://www.carrefourksa.com/mafsau/<ar|en>/<category>/. The response includes the product title returned in whichever language the URL targets (Arabic or English), along with brand, barcode (EAN/GTIN string), and the canonical url.
Pricing and Availability Fields
Pricing fields cover both current promotional price and the regular (pre-discount) price, both denominated in SAR as confirmed by the currency field. When a product is out of stock, both price fields return null and in_stock is set to false. This makes it straightforward to distinguish temporarily unavailable products from active listings without additional logic.
Images and Additional Metadata
The images array contains all gallery image URLs associated with the product, while image_url provides the main product image as a direct string for cases where only one image is needed. The seller_id field identifies the seller on the Carrefour KSA marketplace. The warranty field returns the warranty description text when the site lists one, or null when absent — useful for filtering electronics and appliance listings that require warranty data.
The Carrefour KSA API is a managed, monitored endpoint for carrefourksa.com — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when carrefourksa.com 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 carrefourksa.com 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 drops on electronics by polling
get_productand comparing current vs. regular price fields - Build a product catalog for Carrefour KSA goods using title, brand, barcode, and image_url
- Monitor in_stock status across a watchlist of Carrefour KSA product URLs
- Aggregate EAN barcodes from Carrefour KSA to cross-reference with other regional retailers
- Display warranty information alongside product listings in a comparison shopping tool
- Sync seller IDs to identify which third-party sellers are active on the Carrefour KSA marketplace
- Pull full image galleries for product pages in a localized Arabic or English storefront
| 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 KSA have an official developer API?+
What does `get_product` return when a product is out of stock?+
null, and in_stock is set to false. The remaining fields — title, brand, barcode, images, and warranty — are still returned if the product page is accessible.Does the API support fetching product reviews or ratings?+
Can I retrieve a list of products from a category or search results page?+
get_product endpoint operates on a single product page URL and returns data for that one product. You can fork this API on Parse and revise it to add a category or search listing endpoint.Does language selection affect the data returned?+
product_url parameter determines the response language. URLs containing /ar/ return an Arabic title, while URLs containing /en/ return an English title. All other fields — prices, barcode, availability, and images — are language-independent.