# Idealista Scraper | Spain, Italy & Portugal Property Data (`webdata_labs/idealista-scraper`) Actor

\[$0.90 / 1K listings - no start fee] Scrape any Idealista search across Spain, Italy and Portugal: homes, rooms, garages, offices, premises, land, buildings, storage, for sale or rent. Price, m2, EUR/m2 vs market median, agency and price cuts per row, plus optional listing-page detail.

- **URL**: https://apify.com/webdata\_labs/idealista-scraper.md
- **Developed by:** [WebData Labs](https://apify.com/webdata_labs) (community)
- **Categories:** Real estate, Automation
- **Stats:** 3 total users, 2 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

Pay per event

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?

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

## Idealista Scraper - Spain, Italy & Portugal Property Data

**Any Idealista search, exported as structured rows: homes, rooms, garages, offices, commercial premises, land, whole buildings and storage, for sale or to rent, with €/m² scored against the market median on every row.**

Most Idealista exports give you a price and a title. This one gives you the search you actually ran, on whichever of the three sites you need, with the fields that let you rank the results without opening a single listing: €/m², how that compares with the median of everything the run collected, whether the asking price was cut, and who is advertising it. Turn on detail scraping and each row also carries what only the listing page knows, including the energy rating, the year the building went up, the bathroom count and the floor plan images.

No proxy setup, no API key, no login. Pick a location, pick a property type, press Start.

### ✅ What you get / ❌ what this isn't

| ✅ What you get | ❌ What this isn't |
|---|---|
| **Eight property types**, each with its URL grammar verified against a live page | Not a homes-only scraper with the other types guessed and quietly returning nothing |
| **Three countries with three different grammars** for pagination, sorting and filters | Not a Spanish scraper with `.it` and `.pt` bolted on and capped at page one |
| **€/m² per listing plus the median of your search** and a `% vs median` gap | Not a raw price column that leaves you to work out whether 420,000 € is good for that street |
| **Price cuts as real fields** on every row, at no extra cost, because Idealista renders them into the card | Not a "run it twice a week apart and diff the files" export |
| **Optional listing-page detail**: energy rating, year built, bathrooms, heating, floor plans | Not a search-card dump that calls itself a property database |
| **No proxy or anti-bot setup**, and no start fee | Not a scraper that hands you a proxy field and blames your proxies when it returns nothing |

### 🗺️ What is covered

Property type coverage differs per site, because Idealista does not run the same sections in every country. Every combination below was checked against a live Idealista page, and any combination not listed is refused with a message naming what that site does support, rather than returning an empty run.

**Spain (idealista.com)**

- Homes and flats, for sale and to rent
- Rooms in shared flats, to rent
- Garages and parking, for sale and to rent
- Offices, for sale and to rent
- Commercial premises, for sale and to rent
- Land and plots, for sale
- Whole buildings, for sale
- Storage rooms, for sale and to rent

**Italy (idealista.it)**

- Homes and flats, for sale and to rent
- Rooms in shared flats, to rent
- Garages and parking, for sale and to rent
- Offices, for sale and to rent
- Commercial premises, for sale
- Land and plots, for sale
- Whole buildings, for sale

**Portugal (idealista.pt)**

- Homes and flats, for sale and to rent

### 🔎 Why use this Actor

- **The type slugs are verified, not guessed.** Idealista localises every path segment, and a wrong one is answered with a page rather than an error, so a guessed slug can silently return the wrong thing. Of twelve Italian candidates tested, four were wrong: commercial premises are `vendita-negozi` and not the Spanish-shaped `vendita-locali`, and whole buildings are `vendita-edifici` and not `vendita-palazzi`. Both wrong guesses return a page. Only what was proved on a live page ships here.
- **€/m² is scored, not just printed.** Every row carries `pricePerSqm`, the `medianPricePerSqm` of everything the run collected, and `pctVsMedianPricePerSqm`, so "cheap" and "cheap for this street" stay separate questions. `isBelowMarket` is the one-column answer.
- **Price cuts come free.** Idealista renders the previous price and reduction badge server-side onto reduced cards, so `previousPrice`, `priceDropAmount` and `priceDropPercent` are on every row without a second run or a diff. The percentage is recomputed from the two prices rather than copied from Idealista's badge, which rounds to a whole number.
- **Detail scraping is opt-in and priced separately.** A search page yields about 30 listings for one page fetch; a listing page yields one. Folding that into a single per-row price would make every buyer pay for depth they did not ask for, so it is a separate switch and a separate charge.
- **Multiple locations in one run.** Give a list of location slugs and each is scraped as its own search into one dataset, with a shared market median.
- **No start fee.** Several Idealista Actors add a per-run charge on top of the per-result price. This one does not, so short and scheduled runs stay cheap.

### 👥 Who it's for

Property investors, buyer's agents, relocation consultants, PropTech and valuation teams who need a market rather than a listing.

- Pull an entire city's stock for a type and rank it by €/m² against its own median.
- Screen commercial premises or whole buildings, which most Idealista scrapers do not cover at all.
- Build rental-yield comparisons by running sale and rent for the same location and joining on district.
- Feed asking prices and areas into a valuation model or CMA without hand-collecting comparables.
- Track a district over time by scheduling the same search weekly.

### Example tasks

Ready-made searches you can open, copy the input from, and adapt. Each is a saved
configuration of this Actor, so the fastest way to start is usually to take the closest one
and change the location.

- [Scrape Idealista property listings in Spain](https://apify.com/webdata_labs/idealista-scraper/examples/scrape-idealista-property-listings-in-spain) - the general case: a whole Spanish city's homes for sale.
- [Scrape Idealista apartments for rent in Barcelona](https://apify.com/webdata_labs/idealista-scraper/examples/scrape-idealista-apartments-for-rent-in-barcelona) - the rental side of the same market, with the private-owner filter.
- [Scrape Idealista commercial premises in Italy](https://apify.com/webdata_labs/idealista-scraper/examples/scrape-idealista-commercial-premises-in-italy) - retail and commercial units on the Italian site.
- [Scrape Idealista garages and parking spaces](https://apify.com/webdata_labs/idealista-scraper/examples/scrape-idealista-garages-and-parking-spaces) - cheapest first, a type most Idealista scrapers do not cover.
- [Scrape Idealista land and plots for sale](https://apify.com/webdata_labs/idealista-scraper/examples/scrape-idealista-land-and-plots-for-sale) - development sites and building plots.
- [Scrape whole buildings for sale on Idealista](https://apify.com/webdata_labs/idealista-scraper/examples/scrape-idealista-buildings-for-sale-in-spain) - block purchases and portfolio sourcing.
- [Scrape Idealista rooms for rent in Madrid](https://apify.com/webdata_labs/idealista-scraper/examples/scrape-idealista-rooms-for-rent-in-madrid) - rooms in shared flats, for student housing research.
- [Get Idealista listings with energy rating and floor plans](https://apify.com/webdata_labs/idealista-scraper/examples/idealista-listings-with-energy-rating-and-floor-plans) - detail scraping on, for the deep per-listing record.
- [Find Idealista properties priced below the local market](https://apify.com/webdata_labs/idealista-scraper/examples/find-idealista-properties-below-market-price) - sorted by EUR/m2, then scored against the median of the results.
- [Estrarre case in vendita da idealista a Roma](https://apify.com/webdata_labs/idealista-scraper/examples/scrape-idealista-case-in-vendita-a-roma) - the Italian site, in Italian.

### ⚙️ How to run it

1. Pick the **Country**, then **Sale or rent**, then the **Property type**.
2. Put one or more **Locations** in, using the slug Idealista uses in its own URL: `madrid-madrid`, `barcelona-barcelona`, `roma-roma`, `milano-milano`, `lisboa-lisboa`. Open the search on Idealista and copy the part after the operation segment.
3. Optionally turn on **Also open each listing page** for the deeper fields.
4. Set **Maximum listings** (100 by default, 0 for no limit) and press **Start**.
5. Open the **Listings** view on the run's Output tab, or export to CSV, Excel or JSON.

Prefer to work from the site itself? Set up the search on Idealista with whatever filters you like, copy the URL from the address bar, and paste it into **Idealista search URLs**. That path always matches what you see in the browser, and it overrides the structured fields.

### 📥 Input examples

**A whole city, homes for sale**

```json
{
  "country": "es",
  "operation": "sale",
  "propertyType": "homes",
  "locations": ["madrid-madrid"],
  "maxItems": 500
}
```

**Two cities at once, commercial premises in Italy**

```json
{
  "country": "it",
  "operation": "sale",
  "propertyType": "premises",
  "locations": ["roma-roma", "milano-milano"],
  "maxItems": 200
}
```

**Deep records with energy rating and floor plans**

```json
{
  "country": "es",
  "operation": "sale",
  "propertyType": "homes",
  "locations": ["barcelona-barcelona"],
  "includeDetails": true,
  "maxItems": 50
}
```

**Garages for sale, cheapest first**

```json
{
  "country": "es",
  "operation": "sale",
  "propertyType": "garages",
  "locations": ["madrid-madrid"],
  "sortBy": "cheapest",
  "maxPrice": 30000
}
```

**Rooms to rent, private owners only**

```json
{
  "country": "es",
  "operation": "rent",
  "propertyType": "rooms",
  "locations": ["valencia-valencia"],
  "onlyPrivateOwners": true
}
```

**Only listings whose price was cut**

```json
{
  "country": "es",
  "operation": "sale",
  "propertyType": "homes",
  "locations": ["malaga-malaga"],
  "sortBy": "priceDrop",
  "onlyPriceDrops": true,
  "minPriceDropPercent": 5
}
```

**Large family homes, filtered at the source**

```json
{
  "country": "es",
  "operation": "sale",
  "propertyType": "homes",
  "locations": ["sevilla-sevilla"],
  "minArea": 120,
  "minRooms": 4
}
```

**Portuguese rentals**

```json
{
  "country": "pt",
  "operation": "rent",
  "propertyType": "homes",
  "locations": ["lisboa-lisboa"],
  "maxPrice": 2500
}
```

**Straight from a search URL you already have**

```json
{
  "startUrls": [
    "https://www.idealista.com/venta-viviendas/madrid-madrid/con-precio-hasta_400000/"
  ],
  "maxItems": 300
}
```

**Whole buildings, for portfolio sourcing**

```json
{
  "country": "es",
  "operation": "sale",
  "propertyType": "buildings",
  "locations": ["madrid-madrid", "barcelona-barcelona"]
}
```

### 📤 Output

One row per unique listing. The search-card fields are on every row; the detail fields only when **Also open each listing page** is on.

#### From the search card, always present

| Field | Description |
|---|---|
| `id` | Idealista's own listing id |
| `url` | Listing page URL |
| `title` | Listing headline as Idealista writes it |
| `price` | Current asking price |
| `currency` | Always EUR on these three sites |
| `hasPriceDrop` | Whether Idealista marks this listing as reduced |
| `previousPrice` | The price before the cut |
| `priceDropAmount` | How much was cut |
| `priceDropPercent` | The cut as a percentage, recomputed from both prices |
| `pricePerSqm` | Price divided by area |
| `medianPricePerSqm` | Median €/m² of everything the run scanned |
| `pctVsMedianPricePerSqm` | How far this listing sits from that median |
| `isBelowMarket` | Whether €/m² is under the median |
| `propertyType` | The type searched for |
| `operation` | `sale` or `rent` |
| `country` | `es`, `it` or `pt` |
| `street`, `district`, `city`, `locationText` | Location parsed out of the title |
| `rooms` | Bedrooms as shown on the card |
| `areaSqm` | Floor area as shown on the card |
| `floor`, `isExterior`, `hasLift`, `hasGarage` | Card feature chips |
| `isProfessionalAd` | True for agency stock, false for private owners |
| `agencyName`, `agencyUrl` | The advertising agency |
| `description` | Short description from the card |
| `thumbnailUrl`, `photoCount` | Card media |
| `searchUrl`, `scrapedAt` | Provenance |

#### From the listing page, when detail scraping is on

| Field | Description |
|---|---|
| `detailScraped` | Whether the listing page was fetched and parsed |
| `detailTitle`, `detailLocation` | Title and neighbourhood as the page states them |
| `detailPrice`, `detailPricePerSqm` | Price and €/m² as the page states them |
| `fullDescription` | The complete advertiser description, not the card excerpt |
| `builtAreaSqm` | Built area from the features block |
| `detailRooms`, `bathrooms` | Bedroom and bathroom counts |
| `builtYear` | Year of construction |
| `condition` | For example second hand, good condition, or new build |
| `orientation` | Which way the property faces |
| `heating` | Heating type, or that there is none |
| `detailFloor`, `detailHasLift`, `detailIsExterior`, `detailHasGarage` | Building features |
| `energyConsumption`, `energyConsumptionRating` | kWh/m² per year and its A to G letter |
| `energyEmissions`, `energyEmissionsRating` | kg CO2/m² per year and its A to G letter |
| `features` | Every feature line, grouped under Idealista's own headings, in the site's language |
| `photoUrls`, `photoCount` | Full-size photo URLs and the count Idealista displays |
| `floorPlanUrls`, `floorPlanCount`, `hasFloorPlan` | Floor plan images |
| `advertiserName`, `reference` | Advertiser and their own internal reference |
| `locationBreadcrumb` | Street, neighbourhood, district, city, province |
| `listingUpdatedText` | When Idealista says the ad was last updated |
| `latitude`, `longitude` | Exact position, when the advertiser published one. See the caveats. |

### 💵 How much does it cost?

Two charges, and you only ever pay the second one if you ask for it.

| Event | Price (Free plan) | Down to (Diamond) |
|---|---|---|
| Listing scraped | $0.0009 each, so **$0.90 per 1,000** | $0.0005 |
| Listing page opened | $0.015 each, so **$15 per 1,000** | $0.008 |

There is **no actor start fee**. A run that returns nothing costs nothing.

The gap between the two prices is the real cost difference, not a markup: one page fetch returns about 30 listings from a search page, and exactly one from a listing page. If you do not need the energy rating and the floor plans, leave detail scraping off and pay the row price only.

### 🔁 Run it on the Apify platform

Schedule it, call it over the API, or fire it from a webhook. Save a configuration as a Task to re-run the same search without retyping it, which is the usual way to track a district week to week.

### 🤖 Use with AI agents via MCP

This Actor is available over Apify's MCP server, so an agent can run it as a tool.

**Claude Code**

```bash
claude mcp add apify --transport http https://mcp.apify.com/?actors=webdata_labs/idealista-scraper
```

**Cursor or Claude Desktop**, in your MCP settings:

```json
{
  "mcpServers": {
    "apify": {
      "url": "https://mcp.apify.com/?actors=webdata_labs/idealista-scraper"
    }
  }
}
```

An agent can fill `locations: ["madrid-madrid"]` and `propertyType: "homes"` directly. It cannot reliably construct a valid Idealista URL from scratch, which is why the structured fields exist alongside the URL input.

### 🔗 Use this Actor in n8n

Use the Apify node, pick this Actor, and map the input fields. The dataset comes back as items you can pass straight into a spreadsheet, a database or an LLM node. A common shape is a weekly schedule trigger, this Actor, then a filter on `isBelowMarket` and a notification.

### ⚠️ Limits and caveats

Written plainly, because most of these look like bugs if nobody tells you.

- **Portugal covers homes only.** The Portuguese type slugs for garages, offices and the rest are not verified yet, and shipping an unverified slug would give you an empty run that reads as a broken Actor. Spanish and Italian coverage is listed above in full.
- **New developments are not a supported type on any site.** `obra-nueva` returns a 404 on the Spanish site and the Italian equivalents return nothing, so Idealista appears to route new builds somewhere this Actor does not yet reach. Rather than ship a slug that errors, it is left out.
- **Exact coordinates are usually empty.** Idealista publishes a listing's position only when the advertiser chooses to, and blurs it otherwise. Across the listings measured while building this, `latitude` and `longitude` were empty on all of them. The fields are populated when the data is there, and are not a promise that it usually is.
- **Non-home types carry fewer card fields.** A garage or a plot of land has no bedrooms and often no stated area, so `rooms`, `areaSqm` and therefore `pricePerSqm` come back empty on those rows. That is Idealista's card, not a parsing failure. Turn on detail scraping if you need more from those types.
- **There is no price history.** The listing page carries no history widget, so the only reduction data available anywhere on Idealista is the previous price on the search card, which this Actor already returns. Any Actor promising a full price timeline is reconstructing it from its own past runs, not reading it from Idealista.
- **Portugal has no sort ordering.** Every sort value returns a byte-identical page there, so `sortBy` is ignored on `.pt` and the run says so in the log rather than pretending it applied.
- **Italy has no rental listings for commercial premises**, and land, buildings and storage are sale only everywhere. Asking for an unsupported combination returns a clear error naming what that site does support.
- **The median settles after the first page.** `medianPricePerSqm` on a row is the median known when that row was written, because rows are written page by page rather than held to the end of the run. The final value is in `RUN_SUMMARY`. Holding everything to the end would mean an aborted run returned nothing at all.
- **Very narrow searches stop early on purpose.** If a search is reading many pages and matching almost nothing, the run stops and says so instead of scanning a whole city for a handful of hits. Broaden the location or loosen the filters to go deeper.

### 🧩 Related Actors

A property workflow usually needs more than one source. These fit together:

- [Idealista Price Drop Scraper](https://apify.com/webdata_labs/idealista-price-drop-scraper) - the same three countries, built around the price cut: reduction-first ordering, minimum drop filters and a form shaped for finding motivated sellers.
- [Redfin Property Scraper](https://apify.com/webdata_labs/redfin-property-scraper) - US listings, when your market is on the other side of the Atlantic.
- [Zillow Property Detail Scraper](https://apify.com/webdata_labs/zillow-property-detail-scraper) - deep US property records.
- [Zillow Agent Scraper](https://apify.com/webdata_labs/zillow-agent-scraper) - the agents behind the listings.
- [Spain BOE Subastas API](https://apify.com/webdata_labs/spain-boe-subastas-api) - Spanish judicial property auctions, the distressed end of the same market.
- [France Notaires Property API](https://apify.com/webdata_labs/france-notaires-property-api) - actual recorded French sale prices, for a market where asking prices are not the whole story.
- [Website Contact Extractor](https://apify.com/webdata_labs/website-contact-extractor) - turn the agency URLs on these rows into contact details.

### ❓ FAQ

#### Do I need an Idealista account or API key?

No. This Actor reads public search pages. There is nothing to sign up for and no credentials to enter.

#### Do I need to configure proxies?

No. Proxying and anti-bot handling are our problem, not yours, and are included in the price. There is no proxy field to get wrong.

#### What is a location slug and where do I find it?

It is the part of an Idealista URL after the operation segment. In `idealista.com/venta-viviendas/madrid-madrid/`, the slug is `madrid-madrid`. Open the search you want on the site and copy that part. If in doubt, paste the whole URL into **Idealista search URLs** instead.

#### Why did my run return fewer listings than Idealista claims?

Idealista's result count is for the whole search; the run stops at your **Maximum listings**, and stops early if a search is matching very little per page. Set `maxItems` to 0 to remove the cap.

#### Can I get the phone number of the advertiser?

No. Idealista puts the phone number behind an interaction and this Actor does not attempt it. You get the agency name, the agency profile URL and their internal reference, which is enough to find them.

#### Does it work for new build developments?

Not yet. See the caveats above: Idealista does not serve new builds under the path shapes tested, and rather than ship a guess this Actor leaves the type out.

#### How many listings can I get from one search?

As many as Idealista will paginate, which is thousands for a large city. Set `maxItems` to 0 for no limit. Long runs re-open their session automatically as needed.

#### Is the €/m² median the real market median?

It is the median of the listings this run collected, which is the right comparison for ranking one search against itself. It is not an official market index, and a run limited to 20 listings has a median made of 20 listings.

#### Can I run sale and rent together?

Not in a single run, because they are different searches. Run them separately and join the datasets on `district` or `city`, which is the usual way to compute a yield.

### ⚖️ Is it legal to scrape Idealista?

Scraping publicly available data is broadly lawful in the EU and the US, and this Actor only reads pages any visitor can open, with no login and no personal accounts involved. What you do with the data is a separate question: listing text and photographs are the advertiser's copyright, and if a row identifies a private individual then GDPR applies to your use of it. Use the data for market analysis, keep republication of photos and description text out of it, and take your own advice for anything commercial. Nothing here is legal advice.

### 📝 Changelog

#### 2026-08-24 - 0.1

First release. Eight property types across Spain and Italy, homes in Portugal, each type slug verified against a live page. Optional listing-page detail scraping with energy rating, year built, bathrooms, features, photos and floor plans. €/m² market scoring and price-cut fields on every row.

### 🛠️ Support

Open an issue on the Actor's Issues tab. Bugs get looked at quickly, and a clear description of the search you ran is usually enough to reproduce.

### ⭐ Rate this Actor

If it saved you an afternoon, a rating helps other people find it.

# Actor input Schema

## `startUrls` (type: `array`):

Paste any Idealista search page URL, with whatever filters you already set on the site. This is the most reliable way to get exactly the search you see in your browser. When given, these replace the country, location and property type fields below.

## `country` (type: `string`):

Which Idealista site to search: Spain (idealista.com), Italy (idealista.it) or Portugal (idealista.pt). Property type coverage differs per site, see the README.

## `locations` (type: `array`):

One or more location slugs exactly as they appear in an Idealista URL, for example 'madrid-madrid', 'barcelona-barcelona' or 'valencia-valencia'. Open the search you want on Idealista and copy the part after the operation, e.g. idealista.com/venta-viviendas/madrid-madrid/. Each location is scraped as its own search.

## `operation` (type: `string`):

Whether to search properties for sale or to rent. Some property types exist for only one of the two: rooms are rent only, land and buildings are sale only.

## `propertyType` (type: `string`):

What kind of property to search. Spain covers all eight types. Italy covers homes, rooms, garages, offices, commercial premises, land and buildings. Portugal currently covers homes only.

## `includeDetails` (type: `boolean`):

Adds the fields that only exist on the listing page itself: energy rating, year built, bathrooms, heating, orientation, the full advertiser description, photo and floor plan URLs. This opens one extra page per listing, so a run takes longer and each enriched listing is charged separately. Off by default.

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

Stop after this many matching listings across all searches. Set 0 for no limit. The default keeps a first run small and cheap.

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

Idealista's own result ordering. Spain and Italy only: the Portuguese site exposes no sorting, so PT runs come back in Idealista's default order.

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

Highest price to include, applied by Idealista itself as a search filter. There is no matching minimum-price filter on the Spanish or Italian sites, so use a search URL if you need a lower bound.

## `minArea` (type: `integer`):

Smallest floor area to include, applied by Idealista itself as a search filter.

## `maxArea` (type: `integer`):

Largest floor area to include, applied by Idealista itself as a search filter.

## `minRooms` (type: `integer`):

Keep only listings with at least this many bedrooms. Applied to the scraped rows, not to the Idealista search.

## `onlyPrivateOwners` (type: `boolean`):

Keep only listings posted by private owners, dropping everything marketed by an agency.

## `onlyPriceDrops` (type: `boolean`):

Keep only listings Idealista marks as reduced. Every row carries the price-drop fields either way; this just filters to them.

## `minPriceDropPercent` (type: `integer`):

Keep only listings reduced by at least this percentage. Leave empty for any reduction.

## `includeDescription` (type: `boolean`):

Include the short description text from each search card. Turn off for a narrower export.

## Actor input object example

```json
{
  "startUrls": [],
  "country": "es",
  "locations": [
    "madrid-madrid"
  ],
  "operation": "sale",
  "propertyType": "homes",
  "includeDetails": false,
  "maxItems": 100,
  "sortBy": "relevance",
  "onlyPrivateOwners": false,
  "onlyPriceDrops": false,
  "includeDescription": true
}
```

# Actor output Schema

## `listings` (type: `string`):

No description

## `details` (type: `string`):

No description

## `marketValue` (type: `string`):

No description

## `priceDrops` (type: `string`):

No description

## `sellers` (type: `string`):

No description

## `runSummary` (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 = {
    "startUrls": [],
    "country": "es",
    "locations": [
        "madrid-madrid"
    ],
    "operation": "sale",
    "propertyType": "homes",
    "maxItems": 100,
    "sortBy": "relevance"
};

// Run the Actor and wait for it to finish
const run = await client.actor("webdata_labs/idealista-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 = {
    "startUrls": [],
    "country": "es",
    "locations": ["madrid-madrid"],
    "operation": "sale",
    "propertyType": "homes",
    "maxItems": 100,
    "sortBy": "relevance",
}

# Run the Actor and wait for it to finish
run = client.actor("webdata_labs/idealista-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 '{
  "startUrls": [],
  "country": "es",
  "locations": [
    "madrid-madrid"
  ],
  "operation": "sale",
  "propertyType": "homes",
  "maxItems": 100,
  "sortBy": "relevance"
}' |
apify call webdata_labs/idealista-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,webdata_labs/idealista-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/nVK9U095ORfbkGufJ/builds/rDikIAkzNJTXLBUUf/openapi.json