# Carrefour.es Grocery Products, Prices & EAN Scraper (`abotapi/carrefour-es-scraper`) Actor

Scrape Carrefour Spain (carrefour.es) products. Search by keyword, browse a category, or paste product/category links. Returns name, brand, price, unit price, promotion, stock, category, image, and, with details, the barcode (EAN), ingredients, allergens, nutrition, extra images and rating.

- **URL**: https://apify.com/abotapi/carrefour-es-scraper.md
- **Developed by:** [Abot API](https://apify.com/abotapi) (community)
- **Categories:** E-commerce, Automation, Developer tools
- **Stats:** 1 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $1.50 / 1,000 product results

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.
Actors are written with capital "A".

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

## Carrefour Spain Product Scraper

Scrape products from **Carrefour Spain** (`carrefour.es`) — the supermarket and
general‑retail catalog. Search by keyword, browse a category, fetch specific
products, or paste links. Every product comes back as one flat record with price,
unit price, promotion, stock and category; enable details to add the barcode
(EAN), ingredients, allergens, the full nutrition panel, extra images and the
product's aggregate rating.

### What you can do

- **Search by keyword** — e.g. `leche` (milk), `cerveza` (beer), `pañales`
  (diapers) — with price, promotion, stock and rating filters, plus sorting.
- **Browse a category** — paste a Carrefour category page link and walk it across
  all its pages.
- **Paste links or ids** — mix product links, bare product ids and category links
  in one list and let the actor route each entry. Product links return full detail.
- **Resume & recurring updates** — turn on Incremental mode to get only NEW,
  UPDATED, and REAPPEARED products on every scheduled run, or resume one
  specific interrupted crawl with `resumeFromRunId`.

### Input

| Field | Description |
|---|---|
| **Mode** | `search`, `category` or `url`. |
| **Search keywords** | Keywords to search (search mode). Each is searched separately. |
| **Category links** | Carrefour category page links to browse (category mode). |
| **Carrefour Spain links or product ids** | Product links, bare product ids and category links to scrape directly, mixed freely (url mode). Product links return full detail. |
| **Sort by** | Relevance, price ↑/↓, unit price ↑/↓, or name. Applied over the collected products. |
| **Minimum average rating** | Keep only products rated at least N stars (needs details). |
| **Only on promotion** | Keep only products with a reduced price. |
| **Only in stock** | Keep only products currently in stock. |
| **Min / Max price (EUR)** | Keep only products within a price range. |
| **Fetch product details** | Add barcode, ingredients, allergens, nutrition, extra images and rating. On by default. |
| **Max products** | The run's cap on how many products to return. Default 20; `0` = unlimited. |
| **Max pages per keyword / category** | Result pages walked per keyword / category / link. Default `0` = unlimited — walks every page until *Max products* is hit or a page repeats no new products. |
| **Resume from a previous run** | Continue one specific previous run/dataset: products already collected there are skipped, so this run only appends new products. For recurring daily monitoring of the same search, use Incremental mode instead — see "Resume & recurring updates" below. |
| **Incremental changes for scheduled runs** | Daily/recurring monitoring of this same search. First run returns everything as `NEW`; later runs return only `NEW`/`UPDATED`/`REAPPEARED` by default. See "Resume & recurring updates" below. |
| **State key** | Optional name for a monitoring campaign, so its incremental state stays stable or is deliberately shared. Auto-derived from your search/detail settings when left empty. |
| **Emit unchanged products** | Incremental mode only. Also return products unchanged since the last run, marked `UNCHANGED`. Adds and bills extra rows you already have. |
| **Emit expired products** | Incremental mode only. Also return products from a previous run no longer found, marked `EXPIRED`, once a run has fully scanned the search (not capped, not a resume). Adds and bills extra synthetic rows. |
| **Proxy** | Apify Proxy — a Spanish residential exit by default (required, see below). |
| `mcpConnectors` | Optional MCP connectors to export results into (Notion, Linear, Airtable, Apify). |
| `notionParentPageUrl` | Notion connector only: page under which item pages are created. |
| `maxNotifyListings` | Cap on items exported to each connector per run. Does not affect the dataset. |

### Output

One record per product. With details off you get the listing‑level fields; with
details on you also get barcode, ingredients, allergens, nutrition and rating.
Example (illustrative values):

```json
{
  "productId": "520661336",
  "name": "Leche semidesnatada marca ejemplo brik 1 L",
  "brand": "Marca Ejemplo",
  "ean": "8400000000000",
  "price": 0.99,
  "regularPrice": 1.19,
  "unitPrice": 0.99,
  "unitPriceMeasure": "l",
  "currency": "EUR",
  "onPromotion": true,
  "discountPercentage": 17,
  "inStock": true,
  "stock": 240,
  "categoryId": "cat00000",
  "ingredients": "Leche de vaca semidesnatada.",
  "allergens": ["Leche"],
  "nutrition": [{ "name": "Valor energético", "value": "46 kcal" }],
  "rating": 4.5,
  "reviewCount": 12,
  "reviews": [],
  "image": "https://static.carrefour.es/example/000000.jpg",
  "images": ["https://static.carrefour.es/example/000000.jpg"],
  "url": "https://www.carrefour.es/supermercado/example/R-520661336/p",
  "searchMode": "search",
  "scrapedAt": "2026-01-01T00:00:00Z"
}
```

**Ratings & reviews.** Products carry an aggregate rating (`rating`,
`reviewCount`) where the catalog exposes one. Individual customer review *text* is
not published in the catalog, so the `reviews` array is present but empty on rated
products, and rating fields are simply absent on products with no rating (never
fabricated zeros).

**Incremental mode only.** When `incrementalMode` is on, every returned record also
carries:

| Field | Description |
|---|---|
| `changeType` | `NEW` | `UPDATED` | `UNCHANGED` | `REAPPEARED` | `EXPIRED` |
| `changedFields` | Top-level fields that changed since last seen; non-empty only for `UPDATED` |
| `firstSeenAt` | When this product was first observed by this monitoring campaign |
| `lastSeenAt` | When this product was last observed |

### Resume & recurring updates

There are two different things here — pick the one that matches what you're doing:

| Need | Use |
| --- | --- |
| A crawl stopped and should continue | `resumeFromRunId` / automatic checkpoint recovery |
| Run the same search every day and receive only changes | `incrementalMode` |
| Keep separate daily campaigns for similar searches | distinct `stateKey` values |
| Run a normal full snapshot | leave both off |

**Resume** (`resumeFromRunId`) continues one specific interrupted or previous large crawl: paste a run ID or dataset ID and this run skips products already collected there, returning only the remaining new products. An automatic same-run checkpoint also protects against platform migrations/Resurrects without any input needed.

**Incremental mode** (`incrementalMode`) is for a schedule (for example, daily): the actor remembers the previous run of the *same* search by itself, so you never paste a run ID. The first run returns everything as `NEW`. Later runs return only `NEW`, `UPDATED`, and `REAPPEARED` products by default — duplicates and unchanged products are suppressed (and not charged). Turn on `emitUnchanged` or `emitExpired` only when you also want those rows returned (and billed for). State is isolated per search/category/URL and detail-mode setup automatically; set `stateKey` to name or deliberately share a monitoring campaign.

Scheduled-run example — same search, run daily:

Day 1 (first run ever for this search):

```json
{ "mode": "search", "queries": ["leche"], "incrementalMode": true }
```

→ every product comes back with `"changeType": "NEW"`.

Day 2 (the schedule fires again, identical input):

```json
{ "mode": "search", "queries": ["leche"], "incrementalMode": true }
```

→ products whose price/promotion/stock/etc. changed come back as `"changeType": "UPDATED"` with `changedFields` listing what changed, brand-new products come back as `"changeType": "NEW"`, products that vanished and came back come back as `"changeType": "REAPPEARED"` — and products that are still there, unchanged, are **not** returned at all (suppressed, not charged) unless `emitUnchanged` is on.

### Proxy & connection

Apify Proxy is **required**. Carrefour Spain serves its catalog only to Spanish
residential connections, so the actor uses a **Spanish residential** exit by
default. On the Free plan (no residential proxy access) results may be empty —
enable Apify Proxy or upgrade your plan at <https://apify.com/pricing>.

### Send results into your apps (MCP connectors)

Optionally pipe results into the apps you already use through Model Context Protocol (MCP) connectors. Authorize a connector once under Apify, Settings, Integrations, then select it in the `mcpConnectors` field. Each connector receives a condensed, human-readable summary per product (title plus key fields), while the complete record always stays in the Apify dataset. For Notion, set `notionParentPageUrl` to the page the item pages should be created under. Supported connectors: Notion, Linear, Airtable, and Apify. Leave the field empty to skip; it never changes the dataset output.

### Notes

- Search and category result pages are walked forward one page at a time until
  *Max products* is reached, the storefront runs out of pages, or (with the
  default unlimited *Max pages*) a page repeats no new products.
- Long runs survive an Apify server migration or a manual Resurrect: progress
  is checkpointed, so a resumed run continues without re-scraping or
  double-charging products already collected.
- `searchMode` on each record reports how it was found: `search`, `category`, or
  `product` when it came from a pasted product link or id.
- Prices are in **EUR**. Spanish price strings are normalized to numbers.
- Duplicate products (same id) are returned once per run.

# Actor input Schema

## `mode` (type: `string`):

Choose 'search' for keywords + filters, 'category' to browse a category by its Carrefour category link, or 'url' to scrape pasted Carrefour Spain links — product links, bare product ids and category links are all accepted.

## `queries` (type: `array`):

Only used when mode = search — ignored in every other mode. One or more keywords to search, for example 'leche' (milk) or 'cerveza' (beer). Each keyword is searched separately.

## `categories` (type: `array`):

Only used when mode = category — ignored in every other mode. One or more Carrefour category page links, each walked separately across its result pages. To get one: open carrefour.es, browse to the category you want, and copy the address from your browser — a category address ends in /catNNNNN/c , for example https://www.carrefour.es/supermercado/lacteos-huevos/leche/cat20093/c

## `sortBy` (type: `string`):

How to order the collected products. Applied over the products gathered in the run before they are returned.

## `minRating` (type: `string`):

Optional. Only keep products whose average rating is at least this many stars. Requires details (ratings are collected during 'Fetch product details'). Products with no rating are excluded when this is set.

## `onPromotionOnly` (type: `boolean`):

Optional. Keep only products currently on promotion (a reduced price versus the regular price).

## `inStockOnly` (type: `boolean`):

Optional. Keep only products currently in stock.

## `minPrice` (type: `integer`):

Optional. Only keep products priced at or above this amount.

## `maxPrice` (type: `integer`):

Optional. Only keep products priced at or below this amount.

## `urls` (type: `array`):

Only used when mode = url — ignored in every other mode. Mix freely: product pages under /R-<id>/p , category pages under /catNNNNN/c , or bare product ids such as 521007071 . Multiple entries supported.

## `fetchDetails` (type: `boolean`):

Collect each product's full detail (barcode / EAN, ingredients, allergens, nutrition panel, extra images) plus its aggregate rating. Turn off for a faster, lighter run that returns only the listing-level fields (name, brand, price, unit price, promotion, stock, image).

## `maxItems` (type: `integer`):

Maximum number of products to return across the whole run. This is the run's cap. Use 0 for unlimited.

## `maxPages` (type: `integer`):

Maximum result pages walked per keyword / category / link. 0 = unlimited (walk all pages) — the run then stops only at Max products or when a page repeats no new products.

## `resumeFromRunId` (type: `string`):

Paste a previous run ID or dataset ID to continue a large crawl of products without returning or charging for products already collected there. Use this after an interrupted run, or when continuing a product catalogue pull in another run. For recurring daily monitoring of the same search, use Incremental mode below instead.

## `incrementalMode` (type: `boolean`):

Turn this on for daily or recurring monitoring. The first run returns all matching products as NEW. Later runs normally return only NEW, UPDATED, and REAPPEARED products. Turn on "Emit unchanged" or "Emit expired" only when you also want those products returned (and billed). State is kept separately for each search/category/URL and detail-mode setup; use State key when you want to name or deliberately share a monitoring campaign. To continue one specific interrupted run instead, use Resume from a previous run above.

## `stateKey` (type: `string`):

Optional. Name this monitoring campaign to keep its state stable, or to deliberately share state across differently-configured runs. Leave empty to let the actor derive a key automatically from the search/category/URL and detail settings — different searches then never mix state with each other.

## `emitUnchanged` (type: `boolean`):

Off by default. Turn on to also return products that have not changed since the last run, marked UNCHANGED. This returns — and bills — extra rows you already have, so leave it off unless you specifically want the full snapshot every run.

## `emitExpired` (type: `boolean`):

Off by default. Turn on to also return products that were present in a previous run but are no longer found, marked EXPIRED. Only produced once a run has fully scanned the tracked search — not when Max products capped it or when Resume was used. This returns — and bills — extra synthetic rows, so leave it off unless you need expiry tracking.

## `proxy` (type: `object`):

Apify Proxy is required for reliable results. The actor connects through a Spanish residential exit by default.

## `mcpConnectors` (type: `array`):

Optionally send results into the apps you already use, via Model Context Protocol (MCP) connectors. Authorize one under Apify, Settings, API & Integrations, then select it here. Notion gets a rich page-per-item export; other connectors get a best-effort write/digest. Leave empty to skip; never changes the dataset output. Supported: Notion (https://mcp.notion.com/mcp), Linear (https://mcp.linear.app/sse), Airtable (https://mcp.airtable.com/mcp), Apify (https://mcp.apify.com).

## `notionParentPageUrl` (type: `string`):

URL or id of the Notion page under which item pages are created. Required to enable the Notion export; ignored by other connectors.

## `maxNotifyListings` (type: `integer`):

Cap on items written to each connector per run. Does not affect the dataset.

## Actor input object example

```json
{
  "mode": "search",
  "queries": [
    "leche"
  ],
  "categories": [
    "https://www.carrefour.es/supermercado/lacteos-huevos/leche/cat20093/c"
  ],
  "sortBy": "relevance",
  "minRating": "0",
  "onPromotionOnly": false,
  "inStockOnly": false,
  "urls": [
    "https://www.carrefour.es/supermercado/R-521007071/p",
    "https://www.carrefour.es/supermercado/lacteos-huevos/leche/cat20093/c"
  ],
  "fetchDetails": true,
  "maxItems": 20,
  "maxPages": 0,
  "incrementalMode": false,
  "emitUnchanged": false,
  "emitExpired": false,
  "proxy": {
    "useApifyProxy": true,
    "apifyProxyGroups": [
      "RESIDENTIAL"
    ],
    "apifyProxyCountry": "ES"
  },
  "maxNotifyListings": 50
}
```

# Actor output Schema

## `overview` (type: `string`):

No description

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "mode": "search",
    "queries": [
        "leche"
    ],
    "categories": [
        "https://www.carrefour.es/supermercado/lacteos-huevos/leche/cat20093/c"
    ],
    "urls": [
        "https://www.carrefour.es/supermercado/R-521007071/p",
        "https://www.carrefour.es/supermercado/lacteos-huevos/leche/cat20093/c"
    ],
    "incrementalMode": false,
    "emitUnchanged": false,
    "emitExpired": false,
    "proxy": {
        "useApifyProxy": true,
        "apifyProxyGroups": [
            "RESIDENTIAL"
        ],
        "apifyProxyCountry": "ES"
    }
};

// Run the Actor and wait for it to finish
const run = await client.actor("abotapi/carrefour-es-scraper").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "mode": "search",
    "queries": ["leche"],
    "categories": ["https://www.carrefour.es/supermercado/lacteos-huevos/leche/cat20093/c"],
    "urls": [
        "https://www.carrefour.es/supermercado/R-521007071/p",
        "https://www.carrefour.es/supermercado/lacteos-huevos/leche/cat20093/c",
    ],
    "incrementalMode": False,
    "emitUnchanged": False,
    "emitExpired": False,
    "proxy": {
        "useApifyProxy": True,
        "apifyProxyGroups": ["RESIDENTIAL"],
        "apifyProxyCountry": "ES",
    },
}

# Run the Actor and wait for it to finish
run = client.actor("abotapi/carrefour-es-scraper").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"])
for item in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "mode": "search",
  "queries": [
    "leche"
  ],
  "categories": [
    "https://www.carrefour.es/supermercado/lacteos-huevos/leche/cat20093/c"
  ],
  "urls": [
    "https://www.carrefour.es/supermercado/R-521007071/p",
    "https://www.carrefour.es/supermercado/lacteos-huevos/leche/cat20093/c"
  ],
  "incrementalMode": false,
  "emitUnchanged": false,
  "emitExpired": false,
  "proxy": {
    "useApifyProxy": true,
    "apifyProxyGroups": [
      "RESIDENTIAL"
    ],
    "apifyProxyCountry": "ES"
  }
}' |
apify call abotapi/carrefour-es-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.apify.com/?tools=abotapi/carrefour-es-scraper",
                "--header",
                "Authorization: Bearer <YOUR_API_TOKEN>"
            ]
        }
    }
}

```

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/9NHdUG2ylD15IIXrG/builds/tdgrGwWxk6swajiA1/openapi.json