# Castorama.fr - Products, Prices & Reviews (`abotapi/castorama-fr-scraper`) Actor

Scrape Castorama.fr DIY and home-improvement products by keyword, category, or URL. Extract prices, original prices, promotions, seller details, categories, specifications, ratings, and customer reviews. Incremental mode tracks product and price changes over time.

- **URL**: https://apify.com/abotapi/castorama-fr-scraper.md
- **Developed by:** [Abot API](https://apify.com/abotapi) (community)
- **Categories:** E-commerce, Automation, Developer tools
- **Features:** Limited permissions
- **Stats:** 7 total users, 1 monthly users, 96.9% runs succeeded, 1 bookmarks
- **User rating**: No ratings yet

## Pricing

from $1.00 / 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/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
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.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## 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.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## Castorama France Scraper: Prices, Promotions, Sellers and Reviews

Castorama Scraper turns Castorama France (castorama.fr) into a clean product data feed. Search by keyword or category, or paste product, category and search-result links, and every product comes back as one flat record with price, was-price, promotion, seller identity, breadcrumb category and rating. Switch on product details to add the full description, technical specifications and customer reviews, then export to JSON, CSV or Excel, or pull results straight into your app through the API.

### Why This Scraper?

- **Two ways to find products.** Search by keyword or category name, or paste product, category and search-result links directly, mixed freely in one run.
- **A matching keyword resolves like the site's own search.** Typing a term such as "perceuse" walks the full matching category and its facet set, exactly like typing into the site's own search box, not just a flat keyword match.
- **Genuine promotion detection.** `isOnSpecial`, `originalPrice` and the discount amount are only ever set when the site's own was-price for that item is genuinely higher than the current price, never a marketplace price spread.
- **First-party reviews.** Product detail pulls the site's own embedded review data (author, title, body, rating, date); no third-party review host is involved.
- **Seller-aware.** Every record marks whether it was sold directly by Castorama or by a marketplace partner, with that partner's identity.
- **Built for schedules.** Incremental mode returns only new and changed products on recurring runs, with expired and reappeared tracking once you turn it on, plus a resume option to continue one interrupted crawl.
- **Resilient to the storefront's own occasional maintenance placeholder.** A refused request retries automatically on a fresh connection, within a 25-second budget per page, instead of silently returning fewer products.

### Use Cases

- **Price and promotion monitoring:** track price, was-price and promotion status across a brand or category to catch markdowns as they go live.
- **Marketplace and assortment research:** see which products Castorama sells directly versus through marketplace partners, and compare partner pricing.
- **Catalog and content teams:** pull descriptions, technical specifications and images to enrich a product database.
- **Review and reputation analysis:** collect customer ratings and reviews per product to spot quality issues or standout items.
- **Recurring stock and price feeds:** schedule the actor daily with Incremental mode to feed a price-comparison site or alerting tool with only what changed.

### Data You Get

> Sample shape: values are illustrative placeholders, not from a live record.

| Field | Example |
| --- | --- |
| `productId` / `ean` | `"3666294006226"` |
| `name` | same value as `title` (additive alias) |
| `title` | `"Perceuse Visseuse 20V Exemple + 2 Batteries 1,5 Ah + Chargeur rapide + Malette"` |
| `brand` | `"Nemura"` |
| `price` | `79.99` |
| `currency` | `"EUR"` |
| `originalPrice` | `139.99` (only when a real promotion is present) |
| `discountAmount` / `discountPercentage` | `60.0` / `43` |
| `isOnSpecial` | `true` |
| `promotionLabel` | `"Promotion"` |
| `sellerId` / `sellerName` | `"2131"` / `"Vendeur Partenaire Exemple"` |
| `soldByCastorama` | `false` |
| `category` | `"Visseuse dévisseuse"` |
| `categoryPath` | `[{"name": "Visseuse dévisseuse", "path": "/visseuse-devisseuse/cat_id_0003519.cat"}]` |
| `inStock` | `true` when the site marks the product purchasable online, otherwise `false`; `null` when availability is unknown |
| `availability` | `{"status": "Available", "purchasable": true, "homeDelivery": "Available"}` |
| `images` / `image` | array of image URLs / the first one |
| `url` | `"https://www.castorama.fr/mkp/example/3666294006226_CAFR.prd"` |
| `specifications` | `[{"name": "Tension (en V)", "value": "20V"}]` (with product details on) |
| `description` | the product's full description text (with product details on) |
| `rating` | `4.75` |
| `reviewCount` | `4` |
| `reviews` | `[{"author": "Exemple", "title": "Efficace", "body": "...", "rating": 5, "date": "..."}]` (with product details on) |
| `searchMode` | `"search"`, `"category"`, or `"product"` for a pasted product link |
| `scrapedAt` | `"2026-01-01T00:00:00Z"` |

The Console dataset has four views: Products, Product details, Reviews (one row per review) and Changes (incremental mode).

`name` and `inStock` are new additive fields; existing fields are unchanged. With Incremental mode on, the first run after this update does not flag tracked products as `UPDATED` just because these two fields appeared.

`rating`, `reviewCount` and `reviews` are always present, explicit `null`/`0`/`[]` rather than omitted, on every record, whether product details are on or off. With Incremental mode on, every returned record also carries `changeType`, `changedFields`, `firstSeenAt` and `lastSeenAt`; see "Resume and recurring updates" below for exactly when each `changeType` value is produced.

### How to Use

1. Pick a **mode**: `search` (keywords or category names, with filters) or `url` (paste links).
2. For search mode, list one or more keywords or category links, and set the brand, price, rating, promotion and sort filters you need. For url mode, paste product, category and search-result links, mixed freely.
3. Set **Max products** to cap the run's size and cost, and toggle **Fetch product details** for description, specifications and reviews, then click **Start**.
4. Download the dataset as JSON, CSV or Excel, or read it through the API.

**Search by keyword with filters:**

```json
{
  "mode": "search",
  "queries": ["perceuse"],
  "brand": "Bosch Professional",
  "maxPrice": 150,
  "onPromotionOnly": true,
  "maxItems": 30
}
```

**Supported link shapes (URL mode).** If you leave the `urls` field untouched, url mode now scrapes one example of each shape below (previously it started empty).

| Shape | Example |
|---|---|
| Search that resolves to a category | `https://www.castorama.fr/search?term=perceuse` |
| Search with no category match | `https://www.castorama.fr/search?term=zzxqv` |
| Multi-word search | `https://www.castorama.fr/search?term=peinture+blanche+mate` |
| Category page | `.../cat_id_3796.cat` |
| Paginated category (starts at that page; counts as a partial scan for expired detection) | `.../cat_id_3796.cat?page=2` |
| Filtered category (facet in the link is applied) | `.../cat_id_3796.cat?Marque=Bosch+Professional` |
| Sorted category | `.../cat_id_3796.cat?sort=-product.price` |
| Marketplace product | `https://www.castorama.fr/mkp/<slug>/<ean>_CAFR.prd` |
| Search data route | `https://www.castorama.fr/search.data?term=perceuse&page=1` |

Product links without `/mkp/` (first-party `/<slug>/<ean>_CAFR.prd` links), `.cat.data` links, and `m.` or bare-host links are routed to the shapes above; the link-shape handling is covered by offline tests, and a first-party product link was confirmed to load on the live site. Any link the actor cannot route is skipped with a warning in the log.

**Paste a product link and a category link together:**

```json
{
  "mode": "url",
  "urls": [
    "https://www.castorama.fr/mkp/perceuse-visseuse-20v-nemura-2-batteries-1-5-ah-chargeur-rapide-malette-avec-54-accessoires/3666294006226_CAFR.prd",
    "https://www.castorama.fr/outillage/outillage-electroportatif/perceuse-visseuse-perceuse-a-percussion-et-tournevis-sans-fil/cat_id_3796.cat"
  ],
  "fetchDetails": true
}
```

**Fast listing-only run, sorted and rating-filtered:**

```json
{
  "mode": "search",
  "queries": ["visseuse"],
  "fetchDetails": false,
  "minRating": "4",
  "sortBy": "price_asc",
  "maxItems": 50
}
```

**Daily incremental watch on a category:**

```json
{
  "mode": "search",
  "queries": ["peinture blanche mate"],
  "incrementalMode": true,
  "stateKey": "peinture-blanche-mate-watch"
}
```

#### Run it from your code

Python:

```python
from apify_client import ApifyClient

client = ApifyClient("<YOUR_APIFY_TOKEN>")
run = client.actor("abotapi/castorama-fr-scraper").call(run_input={"mode": "search", "queries": ["perceuse"], "maxItems": 20})
for product in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(product["title"], product["price"], product["currency"])
```

JavaScript:

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

const client = new ApifyClient({ token: '<YOUR_APIFY_TOKEN>' });
const run = await client.actor('abotapi/castorama-fr-scraper').call({ mode: 'search', queries: ['perceuse'], maxItems: 20 });
const { items } = await client.dataset(run.defaultDatasetId).listItems();
```

Or connect it to Make, Zapier, n8n, Google Sheets or webhooks from the **Integrations** tab.

#### Resume and recurring updates

- **Resume** (`resumeFromRunId`) continues one specific interrupted or previous crawl: paste its run ID or dataset ID and this run skips products already collected there, returning only the remaining new products.
- **Incremental mode** (`incrementalMode`) is for scheduling the same search again and again, for example daily. The actor remembers the previous run of the same search by itself, keyed by `stateKey` or an automatically derived key, so you never paste a run ID. The first run for a search returns everything as `NEW`. Later runs return only `NEW` and `UPDATED` (with `changedFields`) products by default; unchanged products are suppressed and not billed unless `emitUnchanged` is on.
- **What counts as a change.** A product is `UPDATED` when any returned field differs from the previous run (price, promotion, stock, rating, review count, title, images, description, specifications). `scrapedAt` and the `reviews` text list are always left out of the comparison, though both stay in the output. Two back-to-back runs of the same search showed no other field changing on its own (images, availability and stock flags stayed identical), so nothing else is left out by default. Use `ignoreFieldsForChanges` to leave out more fields: top-level names such as `images`, or dotted paths for nested fields such as `specifications.value`. Changing this list never re-flags unchanged products, because the saved baseline is compared again with the current list.
- **`EXPIRED`** rows are only produced when `emitExpired` is on, and only on a run that reaches the natural end of every tracked search, meaning no `maxItems` cap was hit, `resumeFromRunId` was not used, and every page was walked to its end. A capped or resumed run skips expiry detection for that run and keeps the previous state as it was.
- **`REAPPEARED`** is not something you see on an early or ordinary run. A product is only ever classified `REAPPEARED` after it was previously marked `EXPIRED` by an earlier `emitExpired` run that completed a full scan, and is then seen again on a later run, whether or not that later run has `emitExpired` on. Until a product has gone through that expiry step once, a product missing on one run and present again on the next is not distinguished from any other `UPDATED`/`UNCHANGED` product, because it was never recorded as gone in the first place.

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

Optionally pipe the scraped results into the apps you already use, through Model Context Protocol (MCP) connectors. This is an extra delivery step after the scrape; the Apify dataset is never changed.

**What gets written to the connector:** a condensed, human-readable summary of each product, not the full JSON. Each item becomes one entry with a title and its key fields flattened to plain text. The complete record always stays in the Apify dataset.

1. Authorize a connector once under Apify, Settings, Integrations (Notion, Linear, Airtable, or Apify).
2. Select it in the "Pipe results into your apps" input field. If the picker is empty, you have not authorized a connector yet.
3. For Notion, also set `notionParentPageUrl` to the page where item pages should be created.

The connection is mediated by Apify's own MCP proxy, so this actor never sees your third-party credentials. Leave the field empty to skip.

### Input Parameters

| Parameter | Type | Default | Description |
| --- | --- | --- | --- |
| `mode` | string | `search` | `search` (keywords or category names, with filters) or `url` (paste product, category or search-result links). |
| `queries` | array | three examples: `["perceuse", "peinture blanche mate", <the Perceuse category link>]` (same as the prefill) | Keywords or Castorama category links to search or browse, search mode only. Each entry is walked separately; a keyword matching a real category resolves straight to that category's full facet set. If you leave `queries` untouched, search mode runs these three examples (previously it stopped with no keywords); every product returned is billed like any other result. |
| `brand` | string | none | Only keep products of this brand, Castorama's own "Marque" facet (case and accents do not matter). If the name matches none of the brands Castorama lists for a search or link, that search or link is skipped with a warning naming close brand values. Narrows search mode and a pasted category/search-result link in url mode; has no effect on a single pasted product link. |
| `sellerCastoramaOnly` | boolean | `false` | Exclude marketplace (third-party seller) offers. Same scope as `brand`. |
| `minPrice` | integer | none | Keep only products priced at or above this amount, in EUR. Same scope as `brand`. |
| `maxPrice` | integer | none | Keep only products priced at or below this amount, in EUR. Same scope as `brand`. |
| `minRating` | string | `0` | Keep only products whose average rating is at least this many stars: `0`, `3`, `4`, or `5`. Same scope as `brand`. |
| `urls` | array | one example link per supported shape (see the table above) | Castorama France links to scrape directly, url mode only. Mix product, category and search-result links freely; each is routed automatically. |
| `onPromotionOnly` | boolean | `false` | Keep only products currently flagged with a real promotion, a genuine prior price for the same item. Applies to every result in either mode, including a single pasted product link. |
| `inStockOnly` | boolean | `false` | Keep only products the site currently marks purchasable online, checked client-side against each product's own status. Same scope as `onPromotionOnly`. |
| `sortBy` | string | `relevance` | Order results: `relevance`, `price_asc`, `price_desc`, `rating_desc`, `newness`, or `best_seller`. Same scope as `onPromotionOnly`, though sorting has no visible effect on a single pasted product link. |
| `fetchDetails` | boolean | `true` | Also collect each product's description, technical specifications and customer reviews. Turn off for a faster run returning only listing-level fields for products found by search or category browsing; a pasted product link always fetches full detail regardless of this setting. |
| `maxItems` | integer | `20` | Maximum number of products to return across the whole run. `0` means the hard limit of 100000 products; larger values are clamped to it. |
| `maxPages` | integer | `0` | Maximum result pages walked per keyword, category or link. `0` means unlimited: the run then stops at Max products, or when a page repeats no new products. |
| `resumeFromRunId` | string | none | Continue one specific interrupted or previous run: products already collected there are skipped rather than returned or charged again. For recurring monitoring of the same search, use `incrementalMode` instead. |
| `incrementalMode` | boolean | `false` | Turn on for scheduled or recurring runs of the same search. The actor remembers the previous run itself; see "Resume and recurring updates" above. |
| `stateKey` | string | none | Name this monitoring campaign, or deliberately share state across differently configured runs. Left empty, a key is derived automatically from the search/URL and filter/detail settings. |
| `emitUnchanged` | boolean | `false` | Incremental mode only. Also return, and bill for, products unchanged since the last run, marked `UNCHANGED`. |
| `ignoreFieldsForChanges` | array | `[]` | Incremental mode only. Fields (or dotted nested paths) that never make a product `UPDATED` and are not listed in `changedFields`. They stay in the output. |
| `emitExpired` | boolean | `false` | Incremental mode only. Also return, and bill for, products no longer found, marked `EXPIRED`, once a run has fully scanned the tracked search. |
| `proxy` | object | `{"useApifyProxy": true}` | Connection settings. Apify Proxy, automatic/datacenter tier, by default. A refused connection falls back to a backup connection automatically. |
| `mcpConnectors` | array | none | Optional: send a summary of each product to apps you authorized under Integrations (Notion, Linear, Airtable, Apify). |
| `notionParentPageUrl` | string | none | Notion connector only: page under which item pages are created. |
| `maxNotifyListings` | integer | `50` | Cap on items exported to each connector per run. Does not affect the dataset. |

### Output Example

> Sample shape: values are illustrative placeholders, not from a live record.

```json
{
  "productId": "3666294006226",
  "ean": "3666294006226",
  "title": "Perceuse Visseuse 20V Exemple + 2 Batteries 1,5 Ah + Chargeur rapide + Malette",
  "brand": "Nemura",
  "price": 79.99,
  "currency": "EUR",
  "originalPrice": 139.99,
  "discountAmount": 60.0,
  "discountPercentage": 43,
  "isOnSpecial": true,
  "promotionLabel": "Promotion",
  "sellerId": "2131",
  "sellerName": "Vendeur Partenaire Exemple",
  "soldByCastorama": false,
  "category": "Visseuse dévisseuse",
  "categoryPath": [
    { "name": "Visseuse dévisseuse", "path": "/visseuse-devisseuse/cat_id_0003519.cat" },
    { "name": "Perceuse visseuse", "path": "/perceuse-visseuse/cat_id_0003518.cat" }
  ],
  "availability": { "status": "Available", "purchasable": true, "homeDelivery": "Available", "clickAndCollect": true, "inStore": false },
  "images": ["https://media.castorama.fr/is/image/Castorama/example.jpg"],
  "image": "https://media.castorama.fr/is/image/Castorama/example.jpg",
  "url": "https://www.castorama.fr/mkp/example/3666294006226_CAFR.prd",
  "specifications": [{ "name": "Marque", "value": "Nemura" }, { "name": "Tension (en V)", "value": "20V" }],
  "description": "Perceuse visseuse sans fil 20V avec deux batteries, chargeur rapide et malette de rangement.",
  "rating": 4.75,
  "reviewCount": 4,
  "reviews": [
    { "author": "Exemple", "title": "Efficace", "body": "Facile à utiliser.", "rating": 5, "date": "2026-07-08T15:18:22.000+00:00" }
  ],
  "searchMode": "search",
  "scrapedAt": "2026-01-01T00:00:00Z"
}
```

### Plan Requirement

The default connection, Apify Proxy on its automatic/datacenter tier, works out of the box. The storefront's own edge occasionally serves a maintenance placeholder to a share of connections regardless of tier or country, and the actor retries on a fresh connection when this happens. If the selected connection is refused (for example residential proxies on an Apify free plan, which does not include them), the run logs a boxed warning ("The selected connection is unavailable to this run. Apify free plans do not include residential proxies. Continuing on a backup connection; some pages may still be unavailable.") and continues on a backup connection, noting "Served over the backup connection (the default connection was unavailable)." once pages load. For large or frequent runs, a paid plan with the residential proxy group under Connection gives more headroom.

### FAQ

#### How much does it cost?

Three events are charged. **Actor start** is charged once per run. **Dataset item** is charged once per product row pushed to the dataset. **Detail enrichment** is charged once per product that reaches the dataset with its description, specifications and reviews fetched: products found by search or category browsing only when Fetch product details is on, and a pasted product link always, since it always fetches full detail regardless of that setting. Never charged for an unchanged product that Incremental mode suppressed, nor for a product that failed to load. The **Pricing** tab shows current rates. Use **Max products** to cap the cost of any run.

#### Is it legal to scrape Castorama?

This actor collects only publicly available product data. You are responsible for how you use it: follow Castorama's terms and the laws that apply to you, and get legal advice if you plan commercial redistribution. Prices, descriptions, images and reviews may be subject to third-party rights.

#### Can I get only new or changed products on a schedule?

Yes. Schedule the actor from the **Schedules** tab and turn on **Incremental mode**. Each run then returns only `NEW` and `UPDATED` products by default; unchanged products are not billed unless **Emit unchanged** is on. `EXPIRED` is returned only on a run that has **Emit expired** on and scans the whole tracked search; `REAPPEARED` is then returned on any later run that finds a product an earlier such run had marked expired.

#### Why didn't Brand, price range or rating apply to my pasted product link?

Those three filters narrow a search, or a pasted category/search-result link, but a single pasted product link already names one specific product, so there is nothing left to narrow. Only **Only products on promotion**, **Only purchasable products** and **Sort by** are still checked against a pasted product link.

#### Why did a run return fewer products than expected, or nothing at all?

Filters (brand, price, rating, promotion, in-stock) narrow the result set, sometimes to zero: try broadening them or check the links you provided. The storefront's edge can also intermittently refuse a share of requests, in which case the actor retries automatically on a fresh connection. If no page loads at all, the run fails with a clear message instead of finishing as an empty success (see the next question).

#### Why did my run fail instead of returning an empty dataset?

A run only fails outright when the input itself cannot be honoured: an invalid `resumeFromRunId`, or combining `resumeFromRunId` with Incremental mode on a state key that already has tracked products, since merging the two could corrupt the monitoring baseline. A run also fails when no results page could be loaded at all, so a connection problem is never mistaken for an empty search. The failure message is one of three: "The proxy connection was refused for this account, so no page could be read. Your Apify plan does not include proxy access; a paid plan is required" (every connection refused, including your own proxy URLs if their credentials are invalid); "No results: residential proxies are unavailable on this run (Apify free plans do not include them), and the backup connection could not load the requested Castorama.fr pages" (free plan, backup connection reachable but the site served nothing usable); or "Could not load any results page (the requests failed), so nothing was collected. This is a connection problem, not an empty search. Please try again later." A run where some pages loaded and others did not returns the partial result.

#### Can I use it with AI agents or MCP?

Yes. Call it from any Apify integration or MCP client, and use the connector field to push results into Notion, Linear or Airtable.

### 🔗 Want more e-commerce data?

Pair this actor with these related scrapers from the same team:

<table>
<tr><td>🥦 <a href="https://apify.com/abotapi/leclerc-fr-scraper"><b>E.Leclerc Scraper</b></a><br>Scrape E.Leclerc France (e.leclerc) grocery and retail products. Search by keyword or...</td><td>🥦 <a href="https://apify.com/abotapi/auchan-fr-scraper"><b>Auchan France Scraper</b></a><br>Scrape Auchan.fr products: grocery, drinks, household and general merchandise. Real price...</td></tr>
<tr><td>🔌 <a href="https://apify.com/abotapi/leroymerlin-es-scraper"><b>LeroyMerlin.es Scraper</b></a><br>Scrape Leroy Merlin Spain (leroymerlin.es) DIY and home-improvement products: price...</td><td>🛒 <a href="https://apify.com/abotapi/obi-de-scraper"><b>OBI.de Scraper</b></a><br>Scrape OBI (obi.de) DIY/home-improvement products: current + strike-through original...</td></tr>
<tr><td>🛒 <a href="https://apify.com/abotapi/decathlon-es-scraper"><b>Decathlon.es</b></a><br>Scrape Decathlon Spain (decathlon.es) sporting goods: current price plus strike-through...</td><td>📰 <a href="https://apify.com/abotapi/veepee-scraper"><b>Veepee Scraper</b></a><br>Scrape Veepee flash sales: live campaigns with brands, dates and discounts plus per-sale...</td></tr>
</table>

👉 [Browse all abotapi scrapers](https://apify.com/abotapi)

### 💬 Support

- 🐞 **Found a bug or a missing field?** Open a ticket on the [Issues tab](https://apify.com/abotapi/castorama-fr-scraper/issues/open). We usually reply within hours.
- 🛠️ **Need another site, extra fields or a private build?** Email <contact@abotapi.com>.
- ⭐ **Enjoying it?** A quick review on the actor page helps other users find it.

# Actor input Schema

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

Choose 'search' for keywords/categories with filters, or 'url' to scrape pasted Castorama France links — product links, category links and search-result links are all accepted.

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

One or more keywords (e.g. 'perceuse', 'peinture blanche mate') or Castorama category page links, each searched/walked separately. Left untouched, the three examples below are scraped. A category link ends in cat_id\_<digits>.cat, for example https://www.castorama.fr/outillage/outillage-electroportatif/perceuse-visseuse-perceuse-a-percussion-et-tournevis-sans-fil/cat_id_3796.cat

## `brand` (type: `string`):

Optional. Only keep products of this brand, matched against Castorama's own 'Marque' facet (e.g. 'Bosch Professional', 'Makita', 'DeWalt'). A name that matches no listed brand skips that search or link with a warning.

## `sellerCastoramaOnly` (type: `boolean`):

Optional. Exclude marketplace (third-party seller) offers — Castorama's own 'Vendu par = Castorama' facet.

## `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.

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

Optional. Only keep products whose average rating is at least this many stars — Castorama's own 'Évaluation' facet.

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

Only used when mode = url — ignored in search mode. Mix freely: product pages ending in .prd, category pages ending in cat_id\_<digits>.cat, or search-result links like /search?term=.... Page (?page=N), facet (e.g. ?Marque=Bosch+Professional) and sort (?sort=...) parameters in a link are honoured. Multiple entries supported.

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

Optional. Keep only products currently flagged with a real promotion (a genuine prior price for the same item) — Castorama's own 'Type d'offre = Promotion' facet.

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

Optional. Keep only products the site currently marks as purchasable online. Applied client-side against each product's own status (Castorama's in-store stock facet needs a postal code and is not covered).

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

How to order results — Castorama's own sort options.

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

Collect each product's full detail: description, technical specifications, and customer reviews (author, title, body, rating, date). Turn off for a faster, lighter run that returns only the listing-level fields (title, brand, price, was-price, seller, breadcrumb, rating summary).

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

Maximum number of products to return across the whole run. This is the run's cap. 0 means the hard limit of 100000 products.

## `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.

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

Apify Proxy — a rotating connection so retries can route around the storefront's occasional maintenance placeholder. Datacenter by default.

## `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. 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. A product counts as UPDATED when any of its returned fields changes (price, promotion, stock, rating, review count, title, images, description, specifications and so on); the scrape timestamp and the review texts list are never compared, and you can exclude more fields below. Turn on "Emit unchanged" or "Emit expired" only when you also want those products returned (and billed). State is kept separately for each search/URL and filter/detail 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/URL and filter/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.

## `ignoreFieldsForChanges` (type: `array`):

Field names that must NOT make a product count as UPDATED, for example images or description. Use a dotted path for a nested field, e.g. specifications.value. The fields stay in the output; they are just not compared and never listed in changedFields. The scrape timestamp and the review texts list are always ignored. Only used when Incremental mode is on.

## `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": [
    "perceuse",
    "peinture blanche mate",
    "https://www.castorama.fr/outillage/outillage-electroportatif/perceuse-visseuse-perceuse-a-percussion-et-tournevis-sans-fil/cat_id_3796.cat"
  ],
  "sellerCastoramaOnly": false,
  "minRating": "0",
  "urls": [
    "https://www.castorama.fr/search?term=perceuse",
    "https://www.castorama.fr/search?term=zzxqv",
    "https://castorama.fr/search?term=peinture+blanche+mate",
    "https://www.castorama.fr/outillage/outillage-electroportatif/perceuse-visseuse-perceuse-a-percussion-et-tournevis-sans-fil/cat_id_3796.cat",
    "https://www.castorama.fr/abri-de-jardin-bois/cat_id_0003373.cat",
    "https://www.castorama.fr/outillage/outillage-electroportatif/perceuse-visseuse-perceuse-a-percussion-et-tournevis-sans-fil/cat_id_3796.cat?page=2",
    "https://www.castorama.fr/outillage/outillage-electroportatif/perceuse-visseuse-perceuse-a-percussion-et-tournevis-sans-fil/cat_id_3796.cat?Marque=Bosch+Professional",
    "https://www.castorama.fr/outillage/outillage-electroportatif/perceuse-visseuse-perceuse-a-percussion-et-tournevis-sans-fil/cat_id_3796.cat?sort=-product.price",
    "https://www.castorama.fr/mkp/perceuse-visseuse-20v-nemura-2-batteries-1-5-ah-chargeur-rapide-malette-avec-54-accessoires/3666294006226_CAFR.prd",
    "https://www.castorama.fr/perceuse-a-percussion-sans-fil-bosch-universalimpact-18v-60-2x2ah/4053423231717_CAFR.prd",
    "https://www.castorama.fr/search.data?term=perceuse&page=1"
  ],
  "onPromotionOnly": false,
  "inStockOnly": false,
  "sortBy": "relevance",
  "fetchDetails": true,
  "maxItems": 20,
  "maxPages": 0,
  "proxy": {
    "useApifyProxy": true
  },
  "incrementalMode": false,
  "emitUnchanged": false,
  "emitExpired": false,
  "ignoreFieldsForChanges": [],
  "maxNotifyListings": 50
}
```

# Actor output Schema

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

No description

## `detail` (type: `string`):

No description

## `reviews` (type: `string`):

No description

## `changes` (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": [
        "perceuse",
        "peinture blanche mate",
        "https://www.castorama.fr/outillage/outillage-electroportatif/perceuse-visseuse-perceuse-a-percussion-et-tournevis-sans-fil/cat_id_3796.cat"
    ],
    "urls": [
        "https://www.castorama.fr/search?term=perceuse",
        "https://www.castorama.fr/search?term=zzxqv",
        "https://castorama.fr/search?term=peinture+blanche+mate",
        "https://www.castorama.fr/outillage/outillage-electroportatif/perceuse-visseuse-perceuse-a-percussion-et-tournevis-sans-fil/cat_id_3796.cat",
        "https://www.castorama.fr/abri-de-jardin-bois/cat_id_0003373.cat",
        "https://www.castorama.fr/outillage/outillage-electroportatif/perceuse-visseuse-perceuse-a-percussion-et-tournevis-sans-fil/cat_id_3796.cat?page=2",
        "https://www.castorama.fr/outillage/outillage-electroportatif/perceuse-visseuse-perceuse-a-percussion-et-tournevis-sans-fil/cat_id_3796.cat?Marque=Bosch+Professional",
        "https://www.castorama.fr/outillage/outillage-electroportatif/perceuse-visseuse-perceuse-a-percussion-et-tournevis-sans-fil/cat_id_3796.cat?sort=-product.price",
        "https://www.castorama.fr/mkp/perceuse-visseuse-20v-nemura-2-batteries-1-5-ah-chargeur-rapide-malette-avec-54-accessoires/3666294006226_CAFR.prd",
        "https://www.castorama.fr/perceuse-a-percussion-sans-fil-bosch-universalimpact-18v-60-2x2ah/4053423231717_CAFR.prd",
        "https://www.castorama.fr/search.data?term=perceuse&page=1"
    ],
    "proxy": {
        "useApifyProxy": true
    },
    "incrementalMode": false,
    "emitUnchanged": false,
    "emitExpired": false,
    "ignoreFieldsForChanges": []
};

// Run the Actor and wait for it to finish
const run = await client.actor("abotapi/castorama-fr-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": [
        "perceuse",
        "peinture blanche mate",
        "https://www.castorama.fr/outillage/outillage-electroportatif/perceuse-visseuse-perceuse-a-percussion-et-tournevis-sans-fil/cat_id_3796.cat",
    ],
    "urls": [
        "https://www.castorama.fr/search?term=perceuse",
        "https://www.castorama.fr/search?term=zzxqv",
        "https://castorama.fr/search?term=peinture+blanche+mate",
        "https://www.castorama.fr/outillage/outillage-electroportatif/perceuse-visseuse-perceuse-a-percussion-et-tournevis-sans-fil/cat_id_3796.cat",
        "https://www.castorama.fr/abri-de-jardin-bois/cat_id_0003373.cat",
        "https://www.castorama.fr/outillage/outillage-electroportatif/perceuse-visseuse-perceuse-a-percussion-et-tournevis-sans-fil/cat_id_3796.cat?page=2",
        "https://www.castorama.fr/outillage/outillage-electroportatif/perceuse-visseuse-perceuse-a-percussion-et-tournevis-sans-fil/cat_id_3796.cat?Marque=Bosch+Professional",
        "https://www.castorama.fr/outillage/outillage-electroportatif/perceuse-visseuse-perceuse-a-percussion-et-tournevis-sans-fil/cat_id_3796.cat?sort=-product.price",
        "https://www.castorama.fr/mkp/perceuse-visseuse-20v-nemura-2-batteries-1-5-ah-chargeur-rapide-malette-avec-54-accessoires/3666294006226_CAFR.prd",
        "https://www.castorama.fr/perceuse-a-percussion-sans-fil-bosch-universalimpact-18v-60-2x2ah/4053423231717_CAFR.prd",
        "https://www.castorama.fr/search.data?term=perceuse&page=1",
    ],
    "proxy": { "useApifyProxy": True },
    "incrementalMode": False,
    "emitUnchanged": False,
    "emitExpired": False,
    "ignoreFieldsForChanges": [],
}

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

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).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": [
    "perceuse",
    "peinture blanche mate",
    "https://www.castorama.fr/outillage/outillage-electroportatif/perceuse-visseuse-perceuse-a-percussion-et-tournevis-sans-fil/cat_id_3796.cat"
  ],
  "urls": [
    "https://www.castorama.fr/search?term=perceuse",
    "https://www.castorama.fr/search?term=zzxqv",
    "https://castorama.fr/search?term=peinture+blanche+mate",
    "https://www.castorama.fr/outillage/outillage-electroportatif/perceuse-visseuse-perceuse-a-percussion-et-tournevis-sans-fil/cat_id_3796.cat",
    "https://www.castorama.fr/abri-de-jardin-bois/cat_id_0003373.cat",
    "https://www.castorama.fr/outillage/outillage-electroportatif/perceuse-visseuse-perceuse-a-percussion-et-tournevis-sans-fil/cat_id_3796.cat?page=2",
    "https://www.castorama.fr/outillage/outillage-electroportatif/perceuse-visseuse-perceuse-a-percussion-et-tournevis-sans-fil/cat_id_3796.cat?Marque=Bosch+Professional",
    "https://www.castorama.fr/outillage/outillage-electroportatif/perceuse-visseuse-perceuse-a-percussion-et-tournevis-sans-fil/cat_id_3796.cat?sort=-product.price",
    "https://www.castorama.fr/mkp/perceuse-visseuse-20v-nemura-2-batteries-1-5-ah-chargeur-rapide-malette-avec-54-accessoires/3666294006226_CAFR.prd",
    "https://www.castorama.fr/perceuse-a-percussion-sans-fil-bosch-universalimpact-18v-60-2x2ah/4053423231717_CAFR.prd",
    "https://www.castorama.fr/search.data?term=perceuse&page=1"
  ],
  "proxy": {
    "useApifyProxy": true
  },
  "incrementalMode": false,
  "emitUnchanged": false,
  "emitExpired": false,
  "ignoreFieldsForChanges": []
}' |
apify call abotapi/castorama-fr-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,abotapi/castorama-fr-scraper"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/192zAConeZ4DcjneO/builds/eQ4eaAPxfcT29L0cP/openapi.json