# Idealista Scraper💰$0.65+/1K Spain Italy Portugal France Emails (`memo23/idealista-scraper`) Actor

From $0.65/1K 💰 Idealista for Spain, Italy, Portugal & France. Paste any search URL, or scrape a whole country in one run — 52 ES / 107 IT / 28 PT / 100 FR provinces. Deduped by property code, so overlapping searches never bill you twice. 80+ fields, agent phones & emails, GPS.

- **URL**: https://apify.com/memo23/idealista-scraper.md
- **Developed by:** [Muhamed Didovic](https://apify.com/memo23) (community)
- **Categories:** Real estate, Lead generation, MCP servers
- **Features:** Limited permissions
- **Stats:** 1,028 total users, 212 monthly users, 99.9% runs succeeded, 30 bookmarks
- **User rating**: 5.00 out of 5 stars

## Pricing

from $0.65 / 1,000 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

## Idealista Scraper — Spain · Italy · Portugal · complete result sets

![How Idealista Scraper works](https://raw.githubusercontent.com/muhamed-didovic/muhamed-didovic.github.io/main/assets/how-it-works-idealista.png)

> ✅ **Verified benchmark — 1,967 properties scraped from a single Madrid rentals search** (search reports 1,968 total; Idealista's per-query API caps at 1,500). This actor captures the full result set past Idealista's cap, returning **+31% more rows than any competitor** that stops at the limit.

Scrape every property listing from **Idealista.com** (Spain), **Idealista.it** (Italy), and **Idealista.pt** (Portugal) — including agent contacts, GPS coords, multilingual descriptions, multimedia, new developments, and floor plans. Flat one-row-per-property output with **80+ fields** including the full `basicInfo` / `moreCharacteristics` / `contactInfo` / `multimedia` / `ubication` blocks. **$1 per 1,000 results.**

### 🧠 NEW: AI Market Intelligence — listings → an investment read on every area

Flip on **`marketAnalysis`** and the scraper doesn't just return listings — it returns a **market read on every area it scrapes**, across Spain, Italy and Portugal. After the crawl, one AI pass per area (backed by live web research) computes rental economics, short-let potential, demand drivers and risks from that run's own listings:

> *Málaga, real run →* median asking **€850,000** · avg local rent **€1,200/mo** · short-let **ADR €155 · 68% occupancy · ~€3,150/mo est. revenue** · gross yield **1.69%** · demand: *tech-hub expansion (Google, Vodafone, TDK), digital-nomad visa migration, 10M+ airport passengers* · risks: *new saturation rules blocking STR registrations in 43 districts, 15–20% YoY rent inflation, centro histórico stock lost to tourist lets*.

One `marketAnalysis` row per area **with cited sources** (`demandSignals`, `risks`, `shortLet.adr` / `occupancyPct` / `revpar` / `estMonthlyRevenue`, `grossYieldPct`, `sources`, `summary`). Paid plans only, **$0.15 per area analyzed**, up to 8 areas per run. Areas with fewer than 3 scraped listings are skipped and never billed. Results are cached for 90 days, so a repeat lookup of the same area comes back instantly.

### The Idealista requests we get most — and the input that answers each

- **🏙️ "I just want to type a city name"** → set **`location`**, e.g. `"Marbella"`, `"Chamberí"` or `"Marbella, Málaga"`. It is resolved against Idealista's own place index before the search starts, so no internal Location ID lookup. Districts and neighbourhoods work too, and several names at once go in **`locations`**. A name that cannot be matched stops the run and tells you what Idealista suggested instead — you never get the wrong city back silently.
- **🔢 Search by postal code (Buscar por código postal)** → set **`postalCodes`**, e.g. `["28013","08013"]`. Each code runs as its own Idealista search and all results merge into one dataset — no Location ID lookup needed. Works on Spain, Italy and Portugal.
- **📍 Radius search around a point** → set **`center`** (`"lat,lng"`) plus **`distanceKm`** to pull every listing within that radius, e.g. everything within 5 km of Madrid's centre (`"40.4168,-3.7038"` + `5`).
- **🔗 Just paste a search URL** → put any Idealista search, filtered-search, single-property or new-development URL straight into **`startUrls`** (`.com` / `.it` / `.pt`). No URL reverse-engineering.
- **📊 "It's not returning all results"** → **`splitByPrice`** (on by default) captures the full result set past Idealista's hidden **1,500-per-query cap** — **+31% more rows** than scrapers that stop at the limit.
- **♻️ "I keep getting duplicate rows"** → every row is de-duplicated by property code within a run, and **`monitoringMode`** emits only listings that are new since your previous run — so scheduled/daily runs never re-deliver or re-charge the same property.

Every item above is a single input you can set today — full details in [Form search](#form-search-no-url-needed) and [Supported inputs](#supported-inputs).

### Why use this scraper

- **🎯 Complete result sets** — every other scraper on Apify Store silently truncates a large search at 1,500 rows. This one returns the whole set, about 31% more rows, and a search under 1,500 hits runs exactly as before.
- **🌍 3 countries in one actor** — Spain, Italy, and Portugal handled by the same code path. No separate scraper needed per country.
- **📦 80+ fields per property** — full `basicInfo`, `moreCharacteristics`, `contactInfo`, `multimedia` (with all images + videos), `ubication` (GPS coords + neighborhood + admin hierarchy), `translatedTexts` (multi-language descriptions), `promotion` (new development info), `labels`, `energyCertification`.
- **🏢 Agency mode (with phone numbers)** — flip `scrapeAgencies: true` to get one row per real-estate **agency** (name, **phone**, profile URL, microsite, logo) for any search area, deduplicated across all pages. The phone is on every row — competing agency scrapers leave it blank. See [Agency mode](#agency-mode-agencies-with-phone-numbers).
- **🔄 Monitoring mode** — only emit new listings vs. previous runs. Build historical archives without paying for re-scraping the same property.
- **📉 Price-change tracking** — add `detectPriceChanges: true` (with monitoring on) to get a row every time a tracked listing's price moves: `oldPrice → newPrice`, delta, %, direction, and how long it's been listed. Perfect for catching price drops. Rows land in a separate `idealista-changes-<runId>` dataset, billed at the low monitoring rate.
- **🗑️ Removed / sold detection** — add `detectRemovedListings: true` (with monitoring on) to get a row for every listing that has **left the market** since your last run. Rows land in a separate `idealista-removed-<runId>` dataset. Full-scan runs only — partial runs are skipped so nothing is wrongly flagged.
- **🛰️ Index / delta mode** — `indexMode: true` for the cheapest possible "keep my database fresh" loop: the actor scans your searches and emits ONLY slim event rows (`new` / `price_changed` / `removed` with propertyCode, price, URL) to the default dataset — no property details fetched, nothing charged for unchanged listings beyond a $0.10-per-1,000 scan fee. Built for customers who already store the full data and just need the diff.
- **🏢 4 URL types** in one pipeline — search results, individual property URLs, new development URLs, custom-filter URLs.
- **💰 $1 per 1,000 results** — among the cheapest premium scrapers on Apify Store. No login or API key needed.

### Overview

Idealista is the dominant real-estate portal across Iberia (Spain) and increasingly in Italy + Portugal. This actor extracts the full property data Idealista publishes — richer than what the page shows, including full GPS coordinates, energy certifications, multi-language auto-translated descriptions, and complete agent contact info (phone + email + agency logo + microsite slug).

Every dataset row represents one property listing. The actor supports four input modes (search URLs, individual property URLs, new-development URLs, filtered searches) and emits the same row shape regardless of input.

### Supported inputs

| Input type | Example URL | Behavior |
|---|---|---|
| **Search by location** | `https://www.idealista.com/venta-viviendas/madrid/` | Walks all paginated results, complete set |
| **Filtered search** | `https://www.idealista.com/en/geo/venta-obranueva/andalucia/con-2-dormitorios,3-dormitorios/?ordenado-por=precios-asc` | Same behavior; respects every filter in the URL |
| **Individual property** | `https://www.idealista.com/inmueble/109366429/` | One row, full schema |
| **New development** | `https://www.idealista.com/obra-nueva/109366429/` | One row, schema includes `promotion` block |
| **Italian listings** | `https://www.idealista.it/vendita-case/milano/` | Same fields, Italian metadata |
| **Portuguese listings** | `https://www.idealista.pt/comprar-casas/lisboa/` | Same fields, Portuguese metadata |
| **Form search (no URL)** | `country` + `operation` + `propertyType` + `location` + filters | Pick filters instead of building a URL — see below |
| **City / area name** | `location: "Marbella"` or `locations: ["Marbella","Estepona"]` | Resolved to Idealista's own area id — city, district or neighbourhood |
| **Postal-code search** | `postalCodes: ["28013","08013"]` | One Idealista search per code, merged into one dataset — no URL or Location ID |
| **Radius search** | `center: "40.4168,-3.7038"` + `distanceKm: 5` | Every listing within N km of the point |
| **Specific listings** | `propertyIds: ["111287956","107412377"]` | Re-fetch a known set of listings inside a search |
| **Business transfers** | `https://www.idealista.com/traspasos/madrid-madrid/` or `propertyType: "transfers"` | Traspasos — bars, restaurants and shops sold as a going concern, with `transferCost` |
| **Whole buildings** | `https://www.idealista.com/venta-edificios/madrid-madrid/` or `propertyType: "buildings"` | Edificios — entire blocks rather than single units |
| **Holiday rentals** | `https://www.idealista.com/alquiler-vacacional/marbella-malaga/` or `propertyType: "vacationRentals"` | Alquiler vacacional — price per night, `maxGuestsAllowed`, `vacationRentalInfo` |

> ⚠️ Only Idealista's own domains are supported: `idealista.com`, `idealista.it`, `idealista.pt`. External recruiter / aggregator URLs are rejected by the input classifier.

#### Form search (no URL needed)

Don't want to hand-build an Idealista URL? Leave **Start URLs** empty and fill in the **🔎 Form Search** fields instead. Set the market (`country`), `operation` (sale/rent), `propertyType`, and name the area in `location`, then narrow with price, size, bedrooms, bathrooms, condition, home type, publication window and amenity toggles (pool, lift, garage, garden, terrace, storage, fitted wardrobes, luxury, balcony, accessible, virtual tour, bank repossessions, sea views, furnished, …).

```json
{
  "country": "es",
  "operation": "sale",
  "propertyType": "homes",
  "location": "Marbella",
  "maxPrice": 250000,
  "bedrooms": "1,2",
  "homeType": ["flat", "penthouse"],
  "swimmingPool": true,
  "publicationDate": "W",
  "sortBy": "price",
  "sortDirection": "asc",
  "maxItems": 500
}
```

`location` accepts a city, a district or a neighbourhood, written the way Idealista writes it — `"Marbella"`, `"Chamberí"`, or `"Marbella, Málaga"` when a name exists in several provinces. It is matched against Idealista's own place index, so `"Salamanca"` returns the city in Castilla y León rather than Madrid's Barrio de Salamanca. Pass several areas in `locations` and each becomes its own search.

If you already know Idealista's internal area identifier you can still pass it directly as `locationId` (e.g. `0-EU-ES-28-07-001-079` = Madrid); `location` simply looks one up for you.

**Sorting** — `sortBy` takes `price`, `publicationDate`, `modificationDate`, `size`, `ratioeurm2` (price per m²), `rooms`, `floor`, `priceDown`, `weigh` (Idealista's relevance) or `distance` (nearest first), with `sortDirection` `asc` / `desc`. Start URLs carry their own ordering and win over this. `distance` needs a `center` point and a radius; on a city or postal-code search Idealista accepts it and orders by relevance instead, and its direction is always ascending so that "nearest first" means what it says.

It sets the order Idealista serves each search in, which is what decides *which* listings you get when you cap a large search with `maxItems` — for example the newest 200 rather than an arbitrary 200. The rows in the dataset are not themselves guaranteed to come out in that order: large searches are split into parallel price buckets (`splitByPrice`, on by default) and details are fetched concurrently, so rows land in completion order. Sort the dataset on your side if you need it ordered.

**Occupancy status** — `currentOccupationType` separates stock that is free to move into from stock that is already let: `free`, `tenanted` (sold with tenants in place), `bareOwnership`, `illegallyOccupied`. Investors buying yield use `tenanted`; owner-occupiers use `free`.

**Also available**: `floorHeights` (`topFloor` / `intermediateFloor` / `groundFloor`), `subTypology` (`villaType` / `apartamentoType` / `loftType` / `casaBajaType` / `atticStudioType` / `cortijoType`, the middle two on sale searches only; cortijos are Andalusian farmhouses — 437 in Málaga, 457 in Granada), `energyEfficiency` (`high` / `medium` / `low`), `exteriorDomesticSpace` (Idealista's combined balcony-or-terrace flag), `hasPlan`, `onlyFlats`, `petsAllowed` (rentals), `auction` (`onlyAuctions` / `excludeAuctions`) and `agency` — the microsite slug from an agency's Idealista URL, which narrows a search to that one agency.

**Published within** — `publicationDate` takes `T` (24 h), `Y` (48 h), `W` (week) or `M` (month). Idealista offers a different shortest window per search type (48 h on sale, 24 h on rent, neither on new developments), so the closest available window is used and the run log says so. Business transfers follow the rental set (24 h, week, month) even though they are a sale vertical.

##### Scrape whole agencies (`agencies`)

Pass one or more agency slugs — the part after `/pro/` in the agency's own URL, so `idealista.com/pro/savills-madrid/` is `savills-madrid`. A full `/pro/` URL works too; the slug is read out of it.

```json
{ "country": "es", "agencies": ["savills-madrid", "walterhauschamberi"], "maxItems": 500 }
```

An agency search needs no location of its own, so that input is a complete run. Add a location and every agency is searched inside it instead. A slug Idealista does not recognise stops that one search with a message naming it, rather than quietly returning the whole market.

##### Send the listings somewhere (`notifyWebhookUrl`, Telegram, Slack, Discord)

A dataset is a place you have to go and check. A message arrives. Point the run at a channel you already watch and each batch of listings is sent there as it is scraped.

```json
{
  "country": "es",
  "location": "Madrid",
  "monitoringMode": true,
  "notifyTelegramBotToken": "123456:ABC…",
  "notifyTelegramChatId": "473801635",
  "notificationLimit": 10
}
```

`notifyWebhookUrl` POSTs `{ source, runId, sentAt, count, listings }` with the full rows. Telegram needs the bot token from @BotFather plus the chat id. Slack takes an Incoming Webhook URL, Discord a channel webhook (Discord caps a message at 2,000 characters, so long batches are cut there). Several channels at once is fine — each batch goes to all of them.

Pair it with `monitoringMode` and you are told about new listings only. Without it, every listing the run returns is sent.

The credentials are yours, and a dead endpoint never costs you the scrape: sends are capped at 50 messages per run, a failure is logged rather than thrown, and the "no results" marker and market-analysis rows are never sent anywhere.

##### Sampling a market (`maxPages`)

Each page is 30 listings. `maxPages: 3` stops every search after three of them, whatever `maxItems` says — three requests against a 40,000-listing province instead of a full walk.

##### Smaller rows (`compact`, `excludeEmptyFields`, `descriptionMaxLength`, `descriptionFormat`)

A full detail row is large because three blocks are large: Idealista's own translations of the description, the entire photo gallery, and the search row attached to each detail. `compact` drops those three and keeps identity and links, price, type, size and layout, the whole location block, the advertiser's contact details, the description, the energy certificate, the engagement counters if you asked for them, and one thumbnail.

Measured on listing 109630900: **133,755 bytes as delivered, 3,371 with `compact` on.**

`excludeEmptyFields` removes nulls and empty strings, lists and objects at any depth. `descriptionMaxLength` cuts the advertiser's text to N characters and marks the cut. `descriptionFormat` writes that text as `original`, `text` (one paragraph, for a spreadsheet cell), `html` or `markdown`. The "no results" marker and market-analysis rows are never trimmed.

##### Results language (`language`)

Idealista writes its own text in six languages, and one setting switches all of it — the listing title, the feature labels, and the wording on the engagement counters. The same Madrid listing comes back as "Penthouse for sale in Calle de Alcalá" in English, "Ático en venta en" in Spanish, "Penthouse à vendre" in French, "Penthouse zu verkaufen in" in German and "Attico in vendita in" in Italian.

```json
{ "country": "es", "location": "Madrid", "language": "es", "maxItems": 100 }
```

The advertiser's own description stays in the language they wrote it in — that is their text, not Idealista's. Idealista's translations of it come through `translatedTexts` either way.

##### Long-term or seasonal rentals (`rentalType`)

Idealista splits its rental market in two, and so can you. `rentalType: "longTerm"` returns ordinary residential letting; `rentalType: "seasonal"` returns *alquiler de temporada* — months rather than years, which is the stock behind short-let yield. Measured on Madrid on 10 September 2026: 10,631 rentals in total, 6,909 long-term, 3,722 seasonal.

```json
{
  "country": "es",
  "operation": "rent",
  "propertyType": "homes",
  "location": "Madrid",
  "rentalType": "seasonal",
  "maxItems": 500
}
```

Rent searches only — Idealista returns nothing for it on a sale search, and the run log says so rather than returning an empty dataset. It works on Spain, Italy and Portugal. Idealista offers this filter in its app but not as a website URL, so it is available through the form rather than through a Start URL.

Pair it with `marketAnalysis` to get the short-let read on exactly the stock the analysis is about.

##### Listing engagement stats (`fetchStats`)

Set `fetchStats: true` and every row gains a `_stats` block with Idealista's own counters:

```json
"_stats": {
  "views": 12593,
  "contactMails": 13,
  "sentToFriend": 0,
  "favorites": 333,
  "text": { "views": "12,593 views", "favorites": "saved as favourite 333 times" }
}
```

This is the demand signal behind a listing. A flat with 12,000 views and 333 saves that is still on the market says something its asking price does not; a fresh listing with no traction says the opposite. Useful for spotting overpriced stock, ranking leads by real interest, and dating how long an ad has been working.

It costs one extra request per listing, so a large run takes roughly twice as long — hence off by default. If the counters cannot be fetched for a listing the row still arrives, with `_stats` set to `null`.

##### Search rows without the detail fetch (`fetchDetails`)

Detail fetches are on by default and are where the deep fields come from: `moreCharacteristics`, energy certification, translated texts, the agency's phone, the full `ubication` block. Set `fetchDetails: false` and each listing is delivered as its search row instead — still around 50 fields including the description, the listing thumbnail, price, size, rooms, floor, coordinates and the advertiser's contact block (a search result carries one photo per listing — the full gallery needs the detail fetch) — at one request per page of 30 rather than one per listing. Much faster on large searches, and lighter on Idealista.

Holiday rentals ignore this setting: Idealista publishes no detail page for them at all, so they always arrive as search rows.

##### Search by postal code (Buscar por código postal)

Skip the Location ID — pass one or more postal codes and Idealista resolves each server-side. Each code runs as its own search and the results merge into one dataset:

```json
{
  "country": "es",
  "operation": "sale",
  "propertyType": "homes",
  "postalCodes": ["28013", "28004"],
  "maxItems": 500
}
```

Every filter above (price, size, bedrooms, amenities) applies to each postal-code search too. Works on Spain, Italy and Portugal.

##### Radius search around a point

Pass a `center` as `"latitude,longitude"` and a `distanceKm` radius to pull every listing within that distance. Idealista's radius is coordinate-based, so `distanceKm` needs a `center` — it has no effect on a Location ID or postal-code search:

```json
{
  "country": "es",
  "operation": "sale",
  "propertyType": "homes",
  "center": "40.4168,-3.7038",
  "distanceKm": 5,
  "maxItems": 500
}
```

> ⚠️ **Start URLs take precedence.** If Start URLs has any value, that is the search and the form fields are ignored (the run log says so explicitly). Leave Start URLs empty to use the form. This keeps a filled-in form from silently adding a second, separately-billed search.

Both modes share the same engine, output schema and per-row price — pick whichever suits you.

### Use cases

| Audience | Use case |
|---|---|
| **Real estate investors** | Track every property in target neighborhoods; detect under-priced listings; monitor agent inventory |
| **Market analysts** | Build price-per-m² datasets by province/district; track new construction supply |
| **Proptech / CRM vendors** | Bulk import for proptech SaaS demos, lead enrichment, comparable-property analysis |
| **Estate agents** | Monitor competitor listings, agent activity, asking price changes over time |
| **Hedge funds / family offices** | Wide-net data collection across Iberia for real-asset allocation models |
| **Sales / lead generation** | Build contact lists of real-estate **agencies with phone numbers** per city/region (`scrapeAgencies: true`) for B2B outreach, CRM seeding, partnership prospecting |
| **Academic / news / NGO** | Housing affordability research, gentrification tracking, agency concentration studies |

### How it works

1. **Classify each `startUrls[]` entry** — search, property, new-development, or filter. Reject non-Idealista hosts.
2. **For search URLs**: probe the first page to read the total result count.
3. **If total > 1500** (Idealista's hidden cap): **automatically capture the full result set past the cap**, dedupe by property ID, and merge into one dataset.
4. **For individual property URLs**: read that listing directly — yields the full 80+ field schema.
5. **For new-development URLs**: same as property but includes the `promotion` block (development name, total units, base price, completion status).
6. **In monitoring mode**: cross-reference each `adid` against the previous-run key-value store; skip duplicates.
7. **With `detectPriceChanges`**: before dedup, compare each listing's current price against the price stored from prior runs; emit a `price_changed` row (old / new / delta / %) for any move, to a separate `idealista-changes-<runId>` dataset.
8. **With `detectRemovedListings`**: at the end of a full-scan run, diff the current listing set against the previous run's snapshot; emit a `removed` row for anything gone, to a separate `idealista-removed-<runId>` dataset.
9. **Output**: one flat row per property to the Apify dataset. JSON or CSV export.

### Input configuration

| Field | Type | Required | Default | Notes |
|---|---|---|---|---|
| `startUrls` | `string[]` | yes | — | Mix of search, property, new-development, filtered URLs across `.com` / `.it` / `.pt` |
| `maxItems` | `integer` | no | `10000` | Hard cap on total dataset rows. Each row = one paid `result` event. |
| `splitByPrice` | `boolean` | no | `true` | **Master switch for complete result sets.** Leave on unless you specifically want legacy-cap behavior. |
| `scrapeAgencies` | `boolean` | no | `false` | **Agency mode.** Emit one row per unique real-estate **agency** (name, **phone number**, profile URL, microsite, logo) found across your search URLs, instead of property rows. `maxItems` then caps unique agencies. See [Agency mode](#agency-mode-agencies-with-phone-numbers). |
| `monitoringMode` | `boolean` | no | `false` | Skip listings seen in previous runs. Useful for daily-delta workflows. |
| `detectPriceChanges` | `boolean` | no | `false` | **Requires `monitoringMode`.** Track price changes across runs — emits a `price_changed` row per move (`oldPrice`, `newPrice`, `priceDelta`, `pctChange`, `direction`, `firstSeenAt`, plus listing URL & address) to a separate `idealista-changes-<runId>` dataset. Billed at the low `additional-data` rate ($0.001/row), not the per-result price. |
| `detectRemovedListings` | `boolean` | no | `false` | **Requires `monitoringMode` + a full scan.** Detect listings that left the market since the last run — emits a `removed` row (`propertyCode`, `url`, `searchUrl`, `detectedRemovedAt`) to a separate `idealista-removed-<runId>` dataset, billed at the `additional-data` rate. Set `maxItems` high enough to enumerate the whole search; truncated runs are skipped so nothing is false-flagged. |
| `indexMode` | `boolean` | no | `false` | **Index / delta monitoring.** Scan searches and emit only slim `new` / `price_changed` / `removed` event rows to the **default dataset** — no detail fetches, no charges for unchanged listings (just the `index-scan` fee, $0.10/1,000 scanned). Implies change + removal tracking; keep `splitByPrice` on so big searches enumerate fully. Regular search URLs only. Paid plans only. |
| `seedBaseline` | `boolean` | no | `false` | With `indexMode` on your **first** run: record the current state without emitting `new` rows (your database already has them). Turn off afterwards. |
| `maxConcurrency` | `integer` | no | `10` | Parallel detail-page fetches. Sweet spot 8–15 via Apify Residential. |
| `minConcurrency` | `integer` | no | `1` | Floor — auto-scales up under good conditions. |
| `maxRequestRetries` | `integer` | no | `100` | Per-URL retry budget on transient failures (Idealista occasionally 403s individual requests). |
| `proxy` | object | no | built-in residential | **Leave empty** — the actor already routes all traffic through its own built-in residential proxy at no extra cost. Only set this to override with your own proxies. |

#### Example input

```json
{
  "startUrls": [
    { "url": "https://www.idealista.com/venta-viviendas/madrid/" },
    { "url": "https://www.idealista.it/vendita-case/milano/" },
    { "url": "https://www.idealista.com/inmueble/109366429/" }
  ],
  "maxItems": 5000,
  "splitByPrice": true,
  "monitoringMode": false,
  "maxConcurrency": 10
}
```

This yields up to 5,000 rows across Madrid sale listings + Milan sale listings + one specific Madrid property — all with complete result sets where applicable.

### Output schema

One flat row per property. Below is a real, shortened sample. Full row carries 80+ fields nested under `basicInfo` / `moreCharacteristics` / `contactInfo` / `multimedia` / `ubication` / `translatedTexts`.

```jsonc
{
  "adid":              109195360,
  "price":             2500000,
  "priceInfo":         { "amount": 2500000, "currencySuffix": "€" },
  "operation":         "sale",              // "sale" / "rent"
  "propertyType":      "homes",             // "homes" / "rooms" / "premises" / "garages"
  "extendedPropertyType": "chalet",
  "homeType":          "chalet",
  "state":             "active",
  "country":           "es",                // "es" / "it" / "pt"

  // ── Location ──────────────────────────────────────────────────
  "ubication": {
    "title":           "Calle Ágata, 2",
    "latitude":        36.476812,
    "longitude":       -5.0222844,
    "hasHiddenAddress": false,
    "administrativeAreaLevel4": "Nueva Atalaya",      // neighborhood
    "administrativeAreaLevel3": "Benamara - Atalaya", // district
    "administrativeAreaLevel2": "Estepona",           // city
    "administrativeAreaLevel1": "Málaga",             // province
    "locationId":      "0-EU-ES-29-07-001-051-07-007",
    "locationName":    "Nueva Atalaya, Estepona"
  },

  // ── Contact + agent ──────────────────────────────────────────
  "contactInfo": {
    "commercialName":  "ATTA VILLAS",
    "phone1":          { "formattedPhoneWithPrefix": "+34 951 12 00 41", ... },
    "contactName":     "Boren Brothers SL.",
    "userType":        "developer",          // "developer" / "professional" / "private"
    "agencyLogo":      "https://st3.idealista.com/22/0c/ed/villas-atta.gif",
    "micrositeShortName": "villas-atta",
    "professional":    true
  },

  // ── Property features ────────────────────────────────────────
  "moreCharacteristics": {
    "roomNumber":      4,
    "bathNumber":      4,
    "plotOfLand":      681,                  // m²
    "constructedArea": 530,
    "swimmingPool":    true,
    "garden":          true,
    "boxroom":         true,
    "chaletType":      "independantHouse",
    "energyCertificationType": "inProcess",
    "modificationDate": 1758214533000        // unix ms
  },

  // ── Multimedia (full image list) ─────────────────────────────
  "multimedia": {
    "images": [
      { "url": "...", "tag": "facade", "width": 1500, "height": 844 },
      { "url": "...", "tag": "plan",   "width": 1489, "height": 820 }
      // ... typically 10-50 images per property
    ],
    "videos": [],
    "hasMultimediasMadeByIdealista": false
  },

  // ── Descriptions (multi-language, auto-translated) ───────────
  "propertyComment":   "Villa de lujo de obra nueva con piscina y spa...",
  "comments": [
    { "language": "es", "autoTranslated": false, "defaultLanguage": true,  "propertyComment": "..." },
    { "language": "en", "autoTranslated": false, "defaultLanguage": false, "propertyComment": "..." },
    { "language": "de", "autoTranslated": true,  "defaultLanguage": false, "propertyComment": "..." },
    { "language": "nl", "autoTranslated": true,  "defaultLanguage": false, "propertyComment": "..." }
  ],

  // ── New-development info (when applicable) ───────────────────
  "promotion": {
    "promotionId":     109190794,
    "name":            "Atta Villas",
    "description":     "Detached houses of 4 bedrooms for sale",
    "price":           1800000,              // base/starting price
    "promotionType":   "notFinished"
  },

  // ── Misc ─────────────────────────────────────────────────────
  "labels":            [ { "name": "luxuryType", "text": "Luxury" }, { "name": "villaType", "text": "Villa" } ],
  "detailWebLink":     "https://www.idealista.com/inmueble/109195360/",
  "modificationDate":  { "value": 1758214533000, "text": "Listing updated 10 days ago" }
}
```

#### Price-change rows (`detectPriceChanges`)

When `detectPriceChanges: true`, each detected price move is written to a **separate run dataset** named `idealista-changes-<runId>` (not your main output — open it from the run's Storage tab). One row per change:

```jsonc
{
  "status":       "price_changed",
  "propertyCode": "107120613",
  "oldPrice":     130000,
  "newPrice":     124930,
  "priceDelta":   -5070,                 // negative = price cut
  "pctChange":    -3.9,                   // % vs the old price
  "direction":    "decrease",            // "increase" / "decrease"
  "firstSeenAt":  "2026-07-10T08:24:16.805Z",   // when we first tracked it
  "url":          "https://www.idealista.com/inmueble/107120613/",
  "address":      "Flat / apartment in Calle Vázquez López, Centro, Huelva",
  "municipality": "Huelva",
  "province":     "Huelva",
  "operation":    "sale",
  "searchUrl":    "https://www.idealista.com/venta-viviendas/huelva-huelva/",
  "detectedAt":   "2026-07-17T08:26:34.291Z"
}
```

#### Removed-listing rows (`detectRemovedListings`)

When `detectRemovedListings: true`, listings that disappeared since the previous full-scan run are written to a **separate run dataset** named `idealista-removed-<runId>`. One row per removed listing:

```jsonc
{
  "status":            "removed",
  "propertyCode":      "30604707",
  "url":               "https://www.idealista.com/inmueble/30604707/",
  "searchUrl":         "https://www.idealista.com/venta-viviendas/soria-soria/",
  "detectedRemovedAt": "2026-07-17T09:21:03.384Z"
}
```

#### Index / delta mode rows (`indexMode`)

With `indexMode: true` the actor fetches **no property details at all**. It scans your search results and writes slim event rows straight to the **default dataset** — one per new listing, price move, or removal:

```jsonc
{ "status": "new",           "propertyCode": "108123456", "price": 465000, "url": "https://www.idealista.com/inmueble/108123456/", "municipality": "Barcelona", "searchUrl": "…", "detectedAt": "…" }
{ "status": "price_changed", "propertyCode": "107988001", "oldPrice": 500000, "newPrice": 479000, "priceDelta": -21000, "pctChange": -4.2, "direction": "decrease", "url": "…", "searchUrl": "…", "detectedAt": "…" }
{ "status": "removed",       "propertyCode": "30604707",  "url": "…", "searchUrl": "…", "detectedRemovedAt": "…" }
```

Typical loop: run `indexMode` on a schedule to keep your own database in sync, and when you want full details for the `new` listings, start a normal run (no `indexMode`) with their property URLs as `startUrls`. On the very first index run set `seedBaseline: true` so listings your database already holds aren't emitted (and billed) as `new`. Removal detection needs the whole search enumerated — keep `splitByPrice` on and `maxItems` high; truncated searches are skipped, never false-flagged.

The scan fee is $0.10 per 1,000 listings scanned. Until the dedicated `index-scan` event activates (September 10, 2026) it shows on your bill as `additional-data` events, one per 10 listings scanned — the same total; after that date it appears as `index-scan`, $0.0001 each.

### Photos

Every row carries the listing's photo URLs, ready to display in your own app or save locally. Nothing in this actor has to fetch them for you, so photos cost you nothing here.

`imageSize` rewrites the size of every photo URL on the row (`multimedia.images[].url`, the `basicInfo` copies and `thumbnail`) so you do not have to edit URLs yourself. It costs nothing and adds no run time, because only the string changes:

| `imageSize` | Approx. weight per photo |
|---|---|
| `original` | whatever Idealista returned |
| `small` | 13 KB |
| `thumbnail` | 26 KB |
| `detail` | 46 KB |
| `large` | 112 KB |

Sizes are one sample photo measured at each setting. On a grid of a few thousand listings the difference between `small` and `large` is the difference between a page that loads and one that does not.

To save the files locally, the URLs are ordinary downloads:

```bash
## every photo from one row of your dataset
curl -s "https://api.apify.com/v2/datasets/<DATASET_ID>/items?fields=multimedia&limit=1" \
  | python3 -c "import json,sys;[print(i['url']) for i in json.load(sys.stdin)[0]['multimedia']['images']]" \
  | xargs -n1 -P4 curl -sO
```

### Keep every run in one dataset

By default each run leaves its own dataset, which is awkward on a schedule: a daily search gives you thirty datasets a month. Set `datasetName` and the run also copies its rows into that dataset in your account, so the schedule builds up in one place. `datasetId` does the same against a dataset you already have.

The run still produces its own dataset exactly as before — this is a copy, not a move. If the copy fails for any reason, the run is unaffected and says so in the log. A run that produced no rows copies nothing, so a blocked run can never dilute what you have already collected, and a resurrected run will not append its rows twice.

Named datasets are never deleted automatically, so they count against your account storage until you remove them.

### Agency mode (agencies with phone numbers)

Set `scrapeAgencies: true` to flip the output from properties to **real-estate agencies**. The actor runs the same search pipeline (returning the complete result set) but, instead of one row per property, it emits **one row per unique agency** that appears in the results — deduplicated by microsite across every page.

Crucially, each row includes the agency's **phone number**, included on every row — the field most agency scrapers leave empty.

```json
{
  "scrapeAgencies": true,
  "startUrls": [{ "url": "https://www.idealista.com/venta-viviendas/madrid-madrid/" }],
  "maxItems": 500
}
```

Each row:

```jsonc
{
  "agencyName":         "Walter Haus Madrid",
  "phone":              "+34 919386183",        // ← the real number, not just a profile link
  "phoneRaw":           "919386183",
  "phonePrefix":        "34",
  "contactName":        "Walter Haus",
  "micrositeShortName": "walterhauschamberi",
  "profileUrl":         "https://www.idealista.com/pro/walterhauschamberi/",
  "agencyLogo":         "https://st3.idealista.com/.../logo.gif",
  "userType":           "professional",
  "firstSeenPropertyCode": "108342199",
  "country":            "es",                    // es / it / pt
  "sourceUrl":          "https://www.idealista.com/venta-viviendas/madrid-madrid/",
  "scrapedAt":          "2026-06-05T10:40:00.000Z"
}
```

Notes:

- **`maxItems` caps unique agencies** in agency mode (not properties).
- Works on `.com` / `.it` / `.pt` search URLs; `profileUrl` uses the matching TLD.
- **Email is not included** — Idealista does not publish agency email addresses (contact is via phone or an on-site form), so no scraper can provide it. We return the phone, which is the actionable contact.

### Pricing

Pay-per-event — no monthly subscription, no upfront commitment.

| Event | When it fires | Rate |
|---|---|---|
| `Actor Start` | Once per run | $0.005 |
| `result` | Per row emitted — a property listing, or an agency in agency mode (same price) | $0.001 |
| `Additional cost for monitoring mode` | Per **detected** price-change / removed row from the monitoring extras (never per listing checked — unchanged listings are free) | $0.001 |
| `index-scan` | Per listing scanned in `indexMode` (covers search enumeration; no other charge for unchanged listings). Until this event activates on Sep 10, 2026, the same $0.10/1,000 is billed as `additional-data` events, 1 per 10 listings scanned | $0.0001 |

**Cost example:**

- Madrid sale search with 1,967 rows (complete set) = **$0.005 + 1967 × $0.001 = ~$1.97**
- Same search via a competitor that stops at the 1500 cap: 1,500 rows = $1.50
- `indexMode` sync of a 6,500-listing portfolio with ~150 changes = **$0.65 scan + ~$0.15 in event rows ≈ $0.80** (vs ~$6.50 for a full re-scrape)
- You pay **$0.47 more** to get **31% more data** — net cost per useful row is **17% lower**.

### What makes this richer than competing actors

We surveyed all Idealista actors on Apify Store. Direct comparison:

| Capability | Competitors | This actor |
|---|---|---|
| Complete result set, no 1,500-row truncation | ❌ silent truncation | ✅ full result-set capture (proven +31%) |
| Spain + Italy + Portugal in one pipeline | ❌ usually Spain-only | ✅ all three, one actor |
| GPS lat/lng on every row | partial | ✅ always (when not hidden by seller) |
| Multi-language `comments` array | ❌ | ✅ up to 6 languages per listing |
| New-development `promotion` block | partial | ✅ full block with starting price + completion status |
| Energy certification details | rarely | ✅ `energyCertificationType` + `energyConsumption` |
| Agent microsite + logo URL | ❌ | ✅ `agencyLogo`, `micrositeShortName`, agent's `totalAds` |
| Monitoring mode (incremental scrapes) | rarely | ✅ deduplication by `adid` |
| Multimedia tagged by type (facade/plan/livingRoom/...) | ❌ flat list | ✅ tagged + dimensioned + 360° flag |
| Price-per-m² (`priceByArea`) | partial | ✅ always when computable |
| `allowsCounterOffers` / `allowsRemoteVisit` / `allowsMortgageSimulator` flags | ❌ | ✅ |
| Long-term vs seasonal rental split | rarely | ✅ `rentalType` — 6,909 long-term and 3,722 seasonal out of 10,631 Madrid rentals |
| Listing engagement counters | rarely | ✅ `fetchStats` — views, email contacts, times shared, times favourited |
| Business transfers, whole buildings, holiday rentals | partial | ✅ all eleven of Idealista's verticals |
| Sort by distance from a point | ❌ | ✅ `sortBy: "distance"` with a `center` and radius |
| Search rows without the per-listing fetch | partial | ✅ `fetchDetails: false` — one request per page of 30 |
| Several agencies in one run | partial | ✅ `agencies` — slugs or /pro/ URLs, no location needed |
| Listings pushed to Telegram / Slack / Discord / a webhook | rarely | ✅ any or all of them, batched |
| Trim the row before it is stored | ❌ | ✅ `compact` — 133,755 bytes down to 3,371 on the same listing |
| A run that finds nothing tells you why | ❌ marked failed | ✅ `reason` on the row: no matches, listings removed, or blocked |

### Coming from another Idealista scraper?

These are the pain points users of other Idealista actors report most often — and how this actor handles each:

| Common complaint elsewhere | This actor |
|---|---|
| **Duplicate listings** in the output | Deduplicated by `adid` within every run — no repeats |
| **Timeouts / partial runs** on large searches | Works around the 1,500-result cap by splitting server-side; transient auth failures are retried automatically |
| **"Scrape by URL" not supported** | URL-first by design: paste any search URL, filtered URL, or single-property URL |
| **Forced to hand-build URLs / hunt location IDs** | Both modes shipped: paste a URL **or** fill the form (country, operation, type, Location ID + price/size/room/amenity filters) |
| **Missing plot area, energy rating, or owner type** | `plotOfLand`, `energyCertificationType`, `energyConsumption`, `userType` (private vs agency), `postalCode` and `modificationDate` are all in the output |
| **No market / aggregated data** | Optional `marketAnalysis` — per-area short-let ADR, occupancy, rent & yield with cited sources |
| **One location per run** | `locations`, `locationIds` and `postalCodes` each take a list, `startUrls` takes as many search URLs as you like, and `scrapeWholeCountry` fans a single search across every province — all in one run |
| **No search by postal code** | `postalCodes` accepts the codes directly, so you never have to track down a Location ID first |
| **Can't restrict a search to one agency** | `agency` for a single agency, `agencies` for several — the search is built per agency rather than filtered afterwards |
| **`fetchDetails` returns the same output whether it's on or off** | Switching it off really does skip the per-listing detail fetch and return summary rows; switching it on adds the full detail payload. The log says which mode ran |
| **No agent contact details** | Agent **phone numbers** (agency mode) plus optional **email enrichment** |
| **Run marked failed when the listings were simply gone** | A listing taken down since you saved the link comes back as a row saying so, with `removedAt` and `removedBy`; a search that genuinely matches nothing finishes successfully with the reason on the row |

### FAQ

**My run returned no rows. What happened?**
The run tells you, on the row itself. `reason: "no_matches"` means the search ran and Idealista has nothing that fits those filters — usually a filter combination that is narrower than intended. `reason: "all_listings_gone"` means every listing you asked for has been taken down; a directly requested listing arrives as its own row with `removedAt` and `removedBy` so you can see when and by whom. `reason: "search_failed"` is the only one that is ours, and only that one marks the run failed.

**Why does Idealista limit each query to 1,500 results?**
It is a limit on how many results a single query returns. The website's UI doesn't show it, but every paginated query stops at page 60 of 25 = 1,500 rows. Other scrapers don't know to work around it. This actor probes the total upfront and, if the count would exceed 1,500, automatically works around the cap to capture and merge the complete result set.

**Do complete result sets cost extra?**
No — we charge per row, regardless of how many sub-queries we needed to walk to collect them. If your search has 800 rows total, the actor does one fetch and charges 800 × $0.001 = $0.80. If it has 8,000 rows, the actor runs the extra sub-queries needed and charges 8,000 × $0.001 = $8.00. The extra work is on us.

**Can I run this on `idealista.it` and `idealista.pt`?**
Yes. Same code path, same row schema. Just paste Italian or Portuguese URLs into `startUrls`. The `country` field on each row tells you which TLD it came from (`es` / `it` / `pt`).

**How does monitoring mode work?**
On each run with `monitoringMode: true`, the actor maintains a key-value store of every `adid` it has already emitted. Subsequent runs skip those IDs and only emit new ones. Useful for daily/weekly deltas without re-paying for the same listings. Costs an extra $0.001 per row to cover the dedup-store overhead.

**How does price-change detection work?**
Turn on both `monitoringMode: true` and `detectPriceChanges: true`. The actor stores each listing's price and, on every later run, compares the current price against the stored one — any change emits a `price_changed` row (`oldPrice`, `newPrice`, `priceDelta`, `pctChange`, `direction`, `firstSeenAt`, plus the listing's URL & address). To keep it cheap, these rows go to a **separate run dataset** named `idealista-changes-<runId>` (open it from the run's Storage tab, not your main output) and are billed at the low `additional-data` rate ($0.001/row), not the per-result price. Great for watching price drops on properties you track. Example input:

```json
{
  "startUrls": [{ "url": "https://www.idealista.com/venta-viviendas/madrid/" }],
  "monitoringMode": true,
  "detectPriceChanges": true,
  "maxItems": 1000
}
```

**How does removed / sold detection work?**
Turn on both `monitoringMode: true` and `detectRemovedListings: true`. At the end of each run, the actor compares the current listing set of each search against a snapshot from the previous run — anything that vanished is emitted as a `removed` row to a **separate run dataset** `idealista-removed-<runId>`, billed at the low `additional-data` rate. **It needs a full scan:** set `maxItems` high enough to cover the entire search (e.g. above the search's total result count). If a run stops early at `maxItems`, that search is skipped for removal detection — so a partial run never wrongly reports listings as removed. Best paired with `detectPriceChanges` for a complete market-change feed (new + price-moved + gone).

**Why is `ubication.hasHiddenAddress: true` on some listings?**
Sellers can choose to hide their exact street address — only the neighborhood + city + province are shown to public viewers. We honor that flag and emit only what Idealista exposes. GPS coords are still populated (Idealista shows an approximate pin in this case).

**What's the difference between `propertyComment` and `comments[]`?**
`propertyComment` is the description in the listing's default language (usually Spanish/Italian/Portuguese). `comments[]` is the array of all language versions, including auto-translated ones via Idealista's built-in translator. Use `comments[]` to get the English version if you need it.

**Can I get a list of real-estate agencies with phone numbers?**
Yes — set `scrapeAgencies: true` and pass any search/result URL (e.g. `/venta-viviendas/madrid-madrid/`). Instead of properties, you get one row per unique agency with its **phone number**, profile URL, microsite, and logo, deduplicated across all pages. `maxItems` caps the number of unique agencies. Email isn't included — Idealista doesn't publish agency emails. See [Agency mode](#agency-mode-agencies-with-phone-numbers).

**Can I scrape rentals?**
Yes — just paste rental URLs (`/alquiler-viviendas/...` instead of `/venta-viviendas/...`). The `operation` field on each row will be `"rent"` instead of `"sale"`.

**Is there a way to filter by price/rooms/area before scraping?**
Two ways, both fully supported:

1. **Form search** — leave Start URLs empty and set `locationId` plus the filter fields (price, size, bedrooms, bathrooms, condition, and the amenity toggles). No URL building required. See [Form search](#form-search-no-url-needed).
2. **URL filters** — paste a filtered Idealista URL and the actor respects every filter in it:

```
https://www.idealista.com/en/geo/venta-obranueva/andalucia/con-2-dormitorios,3-dormitorios,piscina/
```

Both routes feed the same search engine, so the output schema and per-row price are identical.

### Support

- **Bugs / feature requests** — open an [issue on this actor](https://console.apify.com/actors/7Fw4OYjfMapM6l49D/issues)
- **Custom exports / tailored field selection** — email <muhamed.didovic@gmail.com>
- **API access (no Apify fee, raw usage)** — email the same address for direct API setup

### Additional services

- Custom scraping work for sites not in the catalog
- Bulk historical dataset purchase (no need to run the scraper yourself)
- Webhook delivery to your S3 / GCS / DB pipeline
- Daily / hourly scheduled monitoring with email or Telegram alerts

Contact: <muhamed.didovic@gmail.com>

### Explore more scrapers

Other Iberia + EU real-estate actors in the [memo23 portfolio](https://apify.com/memo23):

- [Immobilienscout24 (Germany)](https://apify.com/memo23/immobilienscout24-scraper) — DE real estate
- [Immobiliare (Italy)](https://apify.com/memo23/immobiliare-scraper) — IT real estate (complements Idealista.it)
- [Funda (Netherlands)](https://apify.com/memo23/funda-scraper) — NL real estate
- [Kleinanzeigen (Germany)](https://apify.com/memo23/kleinanzeigen-search-scraper-ppe) — DE classifieds
- [Realestate AU + NZ](https://apify.com/memo23/realestate-au-listings) — Australia + New Zealand bundled
- [Dubizzle (UAE)](https://apify.com/memo23/dubizzle-search-listing-s-scraper) — UAE real estate + autos

***

### 🤖 For AI Agents & LLM Apps

Compact reference for AI agents calling this actor via the [Apify MCP server](https://mcp.apify.com) or the Apify API (actor: `memo23/idealista-scraper`).

**Purpose:** Extracts property listings from idealista.com (Spain), idealista.it (Italy), and idealista.pt (Portugal) — one row per property with 80+ fields — and bypasses Idealista's 1,500-results-per-query cap.

**Minimal input:**

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

Single-property variant: `{ "startUrls": ["https://www.idealista.com/inmueble/109366429/"] }`. Agency-list variant: add `"scrapeAgencies": true` to any search input.

**Output:** one dataset row per property — adid, price, priceInfo {amount, currencySuffix}, operation, propertyType, state, country, ubication {latitude, longitude, administrativeAreaLevel1–4, locationId, locationName}, contactInfo {commercialName, phone1, userType, agencyLogo, micrositeShortName}, moreCharacteristics {roomNumber, bathNumber, constructedArea, plotOfLand, swimmingPool, energyCertificationType}, multimedia {images, videos}, propertyComment, comments, promotion, labels, detailWebLink, modificationDate. Agency mode instead: agencyName, phone, profileUrl, micrositeShortName, agencyLogo, userType, country.

**Behaviors an agent should know:**

- Always set `maxItems` (default 10000) — each row is billed, and a broad search returning the complete set can run to many thousands of rows.
- Only `idealista.com` / `.it` / `.pt` URLs are accepted: search, filtered search, individual property (`/inmueble/{id}/`), and new-development (`/obra-nueva/{id}/`) URLs; other hosts are rejected.
- `splitByPrice` (default `true`) returns the complete result set rather than the first 1,500. `scrapeAgencies: true` switches output to one row per unique agency; `maxItems` then caps agencies.
- `monitoringMode: true` emits only listings new since previous runs; add `detectPriceChanges` / `detectRemovedListings` (both require monitoring mode) for change rows in separate `idealista-changes-<runId>` / `idealista-removed-<runId>` datasets.
- Billing: $0.005 per run start + $0.001 per result row; monitoring mode adds $0.001 per row; price-change/removed rows bill at the low additional-data rate.
- Leave `proxy` empty — traffic already routes through the actor's built-in residential proxy. Agency emails are not available (Idealista doesn't publish them).

***

### ⚠️ Disclaimer

This Actor is an independent tool and is **not affiliated with, endorsed by, or sponsored by** Idealista S.A., Idealista.com, Idealista.it, Idealista.pt, or any related entity. All trademarks mentioned are the property of their respective owners.

The scraper accesses only **publicly visible** property listings shown on Idealista's public website. No login bypass, no API-key forgery, no cookie or session harvesting. The actor honours `robots.txt` and rate-limits via concurrency cap (default 10) to avoid burdening Idealista's infrastructure.

Users are responsible for:

- Complying with Idealista's Terms of Service in your target jurisdiction (`.com`, `.it`, `.pt`)
- Following EU GDPR + Spanish LOPD + Italian Privacy Code + Portuguese RGPD when storing, processing, or republishing scraped property + agent contact data
- Not contacting sellers / agents listed in scraped data for unsolicited commercial outreach
- Not republishing scraped property listings in a way that competes commercially with Idealista (e.g., a clone real-estate portal)
- Honoring `hasHiddenAddress: true` flags — do not attempt to de-anonymize sellers who chose privacy

We do not store scraped data — the Actor returns rows directly to your Apify dataset for your authorized use.

***

### SEO Keywords

idealista scraper, idealista.com scraper, idealista spain scraper, idealista italy scraper, idealista portugal scraper, scrape idealista, idealista api, idealista bulk export, spain real estate scraper, italy real estate scraper, portugal real estate scraper, iberia real estate data, madrid property scraper, barcelona property scraper, milan property scraper, lisbon property scraper, complete result sets, property listing api, real estate market intelligence, real estate lead generation, agent contact scraper, MLS alternative spain, idealista monitoring, property price tracker, real estate JSON export, idealista agency scraper, idealista agencies scraper, real estate agency contacts, real estate agency phone numbers, idealista agent phone scraper, estate agency lead generation spain

# Actor input Schema

## `instantDatabase` (type: `boolean`):

Serve agencies from the database instead of live-scraping. Auto-enabled if you set Agency name below.

## `dbAgencyName` (type: `string`):

e.g. Tecnocasa. Optional. Returns only Instant-Database agencies whose name contains this text; setting it auto-enables Instant Database mode (no live scraping).

## `dbCountry` (type: `string`):

Limit to one market: es (Spain), it (Italy) or pt (Portugal). Leave empty for all three.

## `dbHasPhone` (type: `boolean`):

Only return agencies that have a phone number on file (virtually all do).

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

URLs to start with. Accepts Idealista search URLs, filtered-search URLs, individual property URLs (/inmueble/{id}/) and new-development URLs (/obra-nueva/{id}/) on idealista.com, idealista.it or idealista.pt — other hosts are rejected. Example: https://www.idealista.com/venta-viviendas/madrid-madrid/  ⚠️ Start URLs TAKE PRECEDENCE: if you fill this in, the Form Search fields below are ignored. Leave it empty to use the form instead.

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

Idealista market to search. On France, pick an area with a Location ID, the whole-country sweep, or by typing a place name — idealista.fr keeps its autocomplete behind a challenge, so a typed name is searched as free text rather than resolved to one exact area. idealista.fr Start URLs are not supported.

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

Buy or rent.

## `language` (type: `string`):

The language Idealista returns its own text in — listing titles, feature labels and the wording on the engagement counters. Measured on one Madrid listing: English "Penthouse for sale in Calle de Alcalá", Spanish "Ático en venta en", French "Penthouse à vendre", German "Penthouse zu verkaufen in", Italian "Attico in vendita in". The advertiser's own description stays in the language they wrote it; the translations Idealista holds for it come through <code>translatedTexts</code> either way.

## `rentalType` (type: `string`):

Split the rental market by how long the let is. Long-term is ordinary residential letting; Short-term is Idealista’s “alquiler de temporada” — months rather than years, the stock that feeds short-let yield analysis. Measured on Madrid: 10,631 rentals in total, 6,909 long-term and 3,722 short-term. Ignored on a sale search. Idealista offers this filter in its app but not as a website URL, so it is available here through the form only — a Start URL cannot carry it.

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

What kind of property to search. Three of these exist on one side of the market only, and the operation is corrected for you with a note in the log: Business transfers are for sale only, Holiday rentals and Rooms (shared) are to rent only.

## `location` (type: `string`):

Type a place the way Idealista names it — "Marbella", "Chamberí", or "Marbella, Málaga" when the name is ambiguous. It is resolved to Idealista’s own Location ID before the search runs, so you do not need to look one up. Districts and neighbourhoods work too. A name that cannot be resolved stops the run and lists what Idealista suggested instead.

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

Same as City / area name, but several at once. Each name becomes its own Idealista search and all results merge into one dataset.

## `scrapeWholeCountry` (type: `boolean`):

Sweep every province of the selected country instead of naming a place — 52 in Spain, 107 in Italy, 28 districts and islands in Portugal, 100 departments in France, each run as its own search and merged into one dataset. This is a very large job (Spain alone had ~450,000 listings for sale when the province list was measured), so set Max items unless you really want all of it. Ignored when Start URLs are used.

## `locationId` (type: `string`):

Idealista location ID, e.g. 0-EU-ES-28-07-001-079 (Madrid). Optional — City / area name above resolves one for you. Leave Start URLs empty when using the form.

## `locationIds` (type: `array`):

Advanced: several location IDs in one search. Overrides the single Location ID above when set.

## `postalCodes` (type: `array`):

Search by postal code — no Location ID needed. Add one or more codes (e.g. 28013, 08013, 29602); each is run as its own Idealista search and the results are merged into one dataset. Works for Spain, Italy and Portugal. You can use this on its own (leave Location ID empty) or alongside it.

## `propertyIds` (type: `array`):

Re-fetch known listings by ID (or paste /inmueble/<id>/ URLs). Idealista applies this inside the search, so keep the location and the other filters wide enough to cover them — a mismatch returns nothing rather than an error. Up to ~30 per run.

## `center` (type: `string`):

Latitude,longitude of the point to search around, e.g. 40.4168,-3.7038 (Madrid). Combine with "Search radius" below to pull every listing within X km of this point. Leave empty unless you want a radius search.

## `distanceKm` (type: `integer`):

Radius in kilometres around the Center point above. Example: 5 = everything within 5 km. Requires a Center point — Idealista's radius search is coordinate-based, so this has no effect on a Location ID or postal-code search.

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

Minimum price. Leave empty for no minimum.

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

Maximum price. Leave empty for no maximum.

## `minSize` (type: `integer`):

Minimum built area in m².

## `maxSize` (type: `integer`):

Maximum built area in m².

## `bedrooms` (type: `string`):

Comma-separated: 0=studio,1,2,3,4 (4 means 4+). Example: 2,3,4

## `bathrooms` (type: `string`):

Comma-separated: 1,2,3 (3 means 3+). Example: 2,3

## `preservation` (type: `string`):

Property condition. Single choice, kept for existing saved inputs — "Condition (several)" below takes precedence when set and lets you combine values.

## `condition` (type: `array`):

Property condition, several at a time. Idealista ORs them: measured on Madrid sale, good 14,298 + needs-renovation 2,694 came back as 16,994 together.

## `currentOccupationType` (type: `array`):

Whether the property is free to move into. Idealista lists tenanted and illegally occupied stock separately — useful for investors buying rented assets.

## `homeType` (type: `array`):

Which kinds of home to return. Several can be picked — they widen the search rather than narrowing it.

## `subTypology` (type: `array`):

Idealista’s finer property sub-types, on top of Home type. Several can be picked — they widen the search. Many are regional, so they only return listings where that kind of property exists: each was measured in its own region (detached houses 3,224 Madrid, semi-detached houses 1,129 Madrid, terraced houses 1,653 Madrid, bungalows 969 Alicante, cave houses 232 Granada, stone houses 69 Girona, masías 567 Barcelona, casonas 119 Asturias, and so on). Single-storey houses and attics are offered on sale searches only.

## `floorHeights` (type: `array`):

Which floors to include. Several can be picked.

## `newDevelopment` (type: `boolean`):

Only brand-new / off-plan developments.

## `airConditioning` (type: `boolean`):

Only listings with: air conditioning.

## `elevator` (type: `boolean`):

Only listings with: lift / elevator.

## `garage` (type: `boolean`):

Only listings with: garage / parking.

## `garden` (type: `boolean`):

Only listings with: garden.

## `terrace` (type: `boolean`):

Only listings with: terrace.

## `swimmingPool` (type: `boolean`):

Only listings with: swimming pool.

## `exterior` (type: `boolean`):

Only listings with: exterior-facing.

## `storeRoom` (type: `boolean`):

Only listings with: storage room.

## `builtInWardrobes` (type: `boolean`):

Only listings with: fitted wardrobes.

## `luxury` (type: `boolean`):

Only listings with: luxury.

## `balcony` (type: `boolean`):

Only listings with: balcony.

## `accessible` (type: `boolean`):

Only listings with: wheelchair accessible.

## `virtualTour` (type: `boolean`):

Only listings with: has virtual tour.

## `furnishedKitchen` (type: `boolean`):

Only properties with a fitted kitchen. Idealista offers this on RENT searches only — on a sale search it is ignored.

## `furnished` (type: `boolean`):

Only fully furnished properties. Idealista offers this on RENT searches only — on a sale search it is ignored. Takes precedence over "Fitted kitchen": the two are one either/or filter on Idealista’s side.

## `exteriorDomesticSpace` (type: `boolean`):

Idealista’s combined outdoor-space filter. Wider than the separate Balcony and Terrace toggles.

## `hasPlan` (type: `boolean`):

Only listings that include a floor plan.

## `petsAllowed` (type: `boolean`):

Rentals only — Idealista offers this filter on rent searches.

## `onlyFlats` (type: `boolean`):

Idealista’s narrower "flats only" toggle. Home type = Flat is the broader option (it also covers penthouses and duplexes).

## `energyEfficiency` (type: `string`):

Energy certificate band.

## `auction` (type: `string`):

Idealista accepts only these two values, so this either narrows to auctions or removes them.

## `agency` (type: `string`):

Restrict the search to one agency, by its Idealista microsite slug — the part after /pro/ in the agency URL, e.g. "servihabitat1". Leave empty for all agencies.

## `agencies` (type: `array`):

Scrape one or more agencies by their Idealista slug — the part after /pro/ in the agency's own URL, so <code>idealista.com/pro/savills-madrid/</code> is <code>savills-madrid</code>. Paste either form; a full /pro/ URL is accepted and the slug is taken from it. An agency search needs no location of its own, so a run can be nothing but this list; if you do set a location, every agency is searched inside it. A slug Idealista does not know stops that search with a message naming it, rather than silently returning everything.

## `bankOffer` (type: `boolean`):

Only bank-owned / repossessed stock (Idealista’s "Of banks" filter).

## `seaViews` (type: `boolean`):

Only listings flagged with sea views. Meaningful for coastal areas.

## `publicationDate` (type: `string`):

Only listings published in this window. Idealista offers a different shortest window per search type — 48 hours for sale, 24 hours for rent, and neither for new developments — so the closest available one is used and the run log says when that happened.

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

Field the results are ordered by. Leave empty for Idealista’s own default. Ignored when you use Start URLs — a URL carries its own ordering and wins. "Nearest first" needs a Center point and a radius; on a city or postal-code search Idealista accepts it and then orders by relevance instead.

## `sortDirection` (type: `string`):

Ascending or descending.

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

Maximum number of items that will be scraped. Each item is one billed result row; in agency mode (scrapeAgencies) it caps unique agencies instead of properties. Default: 10000.

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

Each page is 30 listings. 0 means no page limit, and the run stops on <code>maxItems</code> or Idealista's own per-query cap instead. Handy for sampling a market: three pages of a 40,000-listing province is three requests.

## `datasetName` (type: `string`):

A dataset name in your account, e.g. <code>idealista-madrid-daily</code>. Created on the first run and reused after that. Letters, digits, hyphens and underscores. Named datasets are never auto-deleted, so they count against your storage until you remove them.

## `datasetId` (type: `string`):

Use this when the dataset already exists and you want to pin its ID. Takes precedence over the name. If your account cannot write to it, the run says so in the log and still delivers its own dataset.

## `notifyWebhookUrl` (type: `string`):

POSTs <code>{ source, runId, sentAt, count, listings }</code> as JSON. The listings are the full rows, before any trimming from Compact rows.

## `notifyTelegramBotToken` (type: `string`):

From @BotFather. Needs the chat ID below as well. Message @userinfobot, or add your bot to a group and read the chat id from <code>getUpdates</code>.

## `notifyTelegramChatId` (type: `string`):

Where the messages go: your own user id, or a group/channel id (those start with a minus).

## `notifySlackWebhookUrl` (type: `string`):

An Incoming Webhook URL from your Slack app (https://hooks.slack.com/services/…).

## `notifyDiscordWebhookUrl` (type: `string`):

A channel webhook from Discord (Channel → Edit → Integrations → Webhooks). Discord caps a message at 2,000 characters, so long batches are cut there.

## `notificationLimit` (type: `integer`):

How many listings go into one message before it is sent. A run sends at most 50 messages whatever its size.

## `compact` (type: `boolean`):

Keep the fields most runs actually use and drop the three that make a row heavy: Idealista's own translations of the description (<code>comments</code>), the full photo gallery (<code>multimedia</code>) and the search row attached to each detail (<code>basicInfo</code>). Measured on listing 109630900: 133,755 bytes as Idealista delivers it, 3,371 with this on — 40 times smaller, and the fields a price table actually reads are all still there. A compact row keeps identity and links, price, type, size and layout, the full location block, the advertiser's contact details, the description, the energy certificate, the engagement counters when you ask for them, and one thumbnail. Marker rows and market-analysis rows are never trimmed.

## `excludeEmptyFields` (type: `boolean`):

Remove every field that is null, an empty string, an empty list or an empty object, at any depth. Smaller files and cleaner spreadsheets; the trade is that a field's absence no longer tells you Idealista returned it empty.

## `descriptionMaxLength` (type: `integer`):

Cut the advertiser's description to this many characters (an ellipsis marks the cut). 0 keeps it whole. Useful when the description is the field blowing up your row size or your spreadsheet cells.

## `descriptionFormat` (type: `string`):

How the description is written out. Idealista sends plain text with line breaks. <b>Original</b> leaves it exactly as sent; <b>One paragraph</b> flattens the line breaks into a single block, which is what a spreadsheet cell wants; <b>HTML</b> wraps each paragraph in \<p>; <b>Markdown</b> separates paragraphs with a blank line.

## `imageSize` (type: `string`):

Rewrites the size of every photo URL on the row (<code>multimedia.images\[].url</code>, <code>basicInfo</code> and <code>thumbnail</code>) so you do not have to edit the URLs yourself. Costs nothing and adds no run time: only the URL changes, no photo is downloaded. Sizes are the measured weight of one sample photo.

## `fetchStats` (type: `boolean`):

Adds a <code>\_stats</code> field per listing with Idealista's own counters: <code>views</code>, <code>contactMails</code> (people who emailed the advertiser), <code>sentToFriend</code> and <code>favorites</code>, plus Idealista's phrasing for each. This is the demand signal behind an ad — a flat with 34,000 views and 900 saves that has not sold says something a price never will, and a fresh ad with no traction says the opposite. Costs one extra request per listing, so it roughly doubles the time a large run takes; off by default. Needs detail fetches on.

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

On by default. Each listing gets its own request, which is where the deep fields come from — moreCharacteristics, energy certification, translated texts, the agency's phone, the full ubication block. Turn it OFF to deliver the search row instead: still around 50 fields including the description, the listing thumbnail (a search result carries one photo, not the gallery), price, size, rooms, floor, coordinates and the advertiser's contact block, at one request per PAGE of 30 instead of one per listing. Much faster on large searches, and lighter on Idealista. Holiday rentals ignore this setting — Idealista publishes no detail page for them, so they are always delivered as search rows.

## `monitoringMode` (type: `boolean`):

If checked, it will only scrape newly listings compared to what has been scraped in previous runs.

## `detectPriceChanges` (type: `boolean`):

Requires "monitoring mode". Across runs, tracks each listing's price and reports every change — one row per price move with <code>oldPrice</code>, <code>newPrice</code>, <code>priceDelta</code>, <code>pctChange</code>, <code>direction</code> (increase/decrease) and <code>firstSeenAt</code>, plus the listing's URL & address. Price-change rows are written to a separate run dataset named <code>idealista-changes-\<runId></code> (not the default output) and billed at the low <code>additional-data</code> rate. Perfect for spotting price drops on properties you're tracking. No effect unless monitoring mode is also on.

## `detectRemovedListings` (type: `boolean`):

Requires "monitoring mode". Reports listings that have LEFT the market (sold/withdrawn) since your previous run — one <code>{ "status": "removed", propertyCode, url, searchUrl, detectedRemovedAt }</code> row each, written to a separate run dataset named <code>idealista-removed-\<runId></code> and billed at the low <code>additional-data</code> rate. <b>Needs a full scan:</b> set <code>maxItems</code> high enough to cover the whole search — runs that stop early are skipped so nothing is wrongly flagged as removed. No effect unless monitoring mode is also on.

## `indexMode` (type: `boolean`):

Lightweight monitoring for customers who already store the full data: scans your search results and emits ONLY slim event rows to the default dataset — <code>status: "new"</code> (propertyCode, price, url), <code>status: "price_changed"</code> (oldPrice, newPrice, delta, %), and <code>status: "removed"</code> at the end of a full scan. No property details are fetched or charged. Billing: the standard per-result price per event row + a small scan fee of $0.10 per 1,000 listings scanned (billed as <code>additional-data</code> events, 1 per 10 listings, until the dedicated <code>index-scan</code> event activates on Sep 10, 2026). To get full details for new listings, run the actor again with their property URLs as Start URLs (without this toggle). Keep <code>splitByPrice</code> on so searches over 1,500 results enumerate fully — removed-detection skips truncated searches. Regular search URLs only (drawn-area/shape URLs are skipped). Paid plans only.

## `seedBaseline` (type: `boolean`):

Only with <code>indexMode</code>: record the current state of your searches WITHOUT emitting NEW rows — use it on your very first index run when your own database already contains the listings, so you don't pay for thousands of <code>status: "new"</code> rows you already have. Turn it off for all subsequent runs.

## `splitByPrice` (type: `boolean`):

Idealista silently caps each search query at 1500 listings — confirmed against the iOS app itself; the limit lives on the API, not on the website. With this enabled (the default), the actor probes each start URL and, when the total would exceed 1500, automatically captures the complete result set past the cap and merges it into one dataset. Searches with under 1500 hits run as-is (one extra probe request). Turn this OFF if you want the legacy behavior — a single query that stops at the cap.

## `sellerType` (type: `string`):

Who may advertise the listings you get back. Idealista's website has an <b>only private owners</b> filter, and its URLs carry it (<code>de_particulares</code>, <code>da_privati</code>, <code>de-particuliers</code>) — but its API accepts that filter and then ignores it, so until now such a URL still returned agencies, and you paid for them. Measured on one A Coruña search: 29 of the 30 listings on the page were agencies or developers and one was an owner. Left on <b>Follow the start URL</b>, a URL carrying the token now returns owners only, and everything else is unaffected. Choose <b>Private owners only</b> to apply it to a search built from the fields above, which has no URL to carry the token. Choose <b>Everyone</b> to keep agency listings even on a URL that asks for owners. Listings are dropped before their details are fetched, so what you do not receive you do not pay for, and a listing whose seller Idealista does not name is always kept.

## `scrapeAgencies` (type: `boolean`):

When enabled, the actor returns one row per unique real-estate AGENCY found across your search URLs — agency name, <b>phone number</b>, profile URL, microsite, and logo — instead of property listings. Phone numbers are included on every agency row (most agency scrapers leave phone empty). Works with any normal search/result URL (e.g. /venta-viviendas/madrid-madrid/) and respects the 1500-cap bypass for full coverage. Email is not published by Idealista, so it is not included.

## `enrichEmails` (type: `boolean`):

If enabled, finds a contact email for each result from its own website (or by discovering it from the name). Adds contactEmail + contactWebsite columns plus a detailed emailEnrichment object. Billed per contact email found; only charged when an email is returned, never for misses.

## `qualifyByPayment` (type: `boolean`):

Requires "Enrich with contact emails". Scans each listing agent/business website — reusing the pages already fetched for email discovery, so no extra cost or time — for payment processors and e-commerce platforms (Stripe, Shopify, PayPal, Paddle, Lemon Squeezy, WooCommerce, Square, Chargebee and more). Adds takesPayments (is this a real paying business?), paymentProcessors (which stack), stripeLiveKey (the public key if exposed) and paymentConfidence. Turn raw contacts into monetization-qualified leads. No extra charge — included with each enriched company.

## `marketAnalysis` (type: `boolean`):

If enabled, appends a `rowType: "marketAnalysis"` row per area found in your results (up to 8 areas per run, largest first). Billed per area row delivered via the `market-analysis` event; never charged when analysis fails or signal is too thin.

## `maxConcurrency` (type: `integer`):

Maximum number of pages that can be processed at the same time.

## `minConcurrency` (type: `integer`):

Kept for saved tasks that still set it. The scraper's request engine runs a fixed sliding window up to Max Concurrency and has no lower bound to raise, so this value changes nothing. Use Max Concurrency to control speed.

## `maxRequestRetries` (type: `integer`):

Kept for saved tasks that still set it. Retries are no longer a single number: search pages get 30 parallel bursts and each listing gets 5 attempts, both tuned against Idealista's own rate limits, so a value here would either waste proxy bandwidth or cut a page short. Nothing to set.

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

Leave empty — the actor already routes all traffic through its own built-in residential proxy at no extra cost to you. Only set this if you want to use your own proxies.

## Actor input object example

```json
{
  "instantDatabase": false,
  "dbHasPhone": false,
  "country": "es",
  "operation": "sale",
  "language": "en",
  "rentalType": "any",
  "propertyType": "homes",
  "location": "Marbella",
  "scrapeWholeCountry": false,
  "postalCodes": [],
  "preservation": "",
  "newDevelopment": false,
  "airConditioning": false,
  "elevator": false,
  "garage": false,
  "garden": false,
  "terrace": false,
  "swimmingPool": false,
  "exterior": false,
  "storeRoom": false,
  "builtInWardrobes": false,
  "luxury": false,
  "balcony": false,
  "accessible": false,
  "virtualTour": false,
  "furnishedKitchen": false,
  "furnished": false,
  "exteriorDomesticSpace": false,
  "hasPlan": false,
  "petsAllowed": false,
  "onlyFlats": false,
  "energyEfficiency": "",
  "auction": "",
  "agencies": [],
  "bankOffer": false,
  "seaViews": false,
  "publicationDate": "",
  "sortBy": "",
  "sortDirection": "desc",
  "maxItems": 10000,
  "maxPages": 0,
  "notificationLimit": 10,
  "compact": false,
  "excludeEmptyFields": false,
  "descriptionMaxLength": 0,
  "descriptionFormat": "original",
  "imageSize": "original",
  "fetchStats": false,
  "fetchDetails": true,
  "monitoringMode": false,
  "detectPriceChanges": false,
  "detectRemovedListings": false,
  "indexMode": false,
  "seedBaseline": false,
  "splitByPrice": true,
  "sellerType": "auto",
  "scrapeAgencies": false,
  "enrichEmails": false,
  "qualifyByPayment": false,
  "marketAnalysis": false,
  "maxConcurrency": 10,
  "minConcurrency": 1,
  "maxRequestRetries": 100
}
```

# Actor output Schema

## `results` (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 = {
    "postalCodes": [],
    "agencies": []
};

// Run the Actor and wait for it to finish
const run = await client.actor("memo23/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 = {
    "postalCodes": [],
    "agencies": [],
}

# Run the Actor and wait for it to finish
run = client.actor("memo23/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 '{
  "postalCodes": [],
  "agencies": []
}' |
apify call memo23/idealista-scraper --silent --output-dataset

```

## MCP server setup

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