Idealista APIidealista.it ↗
Access Italian real estate listings from Idealista.it. Search properties for sale, rent, new construction, and mountain areas with full details and photos.
What is the Idealista API?
The Idealista.it API covers 7 endpoints for querying Italy's largest property portal, returning listings for sale, rent, new constructions, and mountain properties. The get_property_details endpoint delivers the full property record including price, photos array, features list, location text, and complete description. A location resolver endpoint (search_by_location_slug) converts plain city names into the slugs required by all search endpoints.
curl -X GET 'https://api.parse.bot/scraper/355fc7d9-12b3-4d7e-9a57-fcd5514d1f6f/search_properties_for_sale?page=1&location=milano-milano&max_price=500000&min_price=100000' \ -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-it-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.
"""Walkthrough: Idealista.it Italy real estate SDK — search, filter, drill-down."""
from parse_apis.idealista_it_italy_api import (
Idealista, LocationCategory, NotFound
)
client = Idealista()
# Resolve a city name to its location slug for use in search endpoints.
location = client.locations.search(query="Milano", limit=5).first()
print(f"Resolved: {location.label} (category={location.category}, count={location.count})")
# Search for sale properties in Milano, capped at 3 results.
for prop in client.propertysummaries.search_for_sale(location="milano-milano", max_price=400000, limit=3):
print(f"[Sale] {prop.title} — {prop.price}, {prop.specs.size}")
# Drill into one listing's full details via the summary→detail nav op.
listing = client.propertysummaries.search_for_rent(location="milano-milano", limit=1).first()
if listing:
detail = listing.detail()
print(f"Detail: {detail.title}, features={len(detail.features)}, photos={len(detail.photos)}")
# Construct a PropertySummary by known ID and fetch its photos directly.
try:
photo_set = client.propertysummary(id="99999999").photos()
print(f"Photos: {len(photo_set.photos)}")
except NotFound as exc:
print(f"Property not found: {exc}")
print("Exercised: locations.search / propertysummaries.search_for_sale / search_for_rent / detail / photos")
Search for residential properties for sale on Idealista.it. Returns paginated listings with price, size, room count, and description snippets. Pagination is by page number; each page returns up to 30 listings. Use search_by_location_slug to resolve a city name to the required location slug.
| Param | Type | Description |
|---|---|---|
| page | integer | Page number for pagination. |
| locationrequired | string | Location slug in format 'city-province' (e.g., 'milano-milano', 'roma-roma', 'napoli-napoli'). Use search_by_location_slug to find valid slugs. |
| max_price | integer | Maximum price filter in Euros. |
| min_price | integer | Minimum price filter in Euros. |
{
"type": "object",
"fields": {
"listings": "array of property listing objects with id, title, url, price, details, description_snippet, and thumbnail",
"total_count_text": "string with the total count and location description (e.g., '15.290 case in vendita a Milano')"
},
"sample": {
"data": {
"listings": [
{
"id": "31167672",
"url": "https://www.idealista.it/immobile/31167672/",
"price": "650.000€",
"title": "Trilocale in Piazzale Brescia s.n.c, Morgantini - Segesta, Milano",
"details": {
"size": "100 m²",
"floor": "3º piano con ascensore",
"rooms": "3 locali"
},
"thumbnail": "https://img4.idealista.it/blur/480_360_mq/0/id.pro.it.image.master/38/73/ea/646842718.jpg",
"description_snippet": "In Palazzo Signorile con servizio di portineria ed ascensore..."
}
],
"total_count_text": "15.677 case in vendita a Milano"
},
"status": "success"
}
}About the Idealista API
What the API Returns
The search endpoints — search_properties_for_sale, search_properties_for_rent, search_new_construction, and search_mountain_properties — all return a consistent listing object shape: id, title, url, price, details, description_snippet, and thumbnail. Each response also includes total_count_text, a string like '15.290 case in vendita a Milano' that reflects the total result count for the query. Sale and rental searches support min_price / max_price filters in Euros; the rental endpoint treats price as monthly rent.
Location Resolution and Pagination
All search endpoints require a location parameter formatted as a city-province slug (e.g., milano-milano, cortina-d-ampezzo-belluno). Use search_by_location_slug first: pass a plain city name like 'Roma' and receive an items array where each entry includes label, url, location_id, category (one of Comune, Provincia, Area, Zona, Quartiere), and a listing count. Take the url field from a matching result and use it as the location input for search. Paginated search endpoints return up to 30 listings per page; use the integer page parameter to step through results.
Property Detail and Photo Endpoints
get_property_details accepts a numeric property_id sourced from any listing result and returns the full record: id, url, price, title, photos (array of image URL strings), features (array of strings), description (full text or null), and location_text. If you only need images, get_property_photos returns just the photos array for the same property_id, avoiding the overhead of the full detail payload.
Specialised Search Scopes
search_new_construction filters results to newly built properties (nuova costruzione) for a given location slug, using the same listing object format as the general sale search. search_mountain_properties targets alpine area slugs such as courmayeur-aosta or cortina-d-ampezzo-belluno, making it straightforward to scope queries to ski resort or mountain market segments without additional post-filtering.
The Idealista API is a managed, monitored endpoint for idealista.it — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when idealista.it 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.it 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?+
- Aggregate and compare property sale prices across Italian cities using
search_properties_for_salewithmin_price/max_pricefilters - Build a rental market tracker for Rome or Milan by paginating through
search_properties_for_rentresults and storing monthly rent values - Populate a new-development database by querying
search_new_constructionfor multiple provinces and collecting listing IDs - Display full property pages in a third-party app by calling
get_property_detailsfor any listing ID to retrieve photos, features, and description - Monitor alpine real estate inventory by querying
search_mountain_propertiesfor specific resort locations like Cortina d'Ampezzo - Resolve user-typed city names to canonical Idealista location slugs using
search_by_location_slugbefore constructing search queries - Fetch image galleries for property listings without loading the full detail record via
get_property_photos
| 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.it offer an official developer API?+
What does `search_by_location_slug` return, and why is it needed?+
items array of location suggestions, each with a label, url, location_id, category (Comune, Provincia, Area, Zona, or Quartiere), and listing count. The search endpoints require a precise city-province slug format that is difficult to construct manually — this endpoint resolves plain Italian city names to valid slugs you can pass directly to location parameters.Are commercial properties, offices, or garages covered?+
How does pagination work, and is there a limit on pages retrieved?+
page parameter and return up to 30 listings per page. The total_count_text field in each response tells you the total number of matching listings for the query, so you can calculate how many pages exist. There is no built-in cap on which page numbers you can request, though very high page numbers may return empty results if they exceed the total listing count.Does `get_property_details` always return a full description?+
description field returns a full text string when one is present on the listing, but it can be null if the seller has not provided a description. All other fields — price, title, photos, features, and location_text — are always returned when the property ID is valid. If you only need images, get_property_photos retrieves just the photos array for the same ID.