# Idealista Property Listings Scraper | Sale & Rent (`datascraperes/idealista-property-search-scraper`) Actor

Extract unique Idealista property listings across Spain, Portugal, Italy and France. Search sale or rent by location, filter by property type, price and bedrooms, and export structured listings with public property details and multimedia metadata.

- **URL**: https://apify.com/datascraperes/idealista-property-search-scraper.md
- **Developed by:** [DataScraperES](https://apify.com/datascraperes) (community)
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $1.13 / 1,000 unique idealista listings

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

Search and export unique Idealista property listings across Spain, Portugal, Italy and France. Every saved listing includes normalized property data plus the public detail and multimedia information available for that listing.

### What this Actor does

This Actor searches Idealista by country, location, sale or rent, property category and optional price or bedroom filters. It resolves each location before searching, removes duplicates across locations, and writes one structured Dataset item per unique listing. The public output uses one consistent mode: **Full + multimedia**.

Each item combines stable identifiers, listing URLs, title, price, location, coordinates, property characteristics, description, energy information, advertiser data when available, and multimedia metadata. Public source payloads are retained under `sourceData` so an integration can inspect the search, detail and multimedia portions used to build the normalized record.

### Use cases

- Build a property inventory for a city, province or complete market.
- Compare sale and rental supply across several locations.
- Enrich a real-estate, market-research or lead-analysis workflow with structured listing data.
- Keep image, video and tour references together with the corresponding property record.

### How to use

1. Open the Actor in Apify Console.
2. Select the country, operation and property category, then enter one or more locations.
3. Add optional price or bedroom filters and choose the maximum number of unique listings.
4. Start the run and open the default Dataset or the `propertyListings` output.

Example input for a small search:

```json
{
  "country": "es",
  "locations": ["Madrid", "Málaga"],
  "operation": "sale",
  "propertyType": "homes",
  "maxItems": 30
}
```

### Input

`locations` is the only required field. It accepts up to 20 place names and the names are resolved against Idealista's own location suggestions. `country` accepts `es`, `pt`, `it` or `fr`. `operation` accepts `sale` or `rent`. `propertyType` accepts `homes`, `offices`, `premises`, `garages`, `bedrooms`, `storageRooms`, `lands`, `buildings` or `newDevelopments`.

`minPrice`, `maxPrice` and `bedrooms` are optional filters. `maxItems` controls the complete run and accepts 30–5,000 unique listings. Request pacing and temporary recovery are managed automatically by the Actor.

```json
{
  "country": "es",
  "locations": ["Madrid", "Málaga"],
  "operation": "sale",
  "propertyType": "homes",
  "minPrice": 100000,
  "maxPrice": 300000,
  "bedrooms": 2,
  "maxItems": 30
}
```

### Output

The default Dataset contains one item per unique listing. The `propertyListings` output opens the Dataset view and `summary` contains the customer-facing completion status, listing counts, requested locations and enrichment coverage. A run can return fewer items when a location has fewer available listings or a listing cannot provide all optional fields; missing values remain `null`.

The Full + multimedia mode requests and merges the public detail and dedicated multimedia responses for each delivered listing. `multimedia` contains media metadata and source URLs when available; it does not package image or video files. `sourceData` groups the public source payloads under `search`, `detail` and `multimedia`.

The following complete item shows the current Dataset contract. Contact details are shortened in this documentation example.

```json
{
  "propertyCode": 112511261,
  "url": "https://www.idealista.com/inmueble/112511261/",
  "title": "Piso en venta en Calle Monte Miramar, 56",
  "country": "es",
  "operation": "sale",
  "propertyType": "homes",
  "locationId": "0-EU-ES-29-02-001-067-02-002",
  "extendedPropertyType": "flat",
  "homeType": "flat",
  "typology": "flat",
  "price": 850000.0,
  "priceInfo": {"amount": 850000.0, "currencySuffix": "€"},
  "priceByArea": 8416.0,
  "priceDropValue": null,
  "priceDropPercentage": null,
  "priceDropInfo": null,
  "address": "Piso en Calle Monte Miramar, 56, Limonar, Málaga",
  "municipality": "Málaga",
  "province": "Comarca de Málaga, Málaga",
  "district": "Distrito Este",
  "neighborhood": "Barrio Limonar",
  "latitude": 36.7284362,
  "longitude": -4.3959891,
  "size": 101.0,
  "usableArea": null,
  "rooms": 2.0,
  "bedrooms": null,
  "bathrooms": 2.0,
  "floor": "1",
  "exterior": true,
  "hasLift": true,
  "hasParking": true,
  "hasVideo": true,
  "has360": false,
  "has3DTour": false,
  "newDevelopment": true,
  "newProperty": false,
  "status": "active",
  "description": "Public property description returned by Idealista.",
  "externalReference": "Primera 2",
  "thumbnail": "https://img4.idealista.com/example-thumbnail.jpg",
  "numPhotos": 13.0,
  "features": {
    "hasSwimmingPool": false,
    "hasTerrace": true,
    "hasAirConditioning": true,
    "hasBoxRoom": true,
    "hasGarden": false
  },
  "labels": [],
  "contactInfo": {
    "commercialName": "Advertiser name when supplied",
    "userType": "professional"
  },
  "energyCertification": {
    "title": "Certificado energético del proyecto",
    "energyConsumption": {"prefix": "Consumo:", "type": "a"},
    "emissions": {"prefix": "Emisiones:", "type": "a"}
  },
  "multimedia": {
    "images": [{"url": "https://img4.idealista.com/example-image.jpg", "tag": "livingRoom"}],
    "videos": [],
    "hasMultimediasMadeByIdealista": false
  },
  "detailStatus": "fetched",
  "sourceData": {
    "search": {"propertyCode": 112511261},
    "detail": {"detailWebLink": "https://www.idealista.com/inmueble/112511261/"},
    "multimedia": {"images": [{"url": "https://img4.idealista.com/example-image.jpg"}], "videos": []}
  },
  "modificationDate": "Anuncio actualizado recientemente",
  "searchLocation": "Málaga, Málaga",
  "scrapedAt": "2026-09-29T09:09:10Z"
}
```

### Pricing

The Actor uses one `result` event. One event represents one unique listing saved to the default Dataset. Failed, duplicate and undelivered listings are not charged. Apify resolves the applicable customer tier from the configured tiered event prices.

| Apify tier | Price per listing | Equivalent per 1,000 listings |
|---|---:|---:|
| FREE | $0.001500 | $1.50 |
| BRONZE | $0.001350 | $1.35 |
| SILVER | $0.001200 | $1.20 |
| GOLD | $0.001125 | $1.125 |
| PLATINUM | $0.001125 | $1.125 |
| DIAMOND | $0.001125 | $1.125 |

### Related Actors

| Actor | Best for |
|---|---|
| [Fotocasa Spain Property Listings Scraper](https://apify.com/datascraperes/fotocasa-property-search-scraper) | Comparing Spanish property supply from Fotocasa. |
| [Realtor.com US Property Listings Scraper](https://apify.com/datascraperes/realtor-property-search) | Collecting comparable property listings in the United States. |

### Limits and data quality

Coverage is limited to the four supported markets and the public listings available when the run starts. A location must resolve to an Idealista suggestion. Advertiser fields, coordinates, descriptions, media, price-change information and energy data vary by listing. The Actor preserves the available values and returns `null` when a field is absent.

Results are deduplicated across all requested locations and the `maxItems` limit applies to the complete run. Pagination stops when the source is exhausted or the requested unique count is reached. The run summary distinguishes completed, partial and failed work, while `detailStatus` identifies whether the public detail data was fetched, unavailable or not present.

### Frequently asked questions

#### Can I search several cities in one run?

Yes. Enter up to 20 locations. The maximum number of unique listings applies to the complete run, not separately to each location.

#### What does Full + multimedia include?

It includes the normalized listing, public detail fields, advertiser data when available, multimedia metadata and the corresponding public source payload groups. Image and video URLs are returned as references; media files are not downloaded into the Dataset.

#### Are photos, videos or tours guaranteed for every listing?

No. Their presence depends on the individual public listing. A listing without a particular media type is still returned with the relevant field empty or `null`.

#### What happens when optional listing data is missing?

The listing remains usable. Missing optional values are represented as `null`, and the summary records the final run status and enrichment counts.

### Responsible use

You are responsible for using the results lawfully and for complying with applicable terms of service, privacy rules, intellectual-property rights and other regulations. Use the data only for purposes permitted in your jurisdiction and respect any restrictions that apply to the source or the people represented in the data.

### Support

For help, open an issue in the Actor's **Issues** tab and include a reproducible input, the run ID and the relevant summary message. Do not include private credentials or sensitive personal data in the issue.

[Public integration examples on GitHub](https://github.com/datacrawler-edu/idealista-property-scraper-python)

# Actor input Schema

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

Idealista market to search: Spain (es), Portugal (pt), Italy (it) or France (fr).

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

One or more places to search, written as text (for example Madrid, Málaga, Lisboa, Milano, Paris). Each place is resolved against Idealista's own location suggestions before searching.

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

Search properties for sale or for rent.

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

Idealista property category to search.

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

Optional minimum advertised price in euros.

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

Optional maximum advertised price in euros.

## `bedrooms` (type: `integer`):

Optional minimum number of bedrooms. Use 0 for studios when the source supports it.

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

Maximum number of unique listings to save in the Dataset across all locations.

## Actor input object example

```json
{
  "country": "es",
  "locations": [
    "Madrid"
  ],
  "operation": "sale",
  "propertyType": "homes",
  "maxPrice": 300000,
  "maxItems": 30
}
```

# Actor output Schema

## `propertyListings` (type: `string`):

The complete, deduplicated set of property listings produced by this run, displayed with the Property listings dataset view.

## `summary` (type: `string`):

Customer-facing completion status, listing counts, requested locations and enrichment coverage.

# 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 = {
    "country": "es",
    "locations": [
        "Madrid"
    ],
    "operation": "sale",
    "propertyType": "homes",
    "maxPrice": 300000,
    "maxItems": 30
};

// Run the Actor and wait for it to finish
const run = await client.actor("datascraperes/idealista-property-search-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 = {
    "country": "es",
    "locations": ["Madrid"],
    "operation": "sale",
    "propertyType": "homes",
    "maxPrice": 300000,
    "maxItems": 30,
}

# Run the Actor and wait for it to finish
run = client.actor("datascraperes/idealista-property-search-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 '{
  "country": "es",
  "locations": [
    "Madrid"
  ],
  "operation": "sale",
  "propertyType": "homes",
  "maxPrice": 300000,
  "maxItems": 30
}' |
apify call datascraperes/idealista-property-search-scraper --silent --output-dataset

```

## MCP server setup

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