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?page=1&limit=5&location=madrid-madrid' \ -H 'X-API-Key: $PARSE_API_KEY'
Typed, relational, agent-ready
A generated client with real types, enums, and the links between objects — the structure a flat JSON response can't carry. Autocompletes in your editor and reads cleanly to coding agents.
- Fully typed · autocompletes
- Objects link to objects
- Typed errors & pagination
Typed Python client. Set up the SDK in your uv project, then pull this API’s typed client:
uv add parse-sdk uv run parse init uv run parse add --marketplace idealista-com-api
uv run parse add --marketplace pulls a pinned snapshot of this canonical API — it won’t change underneath you. To customize it, subscribe and swap to your own copy.
from parse_apis.idealista_api import Idealista, Operation, Listing, ListingDetail, PriceStats
client = Idealista()
# Get a location and search for rental listings
madrid = client.location("madrid-madrid")
# Check price stats for rentals
stats = madrid.price_stats(operation=Operation.RENTAL)
print(stats.location, stats.avg_price_per_m2, stats.sample_size)
# Search rental listings with filters
for listing in madrid.rental_listings(filter_bedrooms="2", filter_max_price="1500", limit=5):
print(listing.id, listing.title, listing.price, listing.size)
# Get full detail for a listing
detail = listing.refresh()
print(detail.title, detail.price, detail.description, detail.features)
# Search for sale properties in another city
barcelona = client.location("barcelona-barcelona")
for prop in barcelona.sale_listings(filter_min_size="80", filter_max_price="400000", limit=3):
print(prop.id, prop.title, prop.price_numeric, prop.size_numeric)
Search for properties listed for sale in a given location. Returns paginated listing summaries with price, size, bedrooms, and location info. Supports filtering by price range, size range, and number of bedrooms. Each page returns up to 30 listings from idealista.com. Pagination via page number; the response includes has_next to indicate more pages.
| 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 (e.g. '1', '2', '3', '4'). |
| filter_max_size | string | Maximum size in square meters (e.g. '150'). |
| filter_min_size | string | Minimum size in square meters (e.g. '50'). |
| filter_max_price | string | Maximum price in Euros (e.g. '500000'). |
| filter_min_price | string | Minimum price in Euros (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_text, agency_name",
"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"
},
"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 | 100 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 100 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 `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.