# Idealista API scraper — Spain, Italy & Portugal real estate data: for-sale and for-rent property listings from idealista.com / idealista.it / idealista.pt with full filters (price EUR, bedrooms, surface m², property type, sort), each listing with price, rooms, bathrooms, surface, floor, features and photo, plus a full per-listing detail record (address, year built, description, gallery) — no API key required

> 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.
> ReefAPI engine `idealista` · 3 endpoints · clean JSON, no scraping or browsers to manage.

## How to call
- **Endpoint:** `POST https://api.reefapi.com/idealista/v1/<action>` with a JSON body.
- **Auth:** header `x-api-key: <YOUR_REEFAPI_KEY>` — create one free (1,000 credits, no card): https://reefapi.com/signup
- **Response (every call):** `{ ok: boolean, data: ..., meta: { record_count, credits, ... }, error: { code, message } }` — branch on `ok`. Failed or blocked calls are free.
- **One key + one shared credit pool** across every ReefAPI API. Per-call credits are listed on each endpoint below.
- **Use it from an AI agent (MCP):** connect `https://api.reefapi.com/mcp` (remote streamable-http, `Authorization: Bearer <key>`) and your assistant can call these actions directly.

## Endpoints

### POST /idealista/v1/search — 2 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.

**Parameters:**
- `location` (string, 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` (enum, optional, default "es") — Which Idealista market to search. [one of: es, it, pt]
- `contract` (enum, optional, default "sale") — Listing type. [one of: sale, rent]
- `sort` (enum, optional, default "relevance") — Result ordering. [one of: relevance, newest, price_low, price_high]
- `home_type` (enum, optional) — Restrict to a property type. [one of: apartment]
- `page` (integer, optional, default 1) — Result page (≈30 listings per page; paginate with page += 1).
- `price_min` (integer, optional) — Minimum price in EUR (sale price, or monthly rent when contract=rent).
- `price_max` (integer, optional) — Maximum price in EUR.
- `rooms_min` (integer, optional) — Minimum number of bedrooms. 3 = 3+.
- `surface_min` (integer, optional) — Minimum living surface in square metres (m²).

**Returns:** results[]{id, url, title, price, currency, rooms, bathrooms, surface_m2, floor, features[], thumbnail_url} + total + count + page + country + filters_applied

**Example request body:**
```json
{
  "location": "Madrid",
  "country": "es"
}
```

### POST /idealista/v1/detail — 2 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.

**Parameters:**
- `id` (string, required) — Idealista listing id (the number in an idealista.<tld>/inmueble/<id>/ URL, or a search result's `id`).
- `country` (enum, optional, default "es") — Which Idealista market to search. [one of: es, it, pt]

**Returns:** listing{id, url, title, address, price, currency, rooms, bathrooms, surface_m2, year_built, features[], description, images[], image_count}

### POST /idealista/v1/geography — 0 credits
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.

**Parameters:**
- `query` (string, required) — Free-text place in the selected country to resolve ('Madrid', 'Roma', 'Lisboa').
- `country` (enum, optional, default "es") — Which Idealista market to search. [one of: es, it, pt]
- `contract` (enum, optional, default "sale") — Listing type. [one of: sale, rent]

**Returns:** location{query, slug, country, total_listings, url} + ok

**Example request body:**
```json
{
  "query": "Madrid",
  "country": "es"
}
```

## More
- Try it live, no code: https://reefapi.com/playground?engine=idealista
- Human docs page: https://reefapi.com/docs/idealista
- Every ReefAPI API in one file (for your AI): https://reefapi.com/llms-full.txt