Real Estate

Idealista API scraper API

The Idealista API returns Spanish and Italian real-estate listings as clean JSON.

3 actionsLive JSON1,000 free creditsMCP-ready

🤖 Using an AI assistant? Copy this link into ChatGPT / Claude / Cursor — it reads every endpoint and parameter instantly and tells you if this API fits your use case.

The primary search endpoint returns listings with id, URL, title, price, rooms, bathrooms, surface (m2), floor and features, and you can pull a detail and geography. It is built for real-estate tools and Southern-Europe property analytics that need Idealista data without a scraper. One ReefAPI key, one shared credit pool, the standard envelope.

Live example

Real request and response JSON

Captured from the indexed primary action, search, on Jul 18, 2026, 5:19 PM UTC.

Captured request

{
  "method": "POST",
  "url": "https://api.reefapi.com/idealista/v1/search",
  "headers": {
    "x-api-key": "$REEF_KEY",
    "content-type": "application/json"
  },
  "body": {
    "location": "Madrid",
    "country": "es"
  }
}

Captured response

{
  "ok": true,
  "meta": {
    "api": "idealista",
    "endpoint": "search",
    "mode": "live",
    "latency_ms": 1985,
    "record_count": 30,
    "bytes": 472758,
    "cache_hit": false,
    "stop_reason": "limit_reached",
    "method": "camoufox_mint_curl_replay",
    "country": "es",
    "currency": "EUR",
    "total": 17728,
    "count": 30,
    "page": 1,
    "slug": "madrid-madrid",
    "filters_applied": {},
    "filters_unsupported": null
  },
  "data": {
    "results": [
      {
        "id": "[redacted-phone]",
        "url": "https://www.idealista.com/inmueble/[redacted-phone]/",
        "title": "Piso en Calle de Castelló, Recoletos, Madrid",
        "price": 1490000,
        "currency": "EUR",
        "rooms": 2,
        "bathrooms": null,
        "surface_m2": 106,
        "floor": "3ª planta interior con ascensor",
        "features": [],
        "thumbnail_url": "https://img4.idealista.com/blur/591_420_mq/0/id.pro.es.image.master/5a/9a/e5/[redacted-phone].jpg"
      },
      {
        "id": "[redacted-phone]",
        "url": "https://www.idealista.com/inmueble/[redacted-phone]/",
        "title": "Piso en Calle Velázquez, Castellana, Madrid",
        "price": 2250000,
        "currency": "EUR",
        "rooms": 3,
        "bathrooms": null,
        "surface_m2": 152,
        "floor": "3ª planta exterior con ascensor",
        "features": [],
        "thumbnail_url": "https://img4.idealista.com/blur/591_420_mq/0/id.pro.es.image.master/b4/6e/ef/[redacted-phone].jpg"
      },
      {
        "id": "[redacted-phone]",
        "url": "https://www.idealista.com/inmueble/[redacted-phone]/",
        "title": "Piso en Calle de la Lechuga, Sol, Madrid",
        "price": 798000,
        "currency": "EUR",
        "rooms": 4,
        "bathrooms": null,
        "surface_m2": 110,
        "floor": "3ª planta exterior con ascensor",
        "features": [],
        "thumbnail_url": "https://img4.idealista.com/blur/591_420_mq/0/id.pro.es.image.master/45/b0/a4/[redacted-phone].jpg"
      }
    ],
    "total": 17728,
    "count": 30,
    "page": 1,
    "country": "es",
    "slug": "madrid-madrid",
    "filters_applied": {},
    "filters_unsupported": []
  }
}

Actions

What the Idealista API scraper API does

Action	Description	Concrete use case	Key params
search	Search Idealista property listings by location (Spain, Italy or Portugal; for sale or rent) with structured filters: price (EUR), bedrooms, surface (m²), property type and sort. Each result carries id, title, price, rooms, bathrooms, surface, floor, features and thumbnail. Paginate with page.	Real-estate investors call search to search Idealista property listings by location (Spain, Italy or Portugal; for sale or rent) w….	location, country, contract, sort, home_type, ...
detail	Full record for a single listing by its Idealista id (the number in an idealista.com/inmueble/<id>/ URL, or a search result's `id`). Returns title, price, address, bedrooms, bathrooms, surface, year built, the full feature list, description and all gallery image URLs.	Brokerage tools call detail to get full record for a single listing by its Idealista id (the number in an idealista.com/inmueble….	id, country
geography	Resolve a free-text place name to the Idealista location slug + a ready-to-use search preview (the count of active listings there). Use it to confirm a location before searching, or to discover the exact slug a city resolves to.	Property dashboards call geography to resolve a free-text place name to the Idealista location slug + a ready-to-use search preview….	query, country, contract

Code samples

Call search from your stack

curl -X POST https://api.reefapi.com/idealista/v1/search \
  -H "x-api-key: $REEF_KEY" \
  -H "content-type: application/json" \
  -d '{"location":"Madrid","country":"es"}'

import requests

r = requests.post(
    "https://api.reefapi.com/idealista/v1/search",
    headers={"x-api-key": REEF_KEY},
    json={
  "location": "Madrid",
  "country": "es"
},
)
print(r.json()["data"])

const res = await fetch("https://api.reefapi.com/idealista/v1/search", {
  method: "POST",
  headers: {
    "x-api-key": process.env.REEF_KEY,
    "content-type": "application/json",
  },
  body: JSON.stringify({
  "location": "Madrid",
  "country": "es"
}),
});
const { ok, data, meta, error } = await res.json();

MCP one-liner

Ask your MCP-connected assistant: call reefapi.idealista.search with {"location":"Madrid","country":"es"}.

Use cases

Who uses this API and why

Investors call search to track listing prices by geography.
Dashboards use detail and features to enrich a property.
Analysts use geography to size a Spanish or Italian market.

FAQ

Questions developers ask before integrating

What is the Idealista API scraper API?

Idealista API scraper API is a ReefAPI endpoint group for idealista api scraper It returns live JSON through POST requests under /idealista/v1.

Is the Idealista API scraper API free to try?

Yes. ReefAPI starts with 1,000 free credits, no card required. Idealista API scraper calls use the same shared credit balance as every other ReefAPI engine.

Do I need a Idealista API scraper login or account?

No login to Idealista API scraper is needed for the API response. You call ReefAPI with your x-api-key header, and the playground can run live examples before you create a production key.

How fresh is the Idealista API scraper data?

The page example is captured from a live search call, and production requests fetch live data through ReefAPI rather than a static sample.

How many credits does the Idealista API scraper API use?

Idealista API scraper actions currently cost 1-2 credits per successful call. Failed or blocked calls are free, and all APIs draw from one credit pool.

Can I call Idealista API scraper from an AI assistant or MCP client?

Yes. Connect ReefAPI once through MCP and your assistant can call idealista actions with the same key, credit pool and JSON envelope used by normal REST requests.

Is the Idealista API scraper API a Idealista API scraper scraper?

It is the managed alternative to a DIY Idealista API scraper scraper. Instead of building and maintaining your own scraper — proxies, headless browsers, captcha and constant breakage — you call one ReefAPI endpoint and get the same idealista api scraper back as clean JSON.

Why does my Idealista API scraper scraper keep getting blocked?

Most Idealista API scraper scrapers break on anti-bot defenses, rate limits and IP bans that need rotating residential proxies and browser fingerprinting to clear. ReefAPI handles all of that for you — no proxies, no captchas, no maintenance — and returns live JSON. Blocked or failed calls are free.

docs / idealista

Idealista API scraper

base /idealista/v13 endpoints

post/idealista/v1/search2 credits

Search Idealista property listings by location (Spain, Italy or Portugal; for sale or rent) with structured filters: price (EUR), bedrooms, surface (m²), property type and sort. Each result carries id, title, price, rooms, bathrooms, surface, floor, features and thumbnail. Paginate with page.

Parameter		Allowed / range	Description
location	required	—	Where to search — a city in the selected country ('Madrid', 'Roma', 'Lisboa', 'Barcelona'). You may also pass an exact Idealista location slug (e.g. 'barcelona-barcelona').
country = es	optional	es · it · pt	Which Idealista market to search.
contract = sale	optional	sale · rent	Listing type.
sort = relevance	optional	relevance · newest · price_low · price_high	Result ordering.
home_type	optional	apartment	Restrict to a property type.
page = 1	optional	1–	Result page (≈30 listings per page; paginate with page += 1).
price_min	optional	0–	Minimum price in EUR (sale price, or monthly rent when contract=rent).
price_max	optional	0–	Maximum price in EUR.
rooms_min	optional	1–10	Minimum number of bedrooms. 3 = 3+.
surface_min	optional	0–	Minimum living surface in square metres (m²).

Try in playground →

post/idealista/v1/detail2 credits

Full record for a single listing by its Idealista id (the number in an idealista.com/inmueble/<id>/ URL, or a search result's `id`). Returns title, price, address, bedrooms, bathrooms, surface, year built, the full feature list, description and all gallery image URLs.

Parameter		Allowed / range	Description
id	required	—	Idealista listing id (the number in an idealista.<tld>/inmueble/<id>/ URL, or a search result's `id`).
country = es	optional	es · it · pt	Which Idealista market to search.

Try in playground →

post/idealista/v1/geographyfree

Resolve a free-text place name to the Idealista location slug + a ready-to-use search preview (the count of active listings there). Use it to confirm a location before searching, or to discover the exact slug a city resolves to.

Parameter		Allowed / range	Description
query	required	—	Free-text place in the selected country to resolve ('Madrid', 'Roma', 'Lisboa').
country = es	optional	es · it · pt	Which Idealista market to search.
contract = sale	optional	sale · rent	Listing type.

Try in playground →

Example request · search

curl -X POST https://api.reefapi.com/idealista/v1/search \
  -H "x-api-key: $REEF_KEY" \
  -H "content-type: application/json" \
  -d '{"location":"Madrid","country":"es"}'

Response shape

{
  "ok": true,
  "data": { /* the result */ },
  "meta": {
    "latency_ms": 240,
    "record_count": 12,
    "completeness_pct": 100
  },
  "error": null
}