Idealista is the dominant property portal across three southern European markets at once: Spain, Italy and Portugal. That combination is unusual. Most portals are national, so covering the region normally means integrating three separate sources with three schemas. Idealista gives you one.
The Idealista API exposes that inventory through 14 endpoints. This post covers what is in them and what the data is actually good for.
Finding properties: five ways in
Search is where most integrations start, and there are more entry points than usual.
/property-search is the standard filtered search: country, operation (sale or rent), property type, price range, size, rooms, bathrooms, condition, and the amenity flags that matter locally, such as lift, terrace, pool, garage and air conditioning.
/smart-search takes natural language. You pass something like “three bedroom flat with a terrace near the beach under 400k” and it resolves the intent into a structured query. This is worth knowing about if you are building a conversational property search or an LLM agent, because it removes an entire translation layer you would otherwise write yourself.
/property-search-by-coordinates searches a radius around a point, for map-driven interfaces.
/property-search-by-zip searches by postal code, which is often the cleanest join key when you are enriching an existing address database.
/property-search-by-url takes an Idealista search URL and returns the same results as JSON. Genuinely useful in practice: a client or analyst can build a search in the browser, send you the link, and you turn it into a feed without reverse-engineering their filters.
Supporting these, /auto-complete resolves free text into the location IDs the search endpoints expect, /sublocations walks the hierarchy from region down to district, and /reverse-geocode turns a coordinate into an Idealista location.
Listing detail and the endpoints people miss
/property-details and /property-details-by-url return the full record: price and price history where available, surface area, floor, orientation, energy certificate rating, construction year, parking and storage, agency or private seller, photos, and geo-coordinates.
Two endpoints beyond the obvious are worth calling out.
/listing-stats returns engagement data for a listing - how much interest it is attracting on the portal. This is a demand signal you cannot derive from the listing itself. Two flats at the same price per square metre in the same district are not equivalent if one is generating five times the interest. For investment tools and agency dashboards, this is often the most valuable field in the response.
/comments returns the listing’s descriptive text and notes. Useful for keyword extraction, condition classification, and feeding text into a model that scores listings.
Agent and agency data
/agent-details returns an agency profile and /agent-listings returns its active inventory. Together they answer questions that listing data alone cannot: who is dominant in this district, how large is their book, what price bands do they operate in, and how has that changed.
For lead generation and competitive analysis in Spanish and Portuguese markets, where agency structure is fragmented and local, this is usually where the commercial value sits.
What the three markets look like
Spain is the largest of the three by listing volume and the most liquid. Barcelona and Madrid dominate urban demand; the Balearics, Costa del Sol and Alicante carry heavy international buyer interest with different seasonality and price dynamics. Energy certificate data is well populated, which matters given EU efficiency rules tightening through the decade.
Portugal has been reshaped by foreign demand. Lisbon and Porto have seen sustained international interest, and the Algarve behaves as a distinct holiday and second-home market rather than a residential one. Yields and price trajectories diverge sharply between them, so treat them separately in any model.
Italy is more regionally fragmented than either. Milan and Rome behave like normal metropolitan markets. Much of the rest of the country does not, with large volumes of older housing stock, restoration properties, and enormous variation in condition at similar prices. Condition and construction-year fields do more work here than anywhere else.
What people build with this
Cross-border property search. The strongest use of this API specifically. One integration covering three countries lets you build a search product for buyers who are not committed to a single market, which describes most international buyers in this region.
Investment screening. Combine price per square metre with /listing-stats engagement and location hierarchy to rank districts. Cross-reference against rental listings in the same area to approximate rental yield.
Agency intelligence. Track which agencies hold which inventory, by district and price band.
Market monitoring. Poll saved searches on a schedule, store snapshots, and track how asking prices and inventory move. The API returns current state, so any time series is yours to build. Start collecting before you need it.
CRM and portfolio enrichment. Use /property-search-by-zip or /reverse-geocode to attach live market context to addresses you already hold.
Practical notes
Call /auto-complete first and cache the location IDs. Nearly every mistake in a first integration comes from guessing at location identifiers rather than resolving them.
Place names carry regional spellings, particularly in Catalonia, the Basque Country and Galicia. Do not normalise them yourself; let autocomplete do it.
Treat prices as asking prices. Idealista lists what sellers want, not what buyers paid. For transacted prices you need a registry source, and in Spain that is a separate problem with its own delay.
Related APIs
For Spain specifically, the Fotocasa API is the other major national portal and a useful cross-check on inventory and pricing. For the wider catalog see the Real Estate Data hub, or browse the full API Library.
Disclaimer
Happy Endpoint is not affiliated with, endorsed by, or sponsored by Idealista. All data is collected from publicly available sources.
