# Idealista Scraper 💰 $0.60/1K – Spain, Portugal, Italy & France (`lukass/idealista-scraper`) Actor

From $0.60/1K. Scrape Idealista listings in Spain, Portugal, Italy & France: price, €/m², size, rooms, GPS, photos, agent phones, price drops. Sear
ch by city, postal code, radius, agency or any search URL. No 1,500-result cap, no duplicates. Daily monitoring of new listings.

- **URL**: https://apify.com/lukass/idealista-scraper.md
- **Developed by:** [Lukáš Širhal](https://apify.com/lukass) (community)
- **Categories:** Real estate, Agents
- **Features:** Limited permissions
- **Stats:** 787 total users, 14 monthly users, 98.6% runs succeeded, 13 bookmarks
- **User rating**: 1.36 out of 5 stars

## Pricing

from $0.60 / 1,000 listing 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, Portugal, Italy & France

Scrape property listings from **idealista.com, idealista.pt, idealista.it and idealista.fr**: homes, rooms, holiday rentals, offices, shops, garages and land, for sale or rent. Get price, price per m², size, rooms, GPS coordinates, photos, agent phone numbers, price drops and more, as JSON, CSV or Excel. **From $0.60 per 1,000 results**, and you pay only for results.

Idealista has no public API. This Actor uses the same API as the Idealista mobile app, so it is fast and returns structured data, not scraped HTML.

#### What you can do

- **Search any way you like** — by city, district or postal code (several in one run), a radius around a point, one agency's listings, listing IDs, or any Idealista search URL with its filters, including map views and drawn areas.
- **Get every result, not just 1,500** — the Idealista website stops at 1,500 results per search. Big searches are split by price automatically, so you get the whole market with no duplicates.
- **Monitor new listings** — schedule a daily run with `monitoringMode` and get, and pay for, only listings that are new since the last run.
- **Find deals** — each listing includes `priceDown` and `priceDownPercentage`; sort by biggest price drop or by €/m².
- **Generate leads** — agency name, contact name and phone number on every listing that shows one.
- **Filter like on the website** — price, size, bedrooms, bathrooms, home type, condition, floor, energy rating, furnished, auctions, published within, and features such as pool, terrace, lift, sea views or pets allowed.
- **Fetch full details** — with `fetchDetails`, each result also gets its description and energy certificate from the property page.

#### Why this scraper

- **Each property is charged once** — even when it shows up in several searches, price bands or start URLs in the same run.
- **No platform costs** — you pay only per result. `maxItems` caps how much a run can cost.
- **Results in your language** — titles and labels in English, Spanish, Catalan, Portuguese, Italian, French, German or Dutch.

> **Note:** Due to Idealista's privacy policy, exact property locations may be hidden. In those cases the scraper returns the map center coordinates accessible from the property detail.

> **Note:** `description` is returned in the language the advertiser wrote it in (usually Spanish), even though titles and other labels come back in English.

### Pricing

This Actor uses **pay-per-event** billing — you are not charged for Apify platform usage (compute, proxy bandwidth), only for the results you get.

Prices per 1,000 results, by Apify plan:

| Event | Free | Bronze | Silver | Gold+ | When it's charged |
|-------|------|--------|--------|-------|-------------------|
| `list-result` | $1.00 | $0.80 | $0.65 | $0.60 | One per property returned from a search (`district` or a search `startUrl`) with `fetchDetails` disabled |
| `detail-result` | $2.50 | $1.80 | $1.40 | $1.20 | One per property fetched from its detail page — every result when `fetchDetails` is enabled, plus any direct property `startUrl` |

Each property is charged **once**: with `fetchDetails: true` search results are not pushed on their own, so you pay `detail-result` only — never both events for the same property.

Detail results cost more because each one needs its own extra API request through residential proxies, on top of the search request. If you only need the fields listed in the search response (see the note under [Example Result](#example-result)), leave `fetchDetails` off and pay the `list-result` rate.

Use `maxItems` to cap how many results — and therefore how much — a run can produce.

### Input Parameters

| Field            | Type    | Required | Description |
|------------------|---------|----------|-------------|
| `country`        | String  | ✓        | `es` (Spain), `pt` (Portugal), `it` (Italy), `fr` (France). Used with `district`; a `startUrl` always uses the country of its domain. |
| `operation`      | String  | ✓        | `sale` or `rent` |
| `proxy`          | Object  | ✓        | Proxy configuration — **RESIDENTIAL proxies required** |
| `district`       | String  |          | Location name or postal code to search, e.g. `Madrid` or `28013`. Required if no `startUrl`, radius search, `agency` or `propertyIds` provided. |
| `districts`      | Array   |          | More locations or postal codes searched in the same run, e.g. `["Barcelona", "28013"]`. |
| `postalCodes`    | Array   |          | Postal codes searched in the same run, e.g. `["28013", "08001"]` — same as adding them to `districts`. |
| `agency`         | String  |          | Only one agency's listings: its short name or page URL (`https://www.idealista.com/pro/<agency>/`). Agency page URLs also work as a `startUrl`. |
| `propertyIds`    | Array   |          | Listing IDs to fetch directly (billed as `detail-result`), on the `country` site. |
| `propertyType`   | String  |          | `homes` (default), `newDevelopments`, `bedrooms`, `vacationRentals` (rent only), `offices`, `premises`, `transfers`, `garages`, `lands`, `storageRooms`, `buildings` |
| `startUrl`       | Array   |          | List of Idealista property detail or search URLs from any supported domain (`idealista.com`, `.pt`, `.it`, `.fr`), including map-view (`/mapa`) and drawn-area URLs (`/areas/...?shape=...`) |
| `maxItems`       | Integer |          | Maximum number of results for the **whole run** (across all districts, URLs and price bands). Leave empty for all results. |
| `endPage`        | Integer |          | Last search page per search, 50 results per page (default and maximum 50) |
| `splitByPrice`   | Boolean |          | One Idealista search returns at most 2,500 listings. When a search has more, it is split into price bands so you get the full result set. Default `true`. |
| `monitoringMode` | Boolean |          | Return only listings that previous runs with the same search did not return (see [Monitoring](#monitoring-new-listings-only)). Default `false`. |
| `minPrice` / `maxPrice` | Integer |   | Price range in €. |
| `publishedWithin` | String |          | `any` (default), `last24Hours` (rent only), `last48Hours` (sale only), `lastWeek`, `lastMonth` |
| `sortBy`         | String  |          | `weigh` (relevance, default), `price`, `publicationDate`, `modificationDate`, `priceDown`, `ratioeurm2`, `size`, `distance` (radius search only) |
| `sortOrder`      | String  |          | `desc` (default) or `asc` |
| `language`       | String  |          | Language of titles and labels: `en` (default), `es`, `ca`, `pt`, `it`, `fr`, `de`, `nl`. Descriptions stay in the advertiser's language. |
| `latitude` / `longitude` / `radiusKm` | Number | | Radius search around a point instead of a district, e.g. `40.4168`, `-3.7038`, `2`. Default radius 5 km. |
| `fetchDetails`   | Boolean |          | For each search result, also fetch the full property detail page (adds `description`, `energyCertification`, and more accurate `floor`/`hasLift`/location fields). Slower, uses one extra request per property, and bills at the `detail-result` rate (see [Pricing](#pricing)). Default `false`. |
| `minSize`        | String  |          | Minimum property size in m², e.g. `"60"` |
| `maxSize`        | String  |          | Maximum property size in m², e.g. `"200"` |
| `bedrooms`       | Array   |          | e.g. `["studio","1","2","3","4"]` |
| `bathrooms`      | Array   |          | e.g. `["1","2","3"]` |
| `homeType`       | Array   |          | `flat`, `penthouse`, `duplex`, `studio`, `chalet` (houses), `countryHouse`, `apartment`, `villa`, `loft`, `atticStudio`, `casaBaja`. Several values widen the search. `detachedHouse`, `semiDetachedHouse` and `terracedHouse` are searched as `chalet` — Idealista has no separate filter for them. |
| `condition`      | Array   |          | `newDevelopment`, `good`, `renew` |
| `propertyStatus` | Array   |          | `bareOwnership`, `tenanted`, `illegallyOccupied`, `free` |
| `floorHeights`   | Array   |          | `topFloor`, `intermediateFloor`, `groundFloor` |
| `features`       | Array   |          | `airConditioning`, `builtinWardrobes`, `elevator`, `exteriorDomesticSpace`, `balcony`, `terrance`, `exterior`, `garage`, `garden`, `swimmingPool`, `storeRoom`, `accessible`, `luxury`, `seaViews`, `bankOffer` (bank-owned), `virtualTour`, `hasPlan` (floor plan), `petsAllowed` (rent only) |
| `energyRating`   | String  |          | `any` (default), `high`, `medium`, `low` |
| `furnished`      | String  |          | Rent only: `any` (default), `furnished`, `furnishedKitchen` |
| `auction`        | String  |          | `any` (default), `only`, `exclude` |
| `onlyPriceDrops` | Boolean |          | Return (and pay for) only listings whose price was reduced. Default `false`. |
| `minPriceDropPercent` | Integer |     | Only listings whose price dropped by at least this %, e.g. `10`. Implies `onlyPriceDrops`. |
| `compact`        | Boolean |          | One flat row per listing with the most used fields (`agency`, `phone`, `mainPhoto`, … instead of nested `contacts`/`photos`). Best for CSV/Excel. Default `false`. |
| `excludeEmptyFields` | Boolean |      | Leave out empty fields (null, empty text, empty lists). Default `false`. |
| `descriptionMaxLength` | Integer |    | Cut `description` to this many characters. Empty or `0` = full text. |
| `debugLog`       | Boolean |          | Enable verbose debug logging |

This solution requires **Proxy servers**. Use [Apify Proxy](https://www.apify.com/docs/proxy) with the **RESIDENTIAL** group or your own residential proxies.

### Example Result

```json
{
    "url": "https://www.idealista.it/immobile/35994897/",
    "title": "Flat / apartment in Via della Balduina, 63, Centro di Balduina, Roma",
    "id": "35994897",
    "price": 830000,
    "size": 220,
    "priceByArea": 3773,
    "baths": 3,
    "rooms": 10,
    "address": "Flat / apartment in Via della Balduina, 63, Centro di Balduina, Roma",
    "hideAddress": false,
    "latitude": 41.9166671,
    "longitude": 12.4417612,
    "typology": "flat",
    "subTypology": null,
    "description": "BALDUINA | Refined 210 sq m apartment with livable terraces, garage, and cellar...",
    "energyCertification": null,
    "floor": "3",
    "status": "good",
    "newDevelopment": false,
    "hasLift": true,
    "externalReference": null,
    "district": "Balduina",
    "municipality": "Roma",
    "province": "Roma",
    "neighborhood": "Centro di Balduina",
    "locationId": "0-EU-IT-RM-01-001-097-38-002",
    "parkingSpace": {
        "hasParkingSpace": true,
        "isParkingSpaceIncludedInPrice": true
    },
    "features": {
        "hasSwimmingPool": false,
        "hasTerrace": false,
        "hasAirConditioning": true,
        "hasBoxRoom": true,
        "hasGarden": false
    },
    "labels": [
        { "name": "bright", "text": "Bright" }
    ],
    "highlight": "Top",
    "photos": [
        {
            "url": "https://img4.idealista.com/blur/480_360_mq/0/id.pro.es.image.master/a9/f6/68/1356345714.webp",
            "tag": "facade",
            "localizedName": "Facade",
            "deeplinkUrl": null
        }
    ],
    "videos": [],
    "3dtour": [],
    "listingUpdate": "2024-03-15T10:00:00.000Z",
    "listingUpdateText": "Updated 2 days ago",
    "priceDown": null,
    "priceDownPercentage": null,
    "contacts": {
        "commercialName": "Grupo Ibosa",
        "contactName": "NR Village homes",
        "phone1": {
            "phoneNumber": "919388896",
            "formattedPhone": "919 38 88 96",
            "prefix": "34",
            "phoneNumberForMobileDialing": "+34919388896",
            "nationalNumber": true,
            "formattedPhoneWithPrefix": "+34 919 38 88 96"
        }
    }
}
```

> **Note:** By default, search results (`district` or search-URL scraping) return the data included directly in the search response — it does **not** include everything a single property page has. Enable `fetchDetails` to fetch the full detail page for every search result instead:
>
> - **`energyCertification`** is *only* available from the detail page — there's no way to get it from search results, `fetchDetails` or not.
> - **`description`**, `size`, and `priceByArea` are present in both search results and detail pages.
> - **`neighborhood`**, `parkingSpace`, `newDevelopment`, and `highlight` are only present in search results — they're not returned by the detail endpoint at all, so scraping via a direct property URL (`/inmueble/`, `/immobile/`, `/imovel/`) or with `fetchDetails` enabled won't populate them.
> - **`district`/`municipality`/`province`** use a different, coarser location breakdown on the detail page (it's approximated from Idealista's `administrativeAreaLevel1-3` fields, which don't line up cleanly with the search response's own district/municipality/province).
> - **`features`** (pool, terrace, air conditioning, etc.) is less complete from the detail page — some flags (terrace, air conditioning) only exist there as free-text, not structured fields, so they're left out to avoid unreliable text-matching.

###### Tip

To use a filtered search: go to Idealista, apply filters on the search page, then copy and paste the URL as a `startUrl` entry.

Drawn-area searches work too: draw the area on Idealista's map, then paste the resulting `/areas/...?shape=...` URL as a `startUrl`. The polygon is used as the search area, so no district name is needed.

Filters in the URL path (price, size, rooms, bathrooms, home type, condition, features) are applied to the search and override the same fields in the actor input. Two caveats: the chalet subtypes (`chalets-independientes`, `chalets-adosados`, `casas-de-pueblo`, ...) are searched as one "houses" bucket, because the API has no subtype filter; and any filter token that cannot be mapped is logged as a warning and ignored.

#### How to get more than 2,500 results from one search

Idealista's API serves at most 50 pages of 50 listings for one search. With `splitByPrice` on (the default), a search that reports more results is re-run as price bands that each stay under that limit, and the bands are merged into one dataset. Each property is returned and charged once, even when it appears in two bands. Set `maxItems` to cap the run; with `maxItems` at 2,500 or less no splitting happens.

#### Monitoring: new listings only

Set `monitoringMode: true` and schedule the Actor (e.g. daily). The first run returns the full result set. Every later run with the same search returns only listings that no earlier run returned, so you pay only for new listings. The list of seen listings is kept in your account's `idealista-monitoring` key-value store, separately for each search: changing a location or filter starts a new list, while changing `maxItems`, sorting or language does not. Tip: sort by `publicationDate` so new listings come first. Property detail URLs in `startUrl` are always returned.

### Ready-made examples

Copy an input into the Actor's JSON input tab and run it. Every example works without a pasted URL unless it shows one.

| You want | Key input |
|----------|-----------|
| New homes for sale in Madrid, daily | `"district": "Madrid", "publishedWithin": "last48Hours", "sortBy": "publicationDate", "monitoringMode": true` |
| 2-bed flats to rent in Eixample, Barcelona under €1,400 | `"startUrl": [{ "url": "https://www.idealista.com/alquiler-viviendas/barcelona/eixample/con-precio-hasta_1400,de-dos-dormitorios/" }]` |
| Madrid flats reduced by 10% or more | `"district": "Madrid", "homeType": ["flat"], "minPriceDropPercent": 10` |
| Sea view apartments in Málaga under €400,000 | `"district": "Málaga", "homeType": ["flat"], "features": ["seaViews"], "maxPrice": 400000` |
| Furnished flats to rent in Madrid | `"district": "Madrid", "operation": "rent", "homeType": ["flat"], "furnished": "furnished"` |
| Villas for sale in Marbella | `"district": "Marbella", "homeType": ["villa"]` |
| Homes within 1 km of Puerta del Sol | `"latitude": 40.4169, "longitude": -3.7035, "radiusKm": 1, "sortBy": "distance", "sortOrder": "asc"` |
| Homes in Madrid postal codes 28013 and 28004 | `"postalCodes": ["28013", "28004"]` |
| Flat CSV-ready rows for Excel | `"district": "Valencia", "compact": true, "descriptionMaxLength": 200` |
| Pet-friendly flats to rent in Barcelona | `"district": "Barcelona", "operation": "rent", "homeType": ["flat"], "features": ["petsAllowed"]` |
| Holiday rentals in Barcelona (price per night) | `"district": "Barcelona", "operation": "rent", "propertyType": "vacationRentals"` |
| The whole Madrid sale market (past 2,500 results) | `"district": "Madrid", "splitByPrice": true, "maxItems": 3000` |
| 1-bed flats to rent in Lisbon under €1,100 | `"country": "pt", "district": "Lisboa", "operation": "rent", "bedrooms": ["1"], "maxPrice": 1100` |
| Milan apartments with price drops | `"country": "it", "district": "Milano", "sortBy": "priceDown"` |
| Flats to rent in Paris under €1,500 | `"country": "fr", "district": "Paris", "operation": "rent", "homeType": ["flat"], "maxPrice": 1500` |

A full input, for example the daily Madrid alerts (schedule it in Apify Console):

```json
{
    "district": "Madrid",
    "operation": "sale",
    "publishedWithin": "last48Hours",
    "sortBy": "publicationDate",
    "monitoringMode": true,
    "maxItems": 300,
    "proxy": { "useApifyProxy": true, "apifyProxyGroups": ["RESIDENTIAL"] }
}
```

### FAQ

#### Can I get more than 1,500 results from Idealista?

Yes. The Idealista website shows at most 1,500 results per search, and its API at most 2,500. With `splitByPrice` on (the default) bigger searches are split into price bands and merged, so you get the full result set. See [How to get more than 2,500 results](#how-to-get-more-than-2500-results-from-one-search).

#### How do I get only new listings every day?

Set `monitoringMode: true`, sort by `publicationDate` and schedule the Actor in Apify Console. Each run returns only listings that earlier runs with the same search did not return. See [Monitoring](#monitoring-new-listings-only).

#### Does it return agent phone numbers?

Yes, when the advertiser shows a phone on Idealista. It is in `contacts.phone1` (`phoneNumberForMobileDialing` is ready to dial, e.g. `+34919388896`), together with the agency's `commercialName` and the `contactName`. Private sellers often hide their number.

#### How do I find price drops?

Every result includes `priceDown` (amount in €) and `priceDownPercentage`. Set `onlyPriceDrops: true` to get, and pay for, only reduced listings, or `minPriceDropPercent: 10` for drops of 10% or more. With the default sort the results come biggest drop first, and the run stops as soon as the drops run out.

#### How much does a run cost?

List results cost $0.60–$1.00 per 1,000 depending on your Apify plan, results with `fetchDetails` $1.20–$2.50 (see [Pricing](#pricing)). Example: all 3,000 sale listings of a mid-size city cost about $1.80–$3.00. Set `maxItems` to cap a run.

#### Which countries are supported?

Spain (`idealista.com`), Portugal (`idealista.pt`), Italy (`idealista.it`) and France (`idealista.fr`). Start URLs can mix countries; each URL uses the country of its domain.

#### Can I use it from my code or another tool?

Yes. Run it through the [Apify API](https://docs.apify.com/api/v2) or the JavaScript and Python clients, or connect it to Make, Zapier, n8n, Google Sheets, Slack and other tools via Apify integrations. Results can be downloaded as JSON, CSV, Excel or XML.

#### Why is a listing's location approximate?

Some advertisers hide the exact address. Idealista then shows only an area, and `hideAddress` is `true`; the coordinates point to the area's center.

#### Is scraping Idealista legal?

The Actor collects only data that Idealista shows publicly. Listings can include personal data such as names and phone numbers; under the GDPR you need a legitimate reason to store and use it. If you are unsure, ask a lawyer.

### Bugs, fixes, updates and changelog

If you have any feature requests you can create an issue from [here](https://github.com/laster04/Idealista-scraper/issues).
[Here](https://github.com/laster04/Idealista-scraper/blob/main/CHANGELOG.md) is the changelog with new features and bugfix info.

# Changelog

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

# Actor input Schema

## `district` (type: `string`):

Where you want to look for the real estates: a city, district or postal code, e.g. Madrid or 28013. For further filtering you can use the URL below.

## `districts` (type: `array`):

Further locations or postal codes searched in the same run, e.g. Barcelona, 28013. Each is searched separately; maxItems caps the whole run.

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

Postal codes searched in the same run, e.g. 28013, 08001. Each is searched separately like a district; maxItems caps the whole run.

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

Country to search with the district field. For startUrl, the country comes from the URL domain (idealista.com / .pt / .it / .fr).

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

Select Listing sale or rent properties

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

Select type of property

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

Maximum number of results. Leave empty to get every result (up to the page limit below).

## `endPage` (type: `integer`):

Last search page to scrape per search (50 results per page, at most 50 pages). Leave empty to use all 50. maxItems is the better way to cap a run.

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

For each item found in a search, fetch the full property detail page instead of using the (thinner) search-result data. Adds description text, energy certification, and more accurate floor/lift/location fields, but is slower and uses one extra request per property.

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

One Idealista search returns at most 2,500 listings. When a search has more, it is split into price bands automatically so you get the full result set (no duplicates). Turn off to stop at the first 2,500.

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

Return only listings that previous runs with the same search did not return - ideal for scheduled daily runs. The first run returns everything. Changing a filter starts a new list.

## `startUrl` (type: `array`):

URL(s) of places or pages what will be scraped. For example https://www.idealista.com/venta-viviendas/madrid/centro/con-de-tres-dormitorios,de-cuatro-cinco-habitaciones-o-mas,tres-banos-o-mas/

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

Select proxies to be used by your crawler.

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

Select min size of property

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

Select max size of property

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

\["studio","1","2","3","4"] (leave empty for any)

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

\["1","2","3"] (leave empty for any)

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

\["flat","penthouse","duplex","studio","chalet","countryHouse","apartment","villa","loft","atticStudio","casaBaja"] (leave empty for any; several widen the search). "detachedHouse", "semiDetachedHouse" and "terracedHouse" all search houses (chalet) - Idealista has no separate filter for them.

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

\["newDevelopment","good","renew"] (leave empty for any)

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

\["bareOwnership","tenanted","illegallyOccupied","free"] (leave empty for any)

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

\["topFloor","intermediateFloor","groundFloor"] (leave empty for any)

## `features` (type: `array`):

\[ "airConditioning",  "builtinWardrobes",  "elevator",  "exteriorDomesticSpace",  "balcony",  "terrance",  "exterior",  "garage",  "garden",  "swimmingPool",  "storeRoom",  "accessible",  "luxury",  "seaViews",  "bankOffer",  "virtualTour",  "hasPlan",  "petsAllowed"] (leave empty for any; bankOffer = bank-owned, hasPlan = has a floor plan, petsAllowed = rent only)

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

Lowest price, e.g. 150000 for sale or 800 for rent per month.

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

Highest price.

## `publishedWithin` (type: `string`):

Only listings published recently. Idealista offers 24 hours for rent and 48 hours for sale only - the other one is replaced by it.

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

Order of the results. Distance only works with a radius search.

## `sortOrder` (type: `string`):

Direction of the sort above.

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

Language of titles and labels. Descriptions are always in the advertiser's original language.

## `energyRating` (type: `string`):

Energy certificate band.

## `furnished` (type: `string`):

Only furnished rentals, or only rentals with a fitted kitchen. Ignored for sale searches.

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

Include auction listings, show only auctions, or leave them out.

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

Return (and pay for) only listings whose price was reduced. With the default sort, results come sorted by the biggest drop first.

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

Return only listings whose price dropped by at least this percentage, e.g. 10. Implies Only price drops.

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

Only this agency's listings: its short name or page URL, e.g. https://www.idealista.com/pro/walterhauschamberi/. Replaces district when set.

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

Listing IDs to fetch directly (the number in the listing URL), on the site of the Country above. Like property URLs in startUrl, billed as detail results.

## `latitude` (type: `number`):

Centre of a radius search, e.g. 40.4168. Use with longitude; replaces district when set.

## `longitude` (type: `number`):

Centre of a radius search, e.g. -3.7038.

## `radiusKm` (type: `integer`):

Search radius around the centre point.

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

One flat row per listing with the most used fields (price, size, rooms, location, agency, phone, main photo, ...) instead of the full nested record. Best for CSV and Excel.

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

Leave out fields that are empty (null, empty text, empty lists), so each result carries only the data Idealista has for it.

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

Cut descriptions to this many characters (an ellipsis marks the cut). Leave empty or 0 for the full text.

## Actor input object example

```json
{
  "district": "Madrid",
  "districts": [],
  "postalCodes": [],
  "country": "es",
  "operation": "sale",
  "propertyType": "homes",
  "maxItems": 10,
  "endPage": 50,
  "fetchDetails": false,
  "splitByPrice": true,
  "monitoringMode": false,
  "startUrl": [],
  "proxy": {
    "useApifyProxy": true,
    "apifyProxyGroups": [
      "RESIDENTIAL"
    ]
  },
  "minSize": "any",
  "maxSize": "any",
  "bedrooms": [],
  "bathrooms": [],
  "homeType": [],
  "condition": [],
  "propertyStatus": [],
  "floorHeights": [],
  "features": [],
  "publishedWithin": "any",
  "sortBy": "weigh",
  "sortOrder": "desc",
  "language": "en",
  "energyRating": "any",
  "furnished": "any",
  "auction": "any",
  "onlyPriceDrops": false,
  "radiusKm": 5,
  "compact": false,
  "excludeEmptyFields": false
}
```

# 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 = {
    "district": "Madrid",
    "districts": [],
    "postalCodes": [],
    "maxItems": 10,
    "endPage": 50,
    "startUrl": [],
    "proxy": {
        "useApifyProxy": true,
        "apifyProxyGroups": [
            "RESIDENTIAL"
        ]
    },
    "bedrooms": [],
    "bathrooms": [],
    "homeType": [],
    "condition": [],
    "propertyStatus": [],
    "floorHeights": [],
    "features": []
};

// Run the Actor and wait for it to finish
const run = await client.actor("lukass/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 = {
    "district": "Madrid",
    "districts": [],
    "postalCodes": [],
    "maxItems": 10,
    "endPage": 50,
    "startUrl": [],
    "proxy": {
        "useApifyProxy": True,
        "apifyProxyGroups": ["RESIDENTIAL"],
    },
    "bedrooms": [],
    "bathrooms": [],
    "homeType": [],
    "condition": [],
    "propertyStatus": [],
    "floorHeights": [],
    "features": [],
}

# Run the Actor and wait for it to finish
run = client.actor("lukass/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 '{
  "district": "Madrid",
  "districts": [],
  "postalCodes": [],
  "maxItems": 10,
  "endPage": 50,
  "startUrl": [],
  "proxy": {
    "useApifyProxy": true,
    "apifyProxyGroups": [
      "RESIDENTIAL"
    ]
  },
  "bedrooms": [],
  "bathrooms": [],
  "homeType": [],
  "condition": [],
  "propertyStatus": [],
  "floorHeights": [],
  "features": []
}' |
apify call lukass/idealista-scraper --silent --output-dataset

```

## MCP server setup

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