idealista.pt APIidealista.pt ↗
Search and retrieve Portugal property listings from Idealista.pt. Filter by location, price, size, bedrooms, or coordinates. Track price changes across properties.
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'
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.
| 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/34665653/",
"price": "660.000€",
"title": "Apartamento T2 na Rua da Beneficência, 100, Entrecampos, Avenidas Novas",
"details": [
"Garagem incluída",
"T2",
"151 m² área bruta"
],
"location": "",
"thumbnail": "https://img4.idealista.pt/blur/591_420_mq/0/id.pro.pt.image.master/9a/4b/54/305059374.jpg",
"property_code": "34665653",
"time_on_market": ""
}
],
"location": "lisboa",
"current_page": "1",
"total_on_page": 30
},
"status": "success"
}
}About the idealista.pt API
The Idealista.pt API provides 3 endpoints for accessing residential property listings across Portugal. Use search_properties to query listings by location name, price range, size in sqm, bedroom count, or a coordinate-radius pair, and get back up to 30 results per page including price, title, location, and thumbnail. Two additional endpoints handle full property detail retrieval and bulk price-status monitoring.
Searching Listings
search_properties accepts flexible combinations of filters: a plain location string (e.g., lisboa, porto), or a center coordinate pair with a radius in meters for geo-based queries. Price filtering uses max_price in EUR, and size filtering uses min_size and max_size in sqm. Results are paginated — the page parameter steps through results, and each response includes total_on_page, current_page, and the canonical url for the search. Each listing object in the listings array carries a property_code, title, url, price, location, details, time_on_market, and a thumbnail.
Property Detail
get_property_details takes a property_id (the property_code value from search results) and returns the full listing record: price, title, description, a features array, a details key-value object, an images array of URLs, update_date, and property_code. This is the endpoint to use when you need the full property description or a complete feature list that search results abbreviate.
Price Tracking
track_price_changes accepts a comma-separated list of property codes and returns a changes array. Each entry reports the property_code, a status value (active, inactive, blocked, or error), and the current price as a string or null. This allows periodic polling to detect when a listing has been removed or its price has changed, without fetching the full detail record for every property.
- Build a Portugal property search interface filtered by city, budget, and minimum floor area using
search_properties - Aggregate listing data for statistical analysis of asking prices across Lisbon, Porto, and Coimbra
- Monitor a watchlist of saved property codes for price drops or delistings via
track_price_changes - Pull full property descriptions and image URLs into a CRM or property database using
get_property_details - Run geo-fenced searches around a specific coordinate to find properties within a defined commute radius
- Alert buyers when
track_price_changesreports a status change fromactivetoinactiveon saved listings - Compare bedroom-count distributions across price bands by paginating
search_propertieswith varying filters
| 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 have an official developer API?+
What does `track_price_changes` actually return, and what does 'inactive' mean?+
track_price_changes returns a changes array where each object contains a property_code, a status, and a price. Status values are active (listing is live with a current price), inactive (the listing has been removed or expired), blocked (the listing exists but price data is unavailable), and error (the lookup failed). This endpoint does not return historical price time-series — it reflects the current state at the time of the call.Does the API cover rental listings as well as properties for sale?+
search_properties endpoint does not expose a listing-type filter distinguishing sales from rentals. Results reflect the default listing type returned for a given query. You can fork this API on Parse and revise it to add an explicit operation parameter targeting rental or sale listings separately.How many results can I retrieve per search, and can I access all pages?+
search_properties returns up to 30 listings per page. The page parameter controls pagination, and each response includes current_page and total_on_page. There is no total_results field in the response, so you cannot determine the total listing count for a query upfront — you can only detect the last page when total_on_page drops below 30 or returns an empty listings array.Can I filter by property type, such as apartment versus house?+
search_properties. The available filters are location, center/radius, bedrooms, max_price, min_size, and max_size. You can fork this API on Parse and revise it to add a property-type parameter covering apartments, villas, or land.