Carrefour

Carrefour Search API

Search Carrefour groceries and general merchandise by keyword on carrefour.fr (France, EUR) and on the Argentina (ARS), Romania (RON) and Belgium (EUR, French or Dutch) sites. On carrefour.fr: filter by brand, promotion, Nutri-Score, organic, Carrefour's own brands and price range; sort by price, price per kg or litre, or rating; pass store for one store's shelf prices and range instead of the national online price. 30 items per page with EAN, title, brand, price, unit price, packaging, Nutri-Score, Eco-Score, rating, availability, the promotion (label, loyalty-card flag, dates) and the marketplace seller, plus total, every facet with counts and the site's spelling correction. Titles come in the market's language. Costs 1 credit per request (2 on be).

POST/api/v1/carrefour/search

Authorizations

Authorizationstringheaderrequired

Bearer authentication header of the form Bearer <token>, where <token> is your Scavio API key (e.g. Bearer sk_live_your_key).

Body

application/json

querystringrequired

Search keywords, 1-200 characters. On fr the site corrects misspellings (corrected_query).

Example: nutella

countryenum<string>default:fr

The national Carrefour site. Titles come back in the market's language, prices in its currency. Filters, store and sorts beyond price are fr only.

Example: fr

fr — France (carrefour.fr), EUR, French. The default, and the only market with filters, facets, store prices and every endpoint.
ar — Argentina (carrefour.com.ar), ARS, Spanish. Sorts relevance and the two price sorts.
ro — Romania (carrefour.ro), RON, Romanian. Sorts relevance and the two price sorts.
be — Belgium (carrefour.be), EUR, French or Dutch (language). Relevance only. 2 credits per call.

languageenum<string>

Only for country be: fr (default) or nl. Every other market has one language, and sending language there is a 400.

Example: nl

fr — French. The default on be.
nl — Dutch, on be.

storestring | integer

fr only: prices and assortment at one Carrefour store. A store_ref or a pickup_refs[].ref from the stores endpoint, or stores[].store.ref from store-availability (digits). Without it, prices are carrefour.fr's national online price. The response says which one you got in store and price_scope. An unknown ref is a charged 404.

Example: 840093

pageinteger

Results page, 1-based, up to 500. Defaults to 1. 30 items per page on fr (ar and ro 24, be 36).

Example: 2

sortenum<string>default:relevance

The order of the listing. ar and ro take relevance and the two price sorts; be takes relevance only.

relevance — The site's own order. The default.
price_low_to_high — Cheapest first.
price_high_to_low — Most expensive first.
unit_price_low_to_high — fr: lowest price per kg or litre first.
unit_price_high_to_low — fr: highest price per kg or litre first.
top_rated — fr: best rated first.

brandstring

fr: one brand as the Marque facet lists it (facets[id=facet_marque].values[].label, e.g. NUTELLA, CARREFOUR BIO). Another casing is matched to the facet's own.

Example: LACTEL

promotionstring

fr: one value of the Promotions facet (facets[id=facet_promotions].values[].label), as the site writes it: Toutes les promotions, Remises immédiates, Vu en catalogue, Avantage Fidélité...

Example: Remises immédiates

nutriscoreenum<string>

fr: only this Nutri-Score: A, B, C, D or E.

Example: A

organicboolean

fr: only organic products.

Example: true

carrefour_brandsboolean

fr: only Carrefour's own brands.

Example: true

min_pricenumber

fr: lowest price in EUR.

Example: 2

max_pricenumber

fr: highest price in EUR.

Example: 10

Request

from scavio import ScavioClient

client = ScavioClient(api_key="sk_live_your_key")

# Cheapest milk per litre on carrefour.fr, national online price.
res = client.carrefour.search(query="lait", sort="unit_price_low_to_high")["data"]
print(res["total"], "items,", res["price_scope"])
for item in res["items"]:
    promo = item["promotion"]["label"] if item["promotion"] else ""
    print(item["ean"], item["title"], item["price"], item["unit_price_label"], promo)

Response

"query": "nutella",

"corrected_query": null,

"results_type": "match",

"sort": "relevance",

"applied_filters": {},

"total": 49,

"total_pages": 2,

"page": 1,

"page_size": 30,

"count": 30,

"store": "national",

"price_scope": "national online price; prices and assortment differ by store (pass store for one store's prices)",

"country": "fr",

"language": "fr",

"currency": "EUR"

"response_time": 1515

}

from scavio import ScavioClient client = ScavioClient(api_key="sk_live_your_key") # Cheapest milk per litre on carrefour.fr, national online price. res = client.carrefour.search(query="lait", sort="unit_price_low_to_high")["data"] print(res["total"], "items,", res["price_scope"]) for item in res["items"]: promo = item["promotion"]["label"] if item["promotion"] else "" print(item["ean"], item["title"], item["price"], item["unit_price_label"], promo)