Is There an Idealista API? How to Get Listing Data

Ask whether a property portal has an API and the answer is almost always no. Idealista is the rare exception: it genuinely has one, it's called the Search API, and there's a page on its own domain where you can ask for a key. Then you go looking for the documentation, and there isn't any. No endpoint reference, no parameter list, no sandbox. Just a short paragraph and a contact form.

So the honest answer to "is there an Idealista API?" is yes, and that's where the interesting part starts. Here's what the official API actually is, what it structurally cannot do, and what you can run against Spanish, Italian, and Portuguese listings this afternoon.

The short answer

Yes. Idealista publishes an official Search API, and access is granted case by case. The request page at developers.idealista.com says it plainly: the Search API "lets you integrate property information published on idealista into your site or app. To receive an API key get in touch and tell us a bit about your project." The form asks for three things: your name, your email, and a description of what you're building.

Note the shape of that. It is not a signup. It's an application, reviewed by a human, for a product whose documentation you only receive if you're approved. One open-source client describes its subject in the repo title as the "Idealista API (invitation only)," which is about as concise a summary as you'll find.

That gate is the whole story, and it's why four different classes of workaround exist. We'll compare all of them. First, though, it's worth knowing exactly what you'd be getting if your application is approved, because a surprising number of teams chase the key for months and then discover it doesn't do the thing they needed.

What the official Idealista Search API actually is

Idealista is the leading property platform in Spain, Italy, and Portugal, and it has the balance sheet to match. EQT bought it in 2020 at a €1.3 billion valuation, then announced on 28 June 2024 that Cinven would take a 70 percent stake in a transaction valuing the company at €2.9 billion. When your listings inventory is the load-bearing asset in a three-billion-euro business, you do not put a self-serve firehose in front of it. You put a form in front of it.

The shape of it, reconstructed

Because Idealista hands its reference out privately, the public record of how the API works lives almost entirely in the client libraries that developers with keys wrote and open-sourced. Those are readable, and they agree with each other. A Julia client tested against v3.5 documents the surface in enough detail to reconstruct it:

Auth is OAuth2 client credentials. You POST to https://api.idealista.com/oauth/token with grant_type=client_credentials and scope=read, sending your API key and secret base64-encoded in a Basic auth header. You get back a bearer token and an expires_in, so you cache and refresh it.
Search is one POST per country. https://api.idealista.com/3.5/{country}/search, where country is es, it, or pt. Those three, and only those three.
Three parameters are required: country, operation (sale or rent), and propertyType (homes, offices, premises, garages, or bedrooms).
Plus a geography: every request needs either center as a WGS84 "lat,lon" string with a distance in metres, or an Idealista locationId.
Pages max out at 50. maxItems is documented as "50 as maximum," and you walk results with numPage.
Freshness filtering is coarse. sinceDate accepts W for last week, M for last month, T for the last day on rentals, and Y for the last two days on sales.

That's a competent, conventional listings search API. If your project is "show Idealista inventory near a point," it does the job.

Why nobody links to the docs

Here's the detail that explains half the confusion in the search results. The same Julia client's README, after listing every basic search field it knows about, notes that property-type-specific filters exist and tells you to "check the documentation you get when requesting the API key for details."

The reference is a deliverable of the approval process, not a public web page. That's why competing articles about the Idealista API are so oddly vague, why they cite each other instead of a primary source, and why the ones quoting a specific free-tier quota are quoting a developer's blog post rather than Idealista. We're not going to repeat a number we can't source either. What we can tell you is what the parameter surface allows, because that's written down in code that people actually ran.

Five things the official API won't do for you

This is the section that would have saved us a week, so it goes early rather than buried at the bottom.

It searches. That's the noun in the name. Every public client library built against it implements exactly one operation, and Idealista's own product name is the Search API. If your app's core loop is "user pastes a listing URL, we show them the analysis," a search-only API is the wrong shape and no amount of filtering fixes that.
Geography is a circle or a code. center plus distance draws a radius; locationId selects an administrative area. Neither one is a polygon. Anyone who has tried to express "inside the M-30 but not Chueca" as a circle knows how that goes. We wrote up why this matters in polygon search for property data.
Fifty results per page, and the site itself stops at 2,500. Idealista's own result sets are capped, which is why the better scraper tooling advertises working around it. One widely used Apify actor explicitly describes bypassing "Idealista's standard 2,500-result page limit" by re-slicing searches. Any full-market pull has to be built as many narrow searches, not one wide one.
Three countries. es, it, pt. Idealista is enormous in exactly those markets, so this is a reasonable product decision and a hard ceiling on your roadmap at the same time.
You have to be approved, and your project has to be the kind they like. "Tell us a bit about your project" is a filter, not a formality. A portal that competes for the same agents you want to analyze has every incentive to say no politely.

Infographic comparing what the official Idealista Search API covers against the gaps developers hit

Your four real options in 2026

Every route to Idealista listing data trades money against engineering time against fragility. The honest comparison:

Option	Pricing	Setup effort	Where it hurts
Official Idealista Search API	Not published; access granted case by case	Days to weeks, most of it waiting	Application review, no public docs, search only, circle-or-code geography, 50 per page, three countries.
DIY scraper (headless browser plus proxies)	"Free," plus proxies and your weekends	Days to build, permanent to maintain	Idealista sits behind aggressive bot protection. A plain HTTP client often gets a Cloudflare block page instead of markup, which we ran into repeatedly while researching this post.
Scraper marketplaces (e.g. Apify actors)	From $0.50 per 1,000 results	Hours	Cheap per row, and you still own scheduling, schema drift, dedup, and the 2,500-result workaround. Detail enrichment costs an extra request per property and slows runs dramatically.
Hosted REST endpoints (RealtyAPI)	Free tier at 250 requests/month; PRO $20/month for 20,000	Minutes	Covers Idealista's three markets only, and it's a live-data API rather than a historical archive.

That bot-protection row deserves a sentence more, because it's the single biggest reason DIY Idealista projects die. This live demo is a vendor pitching their own anti-detect browser, so read it as a sales demo. It is still an accurate picture of what your scraper is walking into:

If you're genuinely weighing build against buy, we laid out the general trade in web scraping vs. using an API. The short version: scraping wins when the data has no API at any price and your volume is tiny. It loses the week uptime starts to matter.

Is scraping Idealista legal?

The quiet question. Scraping publicly visible pages is not automatically illegal, but Idealista's terms prohibit it, and two other things make Spain, Italy, and Portugal a stricter environment than the US: everything you collect about named agents and private sellers is personal data under the GDPR, and listing photos and descriptions are somebody's copyrighted work. The commercial scrapers say this out loud in their own docs, which should tell you something. We go through the landscape properly in is website scraping legal? and explain our own sourcing in is RealtyAPI legal?

The practical read has not changed: the legal risk is real and ambiguous, the maintenance burden is certain, and most teams quit scraping because of the second one.

What RealtyAPI's Idealista endpoints cover

RealtyAPI runs hosted Idealista endpoints as part of its real estate data platform. You call a normal REST endpoint with an API key; proxies, blocks, and page-structure changes stop being your problem. Eleven endpoints in three groups, and the grouping is deliberate, because it fills the gaps listed above:

Endpoint	What it returns
`GET /autocomplete`	Location typeahead: cities, provinces, districts, neighborhoods, metro stops and addresses, each with its Idealista `locationId`, parent breadcrumbs, and result-count hints
`GET /search/bylocation`	Listings for a free-text place name or a `locationId`, with the full filter set below
`GET /search/bycoordinates`	Listings within a radius in kilometres of a lat/lon point
`GET /search/bypolygon`	Listings inside an arbitrary polygon, as a `lon lat` ring, a JSON coordinate list, or GeoJSON
`GET /search/byzip`	Listings for a postal code or city name
`GET /search/byurl`	Listings for a pasted Idealista search URL, any country, any operation
`GET /locations/sublocations`	Children of a location id, so you can walk the geography tree yourself
`GET /details/byid`	Full listing detail for one `propertyCode`
`GET /details/byurl`	Full listing detail from any Idealista listing URL, country auto-detected from the host
`GET /agent/details`	An agency's microsite profile: commercial name, contact details, website, default operation and typology, languages, active listing count, active since
`GET /agent/locations`	The locations an agency currently has listings in

Detail responses carry price and currency, address where Idealista shows it, photos, agent and agency contact, energy certification, the extra-characteristics block, year of construction, community costs, lift, neighborhood, latitude and longitude, the original-language description plus translated copies, and deeplink and share URLs. Auth is one x-realtyapi-key header, responses are JSON, and each request costs one credit.

Infographic showing eleven Idealista endpoints grouped into search, details, places, and agents

The filters that make it feel like Idealista

A generic listings API treats Madrid like any other city, which is how you end up unable to answer "second-hand two-bed in Salamanca, exterior, with a lift, under €1,800." These are the southern-European-native parameters that matter:

country: es, it, or pt, on every endpoint
searchType: For_Sale, For_Rent, or For_Share, because room-shares are a first-class market here, not an afterthought
ownerType: private, professional, or bank. That last value is how you isolate bank-repossessed stock, and pairs with auction
preservations: good, almost_new, newly_built, needs_renovation, to_restore
elevator, exterior, storeRoom, builtinWardrobes, independentHotWater: the flags Spanish listings are genuinely sorted by. A fourth-floor walk-up is a different product from a fourth floor with a lift
floorHeights: topFloor, intermediateFloor, groundFloor and friends
micrositeShortName: restrict results to a single agency, which turns the agent endpoints into a competitor-tracking tool
sizeRange in m² and priceRange in EUR, both as min:, max:, or a range
locale: ask for descriptions translated into en, fr, de and others instead of parsing Spanish yourself
newDevelopment, promotionId, parentPromotionId: off-plan and new-build campaigns, which are a large slice of the Spanish market
seaViews, swimmingPool, terrace, petsAllowed, virtualTour, hasPlan, luxury, accessible

There's also freeText, which matches amenity keywords against the listing description in the local language. It's the escape hatch for anything the structured filters don't cover.

Quick-start: Madrid listings in three requests

Base URL: https://idealista.realtyapi.io. Auth: your key in the x-realtyapi-key header. Idealista is on every plan including the free tier, so you can run all three of these on 250 requests a month before deciding anything. The docs cover key setup in about two minutes.

1. Resolve the location

curl "https://idealista.realtyapi.io/autocomplete?input=Salamanca,%20Madrid&country=es" \
  -H "x-realtyapi-key: YOUR_KEY"

You get back matching places with their locationId values. Idealista ids are hierarchical strings rather than integers, so 0-EU-ES-28-07-001-079 is the Madrid municipality and you can read the country, province, and municipality straight out of the code. Hold onto the id: passing it to search is both faster and less ambiguous than passing a name, and it's the difference between Salamanca the Madrid barrio and Salamanca the province three hours west.

2. Search that location

curl "https://idealista.realtyapi.io/search/bylocation?locationId=0-EU-ES-28-07-001-079&country=es&searchType=For_Rent&propertyType=homes&bedrooms=2,3&priceRange=max:1800&elevator=true&exterior=true&resultCount=50&page=1" \
  -H "x-realtyapi-key: YOUR_KEY"

Set resultCount to 50, the per-page ceiling, and walk page upward. Each page is one credit, so a page size of 50 costs you a fifth of what a page size of 10 does for the same listings. People get this wrong constantly.

3. Pull the full listing

curl "https://idealista.realtyapi.io/details/byid?propertyCode=106387165&country=es&locale=en" \
  -H "x-realtyapi-key: YOUR_KEY"

If what you have is a URL your user pasted rather than an id, skip the parsing and hand over the whole thing:

curl --get "https://idealista.realtyapi.io/details/byurl" \
  --data-urlencode "url=https://www.idealista.com/inmueble/106387165/" \
  -H "x-realtyapi-key: YOUR_KEY"

The country is detected from the host, so .it and .pt listing URLs work the same way, as do /immobile/, /imovel/, and /obra-nueva/ paths. This single endpoint is the one that makes "paste a link, get an analysis" products possible, and it's the clearest example of the gap between a search API and a data API.

Diagram of the three request flow: locate, search, then pull details for one listing

A production-ish Python loop

Here's the same flow with pagination and the error handling you actually want, since any API fronting live web data will have a bad minute upstream eventually:

import time
import requests

BASE = "https://idealista.realtyapi.io"
HEADERS = {"x-realtyapi-key": "YOUR_KEY"}
PAGE_SIZE = 50  # Idealista caps pages at 50; anything smaller just costs more credits

def get(path, attempts=3, **params):
    for attempt in range(attempts):
        try:
            r = requests.get(BASE + path, params=params, headers=HEADERS, timeout=60)
            r.raise_for_status()
            return r.json()
        except requests.RequestException as exc:
            if attempt == attempts - 1:
                raise
            # Upstream hiccups are usually transient. Back off, don't hammer.
            time.sleep(2 ** attempt)
            print(f"retrying {path} after {exc}")

def pages(path, max_pages=50, **filters):
    """Yield raw result pages until one comes back short or empty."""
    for page in range(1, max_pages + 1):
        data = get(path, page=page, resultCount=PAGE_SIZE, **filters)
        listings = next(
            (v for v in data.values() if isinstance(v, list)), []
        ) if isinstance(data, dict) else data
        if not listings:
            return
        yield listings
        if len(listings) < PAGE_SIZE:
            return  # short page means we've hit the end of this search

seen = set()
for batch in pages("/search/bylocation",
                   locationId="0-EU-ES-28-07-001-079", country="es",
                   searchType="For_Rent", propertyType="homes",
                   priceRange="max:1800", elevator="true"):
    for listing in batch:
        code = listing.get("propertyCode") or listing.get("id")
        if code and code not in seen:
            seen.add(code)
            print(code, listing.get("price"))

print(f"{len(seen)} unique listings")

Two things in there are deliberate. The retry wrapper exists because a live-data API's failure mode is a bad minute, not a bad day, and a bare raise_for_status() in a nightly job turns that minute into a missing day of data. And the pagination stops on a short page rather than trusting a total count, because remember the 2,500-result ceiling on Idealista's own searches: any strategy that assumes it can walk to the true end of a broad query is going to be quietly wrong. Slice by neighborhood or price band instead, and let each slice terminate honestly.

Unwrap the listing list in exactly one place, as above. When a schema shifts, you want to edit one function, not an application's worth of parsing assumptions.

From here it's your product. Diff nightly snapshots into Postgres for a price-drop tracker, run /search/bypolygon against a hand-drawn catchment for a relocation tool, or pair micrositeShortName with /agent/locations to watch which barrios an agency is expanding into. If you're picking coordinates rather than place names, searching by coordinates covers the geometry side.

What you still can't get

Honesty section. These endpoints return what is on Idealista now: active listings, their details, current agency profiles. They are not an archive. If you need price history across years, you capture snapshots yourself on a schedule, which the loop above plus a cron job and a database gets you most of the way to. There's no registry-level ownership data here either; Idealista is a marketplace, and the Spanish Catastro and the Portuguese and Italian equivalents are separate problems.

And if your product needs coverage beyond Iberia and Italy, Idealista alone won't do it. That's what pairing sources on one platform is for, the same way we worked through which Rightmove APIs actually exist, what became of the Zoopla API, why StreetEasy has none at all, and how the listing APIs compare overall.

Key takeaways

Idealista's API is real, and it's an application, not a signup. You send a name, an email, and a description of your project, and the documentation arrives only if you're approved. Budget weeks, and have a fallback.
Approved or not, it is a search API, and that is the whole product. Every open-source client built against it implements exactly one operation, and the documented parameter surface gives you circles and area codes rather than polygons, 50 results per page, and Spain, Italy, and Portugal only. Check that against your product's core loop before you spend a month waiting.
The 2,500-result ceiling is the trap in every full-market pull. Broad queries silently stop. Slice by neighborhood or price band and let each slice end on its own.
DIY scraping here is a bot-protection project, not a parsing project. Cloudflare answers before the HTML does, and GDPR plus listing copyright make Iberia a stricter place to improvise than the US.
Hosted endpoints collapse it to one HTTP call. Eleven of them cover typeahead, five ways to search including polygons, details by id or URL, and agency profiles, on a free tier that's enough to prove the fit.

If you're building for the Spanish, Italian, or Portuguese market, the fastest way to find out whether this data fits is to run the three requests above against your own barrio on the free tier. Two hundred and fifty requests is plenty to learn whether the shape is right, and you'll know today instead of after an approval queue.