Idealista APIidealista.com ↗
Access Idealista sale and rental property listings, full listing details, and price-per-m² statistics for Spanish cities via a structured JSON API.
What is the Idealista API?
The Idealista API exposes 4 endpoints covering residential property sales and rentals across Spain, returning structured listing data including price, size, bedroom count, floor, and photo URLs. Use search_sale_listings or search_rental_listings to query paginated results filtered by location, price range, size range, and bedroom count, or call get_listing_detail to retrieve the full description, feature list, and photos for a specific property.
curl -X GET 'https://api.parse.bot/scraper/90cfec3d-abc0-45da-9a56-55bad74952eb/search_sale_listings?limit=5&location=madrid-madrid&filter_bedrooms=2&filter_max_price=400000&filter_min_price=200000&page=1' \ -H 'X-API-Key: $PARSE_API_KEY'
Search for properties listed for sale in a given location. Returns paginated listing summaries with price, size, bedrooms, floor, and description snippet. Supports filtering by price range, size range, and number of bedrooms; filters are applied by the site, so total_text reflects the filtered result count. Each page returns up to 30 listings from idealista.com; limit trims the returned page client-side. Pagination via page (defaults to 1); the response includes has_next to indicate more pages. Each call makes two page requests (a rental-route warm-up plus the sale page). Invalid filter values return a stale_input error.
| Param | Type | Description |
|---|---|---|
| page | integer | Page number for pagination. |
| limit | integer | Maximum number of listings to return. 0 means no limit (returns all listings on the page, up to 30). |
| locationrequired | string | Location slug in format 'city-province' (e.g. 'madrid-madrid', 'barcelona-barcelona', 'sevilla-sevilla', 'valencia-valencia'). |
| filter_bedrooms | string | Number of bedrooms filter. Accepted values: '1', '2', '3', or '4' ('4' means four or more). Other values are rejected. |
| filter_max_size | string | Maximum size in square meters, as a positive integer string (e.g. '150'). |
| filter_min_size | string | Minimum size in square meters, as a positive integer string (e.g. '50'). |
| filter_max_price | string | Maximum price in Euros, as a positive integer string (e.g. '500000'). |
| filter_min_price | string | Minimum price in Euros, as a positive integer string (e.g. '200000'). |
{
"type": "object",
"fields": {
"page": "current page number",
"stats": "object with avg_price_per_m2_page and results_on_page",
"has_next": "boolean indicating if more pages are available",
"listings": "array of listing objects with id, url, title, price, price_numeric, bedrooms, size, size_numeric, floor, description_snippet",
"location": "the location slug used in the search",
"operation": "the operation type used (venta-viviendas)",
"total_text": "human-readable total results string from the page header (reflects applied filters)"
},
"sample": {
"data": {
"page": 1,
"stats": {
"results_on_page": 30,
"avg_price_per_m2_page": 10420.51
},
"has_next": true,
"listings": [
{
"id": "111688398",
"url": "https://www.idealista.com/inmueble/111688398/",
"size": "117 m²",
"floor": "5ª planta exterior con ascensor",
"price": "685.000€",
"title": "Piso en Calle de Esparteros, Sol, Madrid",
"bedrooms": "2 hab.",
"size_numeric": 117,
"price_numeric": 685000,
"description_snippet": "GILMAR Consulting Inmobiliario pone a su disposición exclusiva propiedad de 117m2..."
}
],
"location": "madrid-madrid",
"operation": "venta-viviendas",
"total_text": "17.170 casas y pisos en Madrid"
},
"status": "success"
}
}About the Idealista API
Endpoints and Data Coverage
The API provides two search endpoints — search_sale_listings and search_rental_listings — that accept a required location slug in city-province format (e.g. madrid-madrid, barcelona-barcelona). Each page returns up to 30 listing objects containing id, url, title, price, price_numeric, bedrooms, size, size_numeric, floor, description_snippet, and location metadata. The response also includes a stats object with avg_price_per_m2_page and results_on_page, a has_next boolean for pagination, and a total_text string showing the human-readable result count from the page header.
Filtering and Pagination
Both search endpoints support optional filters: filter_min_price / filter_max_price (in Euros), filter_min_size / filter_max_size (in square meters), and filter_bedrooms. Pagination is controlled by the page integer parameter. The limit parameter caps the number of listings returned within a page; setting it to 0 returns all listings on that page (up to 30). The operation field in the response confirms which listing type was queried — venta-viviendas for sales or alquiler-viviendas for rentals.
Listing Detail
get_listing_detail accepts a numeric listing_id obtained from either search endpoint and returns the full description text, a features array (property attributes as strings), size, price, title, url, and a photos array of image URLs. This is the only endpoint that exposes photo URLs and the complete feature list.
Price Statistics
get_price_stats accepts a location slug and an optional operation type and returns avg_price_per_m2, sample_size, location, and operation. The average is computed from the first page of listings for that location and operation type, so sample_size reflects the number of listings included in the calculation.
The Idealista API is a managed, monitored endpoint for idealista.com — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when idealista.com changes and a check fails, the API is automatically queued for repair and re-verified. It is built to keep working as the site underneath it changes.
This isn't an official idealista.com API — it's an independent, maintained REST wrapper over public data. Where the source has no official API (or only a limited one), Parse gives you a stable contract over a source that never promised one, and keeps it current. Need a new endpoint or field? You can revise it yourself in plain English and the agent rebuilds it against the live site in minutes — contributing the change back to the shared API is free.
Will this API break when the source site changes?+
Is this an official API from the source site?+
Can I fix or extend this API myself if I need a new endpoint or field?+
What happens if I call an endpoint that has an issue?+
- Build a property price tracker for Spanish cities using
avg_price_per_m2fromget_price_stats - Aggregate rental listings in Madrid or Barcelona filtered by bedroom count and monthly rent range
- Populate a property comparison tool with full descriptions, features, and photos via
get_listing_detail - Monitor sale listing volume and average price trends across pages using
total_textandstats - Feed a real estate investment dashboard with price-per-m² data segmented by city and operation type
- Alert users when new listings matching size and price filters appear in a target neighborhood
- Build a relocation tool surfacing rental properties by minimum size and maximum monthly budget
| Tier | Price | Credits/month | Rate limit |
|---|---|---|---|
| Free | $0/mo | 200 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 100 req/min |
| Team | $300/mo | 20,000 | 300 req/min |
| Company | $1,000/mo | 100,000 | 500 req/min |
Each endpoint has a fixed posted price per successful call — most fall between 1 and 10 credits — shown on this API's page before you run it. 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 `location` parameter accept and what cities are supported?+
location parameter takes a slug in city-province format, for example madrid-madrid, barcelona-barcelona, or sevilla-sevilla. Any city available on idealista.com can be targeted using the corresponding slug. The API does not cover Idealista's Portugal or Italy portals — only Spain.How accurate is the `avg_price_per_m2` returned by `get_price_stats`?+
sample_size field tells you how many listings were included. Because it reflects only one page (up to 30 listings), it is a directional estimate rather than a market-wide average.Does the API return commercial properties, new-build developments, or garage listings?+
venta-viviendas) and residential rentals (alquiler-viviendas). Commercial properties, new-build promotions, parking spaces, and land listings are not exposed. You can fork this API on Parse and revise it to add endpoints targeting those Idealista property categories.Can I retrieve all listings for a location beyond the 30-per-page limit?+
has_next boolean indicates whether additional pages exist, and you can iterate using the page parameter to collect further results. There is no single-call endpoint that returns all listings for a location in one response.