Idealista APIidealista.pt ↗
Search and retrieve Portugal property listings from Idealista.pt. Filter by location, price, size, bedrooms, and coordinates. Track price changes across multiple properties.
What is the Idealista API?
The Idealista.pt API gives developers access to Portugal's property market through 3 endpoints covering listing search, full property details, and price-change tracking. With search_properties, you can query by city, bounding coordinates, bedroom count, price range, and square meters — getting back up to 30 paginated listings per request, each identified by a property_code that feeds directly into get_property_details or track_price_changes.
curl -X GET 'https://api.parse.bot/scraper/e54f0efd-0b6f-46e6-9088-7af104a1a037/search_properties?page=1&location=lisboa&operation=comprar&property_type=casas' \ -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-pt-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_portugal_api import Idealista, Operation, PropertyType
idealista = Idealista()
# Search for houses to buy in Lisbon
for listing in idealista.properties.search(
location="lisboa",
operation=Operation.BUY,
property_type=PropertyType.HOUSES,
max_price=800000,
):
print(listing.title, listing.price, listing.property_code)
# Navigate from summary to full details
full = listing.full()
print(full.description, full.update_date)
break
# Get a specific property by code
prop = idealista.properties.get(property_code="34665653")
print(prop.title, prop.price, prop.description)
# Track prices for multiple properties
for status in idealista.properties.track(property_codes="34665653,35043589"):
print(status.property_code, status.status, status.price)
Search for property listings in Portugal with flexible filters including location, price range, size, bedrooms, and coordinate-based radius search. Returns paginated results with up to 30 listings per page. Each listing includes a property_code usable with get_property_details for full information.
| Param | Type | Description |
|---|---|---|
| page | integer | Page number for pagination |
| center | string | Coordinates 'lat,lon' for circular search (e.g., '38.6979,-9.4215') |
| radius | string | Radius in meters from center (e.g., '5000') |
| bedrooms | string | Number of bedrooms (e.g., '1', '2', '3') |
| location | string | Location name for the search (e.g., 'lisboa', 'porto', 'coimbra') |
| max_size | integer | Maximum size in sqm |
| min_size | integer | Minimum size in sqm |
| max_price | integer | Maximum price in EUR |
| min_price | integer | Minimum price in EUR |
| operation | string | Operation type: 'comprar' (buy) or 'arrendar' (rent) |
| property_type | string | Property type: 'casas', 'quarteis-escritorios', 'garagens' |
{
"type": "object",
"fields": {
"url": "string - full URL of the search page",
"listings": "array of property listing objects with property_code, title, url, price, location, details, time_on_market, and thumbnail",
"location": "string - location used in the search",
"current_page": "string - page number",
"total_on_page": "integer - count of listings returned on this page"
},
"sample": {
"data": {
"url": "https://www.idealista.pt/comprar-casas/lisboa/",
"listings": [
{
"url": "https://www.idealista.pt/imovel/35043589/",
"price": "2.425.000€",
"title": "Apartamento T4 na Estrada das Laranjeiras, Entrecampos, Avenidas Novas",
"details": [
"Garagem incluída",
"T4",
"323 m² área bruta"
],
"location": "",
"thumbnail": "https://img4.idealista.pt/blur/591_420_mq/0/id.pro.pt.image.master/27/c3/9a/318252692.jpg",
"property_code": "35043589",
"time_on_market": ""
}
],
"location": "lisboa",
"current_page": "1",
"total_on_page": 30
},
"status": "success"
}
}About the Idealista API
Searching Listings
search_properties accepts flexible combinations of filters: a location string (e.g. 'lisboa', 'porto'), a center coordinate pair with a radius in meters for circular searches, min_size/max_size in square meters, max_price in EUR, and a bedrooms count. Results are paginated — use the page parameter to step through them. Each listing object in the listings array returns a property_code, title, url, price, location, details summary, time_on_market, and a thumbnail URL.
Property Details
get_property_details takes a single property_id (the property_code from search results) and returns the full listing record: a description text block, a structured details object of key-value pairs, a features array of amenity strings, an images array of full-resolution URLs, the formatted price, and an update_date showing when the listing was last modified on Idealista.pt. This endpoint is the right place to pull data for individual property pages or enrichment pipelines.
Tracking Price Changes
track_price_changes accepts a comma-separated list of up to 10 property codes and returns a changes array. Each entry carries the property_code, a status field ('active', 'inactive', 'blocked', or 'error'), and the current price (or null if the listing is no longer live). This is useful for monitoring a shortlist of properties over time — an 'inactive' status indicates the listing has been removed, while 'blocked' means the property is not currently accessible.
Coverage and Scope
All three endpoints are scoped to Idealista.pt, which covers Portugal. Rental listings and commercial property are not currently exposed — the endpoints return residential sale listings. The search_properties response includes a total_on_page count but does not return a total result count across all pages, so iteration requires stepping through pages until results drop off.
The Idealista API is a managed, monitored endpoint for idealista.pt — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when idealista.pt 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.pt 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 alert system that uses
track_price_changesto notify users when a saved listing drops in price or goes inactive - Aggregate Lisbon or Porto listings by coordinate radius to display on a map using
centerandradiusfilter parameters - Populate a property comparison tool with structured
detailsandfeaturesdata fromget_property_details - Feed a real estate investment model with filtered listings by
min_size,max_price, andbedroomsfromsearch_properties - Monitor listing freshness using the
update_datefield returned byget_property_details - Build a portfolio tracker for a shortlist of properties by polling
track_price_changesperiodically across up to 10 property codes - Extract property images via the
imagesarray for visual catalogues or machine learning datasets
| 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 have an official developer API?+
What does `track_price_changes` actually return, and what does each status mean?+
track_price_changes returns a changes array with one entry per property code you submit (up to 10). Each entry has a status field: 'active' means the listing is live and includes a current price; 'inactive' means the listing has been removed from Idealista.pt; 'blocked' means the listing exists but is not currently accessible; 'error' indicates a lookup problem. The price field is null for anything other than 'active'.Does `search_properties` return the total number of results across all pages?+
total_on_page, which is the count of listings on the current page, and current_page, but there is no field for the overall result count. To iterate through all results, increment the page parameter until total_on_page returns fewer than the maximum (30) or zero listings.