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
}