# 🏠 Idealista Scraper (`scraper-engine/idealista-scraper`) Actor

🏠 Idealista Scraper (idealista-scraper) extracts listings & key property details from Idealista—price, location, size, features & more. 🚀 Fast, reliable data for real estate analytics, lead gen, and market research.

- **URL**: https://apify.com/scraper-engine/idealista-scraper.md
- **Developed by:** [Scraper Engine](https://apify.com/scraper-engine) (community)
- **Categories:** Real estate, Lead generation, Developer tools
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $4.99 / 1,000 results

This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage.

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

## What's an Apify Actor?

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

## How to integrate an Actor?

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

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

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

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

# README

## 🏠 Idealista Scraper — Spain · Portugal · Italy Real Estate

Extract **real-estate listings from [Idealista](https://www.idealista.com)** at scale —
properties **for sale or rent** across **🇪🇸 Spain, 🇵🇹 Portugal and 🇮🇹 Italy**. Search by
location, paste listing URLs or property codes, apply rich filters, and get clean,
structured JSON with prices, sizes, photos, geolocation, agent contacts and (optionally)
full property details and engagement statistics.

This Actor talks to Idealista's official **mobile-app API**, so results are fast, complete
and consistently structured — and a **smart auto-escalating proxy** keeps it running even
when requests get blocked.

### ⭐ Why choose this Actor?

- **Fast & reliable** — direct mobile-API access, not fragile HTML scraping.
- **Self-healing proxies** — starts with no proxy, automatically escalates to datacenter
  and then residential proxies on blocks, then sticks with what works.
- **Live results** — every property is saved the moment it's ready; a crash never loses
  finished work.
- **Deeply structured output** — search fields + optional `_details` and `_stats`.
- **Bulk-friendly** — paste many listing URLs / property codes, or search whole cities.

### 🔑 Key features

- Sale & rent, 9 property types (homes, new developments, offices, garages, lands…).
- 40+ filters: price, size, bedrooms, bathrooms, condition, floor, amenities, agency…
- Automatic sub-location splitting to exceed the per-search pagination cap.
- Optional per-property enrichment (`_details`, `_stats`).
- Real-time, emoji-rich logs and a tabbed Output view (Overview · Location · Features · Contact).

### 📥 Input

```json
{
  "location": "0-EU-ES-28-07-001-079",
  "country": "es",
  "operation": "sale",
  "propertyType": "homes",
  "maxItems": 50,
  "sortBy": "mostRecent",
  "fetchDetails": true,
  "fetchStats": true,
  "proxyConfiguration": { "useApifyProxy": false }
}
```

| Field | Meaning |
|---|---|
| `startUrls` | Bulk Idealista listing URLs; property codes are auto-extracted. |
| `propertyCodes` | Idealista property codes to fetch directly (skips search & filters). |
| `location` | City name (e.g. `Madrid`) or Idealista Location ID. |
| `country` | `es` · `pt` · `it`. |
| `operation` | `sale` or `rent`. |
| `propertyType` | `homes`, `newDevelopments`, `offices`, `premises`, `garages`, `lands`, `storageRooms`, `buildings`, `bedrooms`. |
| `maxItems` | Max listings (0 = unlimited; >2500 auto-splits by sub-location). |
| `sortBy` | Result ordering (most recent, lowest price, biggest…). |
| `fetchDetails` / `fetchStats` | Add `_details` / `_stats` per property (slower). |
| Price/size/filters/amenities | See the input form — all optional. |
| `proxyConfiguration` | Proxy. Default: no proxy with auto-escalation. |

### 📤 Output

Each dataset item is a full Idealista listing. With enrichment on, it also carries
`_details` (full description, all photos, characteristics, agent info) and `_stats`
(views, favourites, contacts):

```json
{
  "propertyCode": "111666344",
  "operation": "sale",
  "propertyType": "flat",
  "price": 700000,
  "priceByArea": 5645,
  "size": 124,
  "rooms": 4,
  "bathrooms": 2,
  "status": "good",
  "address": "Piso en Calle de Fermín Caballero, 85, Peñagrande, Madrid",
  "province": "Madrid",
  "municipality": "Madrid",
  "district": "Fuencarral",
  "neighborhood": "Peñagrande",
  "latitude": 40.4794993,
  "longitude": -3.7182544,
  "thumbnail": "https://img4.idealista.com/...",
  "url": "https://www.idealista.com/inmueble/111666344/",
  "_details": { "...": "full property detail" },
  "_stats":   { "views": { "value": 0 }, "favorites": { "value": 0 } }
}
```

### 🚀 How to use the Actor (via Apify Console)

1. Log in at <https://console.apify.com> → **Actors**.
2. Open **Idealista Scraper**.
3. Set a **location** (or paste URLs / property codes) and tune filters.
4. (Optional) Enable **Fetch details / stats** for richer data.
5. Click **Start** and watch the real-time logs.
6. Open the **Output** tab — switch between **Overview · Location · Features · Contact** views.
7. Export to **JSON / CSV / Excel** or pull via the **API**.

### 🏙️ Best use cases

- Market analysis & price benchmarking by area.
- Lead generation for agencies and investors.
- Building property datasets for ML / dashboards.
- Monitoring new listings with `publicationDate` filters.

### 💸 Pricing

This Actor uses **pay-per-event** pricing: a small charge when the run starts plus a small
charge per property saved. You only pay for results you receive.

### ❓ FAQ

**Where do I find a Location ID?** Use the
[Idealista Location Search tool](https://igolaizola.github.io/idealista-scraper), or just
type a city name and the Actor resolves it.

**Why enrichment is slower?** `_details`/`_stats` each add one request per property
(~50× more requests), so enable them only when you need that depth.

**Do I need a proxy?** No. The Actor starts without one and escalates automatically only if
Idealista blocks the request.

### ⚖️ Legal & ethics

Only public listing data is collected. You are responsible for complying with applicable
laws and Idealista's Terms of Service in your jurisdiction.

### 🛟 Support

Found a bug or need a new field? Open an issue on the Actor's **Issues** tab in the Apify
Console.

# Actor input Schema

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

City name (e.g. Madrid) or an Idealista Location ID (e.g. 0-EU-ES-28-07-001-079). Tip: use the Idealista Location Search tool (https://igolaizola.github.io/idealista-scraper) to find an exact Location ID.

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

Which Idealista marketplace to search.

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

Buy or rent.

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

Type of property to search.

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

Maximum number of listings to scrape (0 = unlimited). Above 2500 the location is auto-split into sub-locations, which groups results by sub-location.

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

Ordering of the search results.

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

Add a rich '\_details' object to every property (full description, all photos, characteristics, agent info…). Roughly 50× slower because each property needs its own request.

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

Add a '\_stats' object to every property (views, favourites, e-mail contacts, sent-to-friend). Roughly 50× slower.

## `minPrice` (type: `string`):

Minimum price (0 = any).

## `maxPrice` (type: `string`):

Maximum price (0 = any).

## `minSize` (type: `string`):

Minimum size in m² (0 = any).

## `maxSize` (type: `string`):

Maximum size in m² (0 = any).

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

Only listings published within this window.

## `rentalTypes` (type: `array`):

Rental usage type. Leave empty for any.

## `bedrooms` (type: `array`):

Number of bedrooms. Leave empty for any.

## `bathrooms` (type: `array`):

Number of bathrooms. Leave empty for any.

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

Home typologies. Leave empty for any.

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

Property condition. Leave empty for any.

## `propertyStatus` (type: `array`):

Ownership / occupancy status. Leave empty for any.

## `floor` (type: `array`):

Floor level. Leave empty for any.

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

Only properties with air conditioning.

## `fittedWardrobes` (type: `boolean`):

Only properties with fitted wardrobes.

## `lift` (type: `boolean`):

Only properties with a lift.

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

Only properties with a balcony.

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

Only properties with a terrace.

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

Only exterior properties.

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

Only properties with garage or parking.

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

Only properties with a garden.

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

Only properties with a swimming pool.

## `storageRoom` (type: `boolean`):

Only properties with a storage room.

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

Only accessible properties.

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

Only properties with sea views.

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

Only luxury homes.

## `plan` (type: `boolean`):

Only properties with a floor plan.

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

Only properties with a virtual tour.

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

Filter by agency using the slug from its page URL, e.g. 'engel-volkers' from https://www.idealista.com/pro/engel-volkers/.

## `proxyConfiguration` (type: `object`):

Proxy settings. By default the actor starts with NO proxy and automatically escalates to a datacenter proxy and then a residential proxy if Idealista blocks the request (and sticks with residential afterwards). You can still force a specific Apify proxy group here.

## Actor input object example

```json
{
  "location": "0-EU-ES-28-07-001-079",
  "country": "es",
  "operation": "sale",
  "propertyType": "homes",
  "maxItems": 10,
  "sortBy": "mostRecent",
  "fetchDetails": false,
  "fetchStats": false,
  "minPrice": "0",
  "maxPrice": "0",
  "minSize": "0",
  "maxSize": "0",
  "publicationDate": "",
  "airConditioning": false,
  "fittedWardrobes": false,
  "lift": false,
  "balcony": false,
  "terrace": false,
  "exterior": false,
  "garage": false,
  "garden": false,
  "swimmingPool": false,
  "storageRoom": false,
  "accessible": false,
  "seaViews": false,
  "luxury": false,
  "plan": false,
  "virtualTour": false,
  "agency": "",
  "proxyConfiguration": {
    "useApifyProxy": false
  }
}
```

# 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 = {
    "location": "0-EU-ES-28-07-001-079",
    "proxyConfiguration": {
        "useApifyProxy": false
    }
};

// Run the Actor and wait for it to finish
const run = await client.actor("scraper-engine/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 = {
    "location": "0-EU-ES-28-07-001-079",
    "proxyConfiguration": { "useApifyProxy": False },
}

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

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

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

```

## CLI example

```bash
echo '{
  "location": "0-EU-ES-28-07-001-079",
  "proxyConfiguration": {
    "useApifyProxy": false
  }
}' |
apify call scraper-engine/idealista-scraper --silent --output-dataset

```

## MCP server setup

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

```

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/acts/IkMX8teunpbquXdqk/builds/McNSdKNNSDpCbS3w1/openapi.json