---
title: "Scrape idealista property listings (Spain, Italy, Portugal)"
method: POST
path: "/realestate/idealista"
tags: ["Plugins"]
---

# Scrape idealista property listings (Spain, Italy, Portugal)

`POST /realestate/idealista`

## Request

- Base URL: `https://api.scrapeunblocker.com`
- URL: `https://api.scrapeunblocker.com/realestate/idealista`
- Auth: API key in header `x-scrapeunblocker-key`

Searches idealista (idealista.com, idealista.it, idealista.pt) for `location` - or takes any idealista search `url` - and returns the listings as JSON: `id`, `url`, `title`, `price` + `currency` (+ `pricePeriod` for rentals), `originalPrice` and `priceDropPercent` after a price cut, `pricePerM2`, `area`, `rooms`, `floor`, `lift`, `exterior`, `parking`, `description`, `tags`, `images`, `imageCount`, `multimedia` (plan, video, 3D tour), `agency` and `professional`. Filter by `operation` (sale / rent), `property_type`, price and size ranges, `rooms`, `bathrooms` and `features`, order with `sort`, and collect up to `max_results` across pages (30 per page; idealista shows at most 60 pages per search). A search with no match answers 200 with an empty `listings`. Billed one unit per page fetched (`pagesFetched`).

## Query parameters

- `url` string, nullable: Any idealista search URL (idealista.com, idealista.it or idealista.pt) with its filters, e.g. https://www.idealista.com/alquiler-viviendas/barcelona-barcelona/con-precio-hasta_2000,de-dos-dormitorios/. Overrides location and the filter parameters.
- `location` string, nullable: Location as idealista writes it in its URLs: a municipality ('madrid-madrid', 'barcelona-barcelona', 'milano-milano', 'lisboa'), a district ('madrid/centro', 'lisboa/arroios') or a province ('malaga-provincia'). Required unless url is given.
- `country` string: es, it, pt (idealista.com / .it / .pt).
- `operation` string: sale or rent.
- `property_type` string: One of: homes, new_homes, offices, premises, garages, lands, storage, buildings, rooms.
- `min_price` integer, nullable: Minimum price in EUR (monthly rent with operation=rent).
- `max_price` integer, nullable: Maximum price in EUR.
- `min_size` integer, nullable: Minimum area in m².
- `max_size` integer, nullable: Maximum area in m².
- `rooms` string, nullable: Comma-separated room counts: bedrooms in Spain (0 = studio ... 4 = four or more) and Portugal (T0 ... T4+), total rooms in Italy (1 ... 5 = five or more). E.g. '2,3'.
- `bathrooms` string, nullable: Comma-separated 1, 2, 3 (3 = three or more).
- `features` string, nullable: Comma-separated: lift, terrace, balcony, garage, pool, garden, air_conditioning, storage_room, fitted_wardrobes, accessible, luxury, new_construction, good_condition, to_renovate.
- `sort` string: One of: relevance, price_asc, price_desc, newest, oldest, size_asc, size_desc, price_per_m2_asc, price_per_m2_desc, biggest_drop.
- `page` integer, nullable: 1-based results page to start from (30 listings per page, at most 60). Use the `nextPage` of a previous response to continue.
- `max_results` integer: How many listings to collect across pages (1-300); each page fetched is one billed unit.
- `proxy_country` string, nullable: Proxy country the request is sent from (ISO-2). Leave blank for the exit chosen for the site.

## Response `200`

JSON with a `listings` array, `totalResults` and `nextPage`.

- unknown

## Other responses

- `400`: Invalid parameters.
- `404`: idealista has no such search (unknown location or URL).
- `422`: Validation Error
- `502`: Blocked by idealista on every attempt, no results page returned, or idealista did not answer in time.

---

[API](https://skmtc.dev/scrapeunblocker/apis/scrapeunblocker-api.md) · [All operations](https://skmtc.dev/scrapeunblocker/apis/scrapeunblocker-api/llms.txt) · [OpenAPI document](https://skmtc.dev/scrapeunblocker/apis/scrapeunblocker-api/revisions/c02f1254cc47?raw)