idealista.com APIidealista.com ↗
Search sale and rental listings on Idealista, retrieve full property details, and pull average price-per-m² stats by location with 4 structured endpoints.
curl -X GET 'https://api.parse.bot/scraper/90cfec3d-abc0-45da-9a56-55bad74952eb/search_sale_listings' \ -H 'X-API-Key: $PARSE_API_KEY'
Search for properties for sale. Accepts location slug and filters.
| Param | Type | Description |
|---|---|---|
| page | integer | Page number |
| limit | integer | Max listings to return |
| locationrequired | string | Location slug (e.g. 'madrid-madrid') |
| filter_bedrooms | string | Number of bedrooms (e.g. '1', '2', '3') |
| filter_max_size | string | Maximum size in m2 |
| filter_min_size | string | Minimum size in m2 |
| filter_max_price | string | Maximum price in Euros |
| filter_min_price | string | Minimum price in Euros |
{
"type": "object",
"fields": {
"page": "integer",
"stats": "object",
"listings": "array",
"location": "string",
"operation": "string",
"total_text": "string"
},
"sample": {
"page": 1,
"stats": {
"results_on_page": 20,
"avg_price_per_m2_page": 3500
},
"listings": [
{
"id": "12345678",
"url": "...",
"price": "250.000€",
"title": "Piso en venta..."
}
],
"location": "madrid-madrid",
"operation": "venta-viviendas",
"total_text": "1.234 casas y pisos..."
}
}About the idealista.com API
The Idealista API covers Spain's largest property portal through 4 endpoints: search sale listings, search rental listings, retrieve a single listing's full detail, and fetch average price-per-m² statistics for any location. The search_sale_listings endpoint accepts price, size, and bedroom filters and returns a listings array alongside aggregated stats, giving developers a direct path from location slug to structured property data.
Search and Filter Listings
Both search_sale_listings and search_rental_listings accept a required location slug (e.g. madrid-madrid, barcelona-barcelona) and optional filters for filter_bedrooms, filter_min_size/filter_max_size in m², and filter_min_price/filter_max_price in Euros. Results are paginated via the page and limit parameters. Each response includes a listings array and a stats object that summarises the matched set. The sale endpoint also returns total_text, operation, and the resolved location string so you can confirm what the query matched.
Listing Detail
Passing a listing_id to get_listing_detail returns the full record for a single property: id, url, price, title, a photos array, a features array covering attributes like floor area and room count, and a free-text description. Listing IDs appear in search results, so a typical workflow is to page through search_sale_listings and then call get_listing_detail for records that match your criteria.
Price Statistics
get_price_stats accepts a location slug and an optional operation string — either alquiler-viviendas (rentals) or venta-viviendas (sales) — and returns avg_price_per_m2, sample_size, location, and operation. This endpoint is useful for market benchmarking, automated valuation models, or tracking neighbourhood price trends over time without having to aggregate individual listings yourself.
Coverage and Limitations
All location inputs use Idealista's own slug format. If you supply an unrecognised slug, results will be empty rather than an error, so validate slugs against known geography before building automated pipelines. Filtering is limited to the parameters listed above; sorting order, property type (house vs. apartment), and new-build flags are not exposed as inputs in the current endpoint set.
- Track average price-per-m² trends across Madrid neighbourhoods using
get_price_statswithventa-viviendas - Build a rental affordability dashboard by combining
search_rental_listingsprice filters withstatsoutput - Aggregate full listing details — photos, features, description — for a property comparison tool via
get_listing_detail - Alert users when new sale listings match their bedroom count and size range using paginated
search_sale_listings - Feed a CRM with structured property data by looping through
listingsarrays and enriching records with detail calls - Benchmark asking prices against market averages by pairing individual listing prices with
avg_price_per_m2from the same location
| Tier | Price | Credits/month | Rate limit |
|---|---|---|---|
| Free | $0/mo | 100 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 250 req/min |
One credit = one API call regardless of which marketplace API you call. Exceeding the rate limit returns a 429 response. Authenticate with the X-API-Key header.
Does Idealista offer an official developer API?+
What does the `stats` object in search results contain?+
stats object is returned alongside the listings array in both search_sale_listings and search_rental_listings. It provides aggregated summary figures for the matched result set. For precise per-location market averages broken out by operation type, use get_price_stats instead, which returns avg_price_per_m2 and sample_size as explicit fields.Can I filter by property type — for example, only apartments or only houses?+
Does the API cover Idealista listings outside Spain, such as Italy or Portugal?+
How should I handle pagination when scraping large result sets?+
page integer and a limit parameter. Increment page on successive calls and stop when the returned listings array is shorter than limit or empty. The total_text field on search_sale_listings gives a human-readable count of total results, which you can use to estimate the number of pages before starting.