# Idealista Market Intel Scraper (`fetch_cat/idealista-scraper`) Actor

Extract public Idealista property listings and normalized market intelligence for Spain, Portugal, and Italy.

- **URL**: https://apify.com/fetch\_cat/idealista-scraper.md
- **Developed by:** [Hanna Nosova](https://apify.com/fetch_cat) (community)
- **Categories:** Real estate, Lead generation
- **Stats:** 2 total users, 1 monthly users, 94.7% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.39 / 1,000 item processeds

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 Market Intel Scraper

This Idealista scraper turns public search and property pages into analysis-ready Idealista data for Spain, Portugal, and Italy. Use it to monitor asking prices, compare price per square metre, build listing inventories, or access structured results as an Idealista API workflow.

### What it extracts

Each unique property record includes its stable Idealista ID, canonical URL, country, operation, property type, title, price and currency. When publicly available, records also include:

- price per square metre, size, rooms, bathrooms, floor, and condition
- address, municipality, province, latitude, and longitude
- lift, parking, terrace, and swimming-pool flags
- description, images, video, virtual tour, and energy ratings
- agency/contact details and publication timestamps
- source input URL, extraction mode, and fetch timestamp

Missing upstream values remain absent; the Actor does not invent market estimates or unavailable attributes.

#### Output fields

| Group | Dataset fields |
|---|---|
| Identity | `id`, `url`, `country`, `operation`, `propertyType`, `title` |
| Pricing and layout | `price`, `currency`, `pricePerSquareMeter`, `size`, `rooms`, `bathrooms`, `floor`, `condition` |
| Location | `address`, `locationName`, `municipality`, `province`, `latitude`, `longitude` |
| Features | `hasLift`, `hasParking`, `hasTerrace`, `hasSwimmingPool` |
| Content and media | `description`, `images`, `videoUrl`, `virtualTourUrl`, `energyConsumption`, `energyEmissions` |
| Contact and timing | `contactName`, `agencyName`, `phone`, `publishedAt`, `updatedAt` |
| Provenance | `source` (platform, input URL, fetch time, and search/detail mode) |

### Input

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

- `startUrls` (required): public HTTPS Idealista search or property URLs on `idealista.com`, `idealista.pt`, or `idealista.it`.
- `maxItems`: global maximum number of unique records saved (1–10,000; default 10).
- `fetchDetails`: enrich search results from their public detail endpoint (default `true`). Disable it for a faster search-inventory pass.

Multiple inputs are deduplicated by stable property ID. Only successfully persisted dataset items are charged as item events.

### Ready-to-run examples

Open a public example to inspect its input, run it, or reuse it as a task:

- [Export Madrid homes for sale data](https://apify.com/fetch_cat/idealista-scraper/examples/export-madrid-homes-for-sale)

**Fast Madrid sale inventory**

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

**One property with all available public detail fields**

```json
{
  "startUrls": [{ "url": "https://www.idealista.com/inmueble/109592362/" }],
  "maxItems": 1,
  "fetchDetails": true
}
```

### Output example

```json
{
  "id": "82100417",
  "url": "https://www.idealista.com/inmueble/82100417/",
  "country": "ES",
  "operation": "rent",
  "propertyType": "flat",
  "title": "Flat in Calle Everluz",
  "price": 500,
  "currency": "EUR",
  "size": 60,
  "rooms": 1,
  "bathrooms": 1,
  "municipality": "Punta Umbria",
  "province": "Huelva",
  "source": {
    "inputUrl": "https://www.idealista.com/venta-viviendas/madrid-madrid/",
    "mode": "search",
    "fetchedAt": "2026-08-30T00:00:00.000Z"
  }
}
```

Results are available in the default dataset as JSON, CSV, Excel, XML, or RSS.

### API usage, SDK, and MCP

Run the Actor from Apify Console, schedule it as a Task, invoke it through the Apify API, or call it with `apify-client` from JavaScript or Python.

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

const client = new ApifyClient({ token: process.env.APIFY_TOKEN });
const run = await client.actor('fetch_cat/idealista-scraper').call({
  startUrls: [{ url: 'https://www.idealista.com/venta-viviendas/madrid-madrid/' }],
  maxItems: 25,
  fetchDetails: true,
});
const { items } = await client.dataset(run.defaultDatasetId).listItems();
```

```python
import os
from apify_client import ApifyClient

client = ApifyClient(os.environ['APIFY_TOKEN'])
run = client.actor('fetch_cat/idealista-scraper').call(run_input={
    'startUrls': [{'url': 'https://www.idealista.com/venta-viviendas/madrid-madrid/'}],
    'maxItems': 25,
    'fetchDetails': True,
})
items = client.dataset(run['defaultDatasetId']).list_items().items
```

```bash
curl -X POST 'https://api.apify.com/v2/acts/fetch_cat~idealista-scraper/runs?token=YOUR_APIFY_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"startUrls":[{"url":"https://www.idealista.com/venta-viviendas/madrid-madrid/"}],"maxItems":25,"fetchDetails":true}'
```

For MCP-compatible assistants, connect to `https://mcp.apify.com/?tools=fetch_cat/idealista-scraper` and pass the same input object. Webhooks can send completed-run data into databases, spreadsheets, n8n, Make, or custom services.

### Pricing and limits

The Actor uses pay-per-event pricing: one run-start event and one item event for each successfully saved property. See the live [Apify Pricing tab](https://apify.com/fetch_cat/idealista-scraper/pricing) for current rates and plan-specific discounts.

`maxItems` is a global cap after deduplication. Search pages can change between runs, detail fields vary by country and listing, and removed properties may stop returning data. Detail enrichment makes additional requests and therefore runs more slowly than search-only inventory. The Actor does not bypass login-only access or return private seller information.

### Who is it for?

This Actor is designed for property analysts, real-estate teams, investors, researchers, and automation builders who need repeatable public listing exports without manual copying.

### Practical use cases

- Track fresh sale or rental inventory in a target market.
- Compare asking price per square metre across municipalities.
- Monitor individual properties by their detail URLs.
- Feed public listing data into BI, valuation, or lead-qualification workflows.
- Detect listing changes by scheduling repeat runs and joining on `id`.

### FAQ

#### Does it require an Idealista login?

No. It accepts only supported public, no-login URLs.

#### Is this an official Idealista API?

No. This independent Actor extracts publicly observable listing data and may need maintenance when Idealista changes its public interfaces.

#### Does `maxItems` apply per URL?

No. It is a global cap across all inputs after deduplication.

#### Why are some fields missing?

Availability varies by listing and country. Unsupported or hidden claims are omitted rather than guessed.

#### Can I use an Idealista scraper through an API or MCP?

Yes. The Actor input and dataset output work through Apify API clients and Apify's MCP integration.

#### How can I export Idealista listings to CSV or Excel?

Run the Actor, open its default dataset, and choose CSV or Excel from the export formats. The same records are also available as JSON, XML, and RSS.

#### How do I monitor Idealista property prices over time?

Save a bounded search input as an Apify Task, schedule repeat runs, and join snapshots by stable `id`. Compare `price`, `pricePerSquareMeter`, and `updatedAt` across runs.

#### What are the responsible-use limits?

Use public data lawfully, respect applicable terms and privacy rules, avoid unnecessary collection, and choose a bounded `maxItems`. Website rate limits or interface changes can affect runs.

### Related Actors

- [Leboncoin Listings Scraper](https://apify.com/fetch_cat/leboncoin-listings-scraper)
- [Marktplaats Listings Scraper](https://apify.com/fetch_cat/marktplaats-listings-scraper)
- [Apple Maps Places Scraper](https://apify.com/fetch_cat/apple-maps-places-scraper)
- [Google Maps Photos Scraper](https://apify.com/fetch_cat/google-maps-photos-scraper)
- [Google Images Scraper](https://apify.com/fetch_cat/google-images-scraper)

### Support

For questions, reproducible failures, or field requests, open an issue from the Actor's Apify Store page. Include the public input URL, run ID, expected behavior, and a short description; do not post passwords, cookies, or personal login data.

# Changelog

This Actor's version history is a separate document: https://apify.com/fetch\_cat/idealista-scraper/changelog.md

# Actor input Schema

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

Public idealista.com, idealista.pt, or idealista.it search and property URLs.

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

Global maximum number of unique property listings persisted across all URLs.

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

Make an additional public detail request per search result for descriptions, media, contacts, and energy fields.

## Actor input object example

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

# Actor output Schema

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

No description

# API

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

## JavaScript example

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

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

// Prepare Actor input
const input = {
    "startUrls": [
        {
            "url": "https://www.idealista.com/venta-viviendas/madrid-madrid/"
        }
    ]
};

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

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

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

```

## Python example

```python
from apify_client import ApifyClient

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

# Prepare the Actor input
run_input = { "startUrls": [{ "url": "https://www.idealista.com/venta-viviendas/madrid-madrid/" }] }

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

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

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

```

## CLI example

```bash
echo '{
  "startUrls": [
    {
      "url": "https://www.idealista.com/venta-viviendas/madrid-madrid/"
    }
  ]
}' |
apify call fetch_cat/idealista-scraper --silent --output-dataset

```

## MCP server setup

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