# Idealista

> Search Idealista listings in Spain, Italy and Portugal on the map beside your own, with nothing to connect.

Search Idealista in Spain, Italy and Portugal next to your own listings: on the map, in a brochure, or to look up the agency behind a home. There is nothing to connect: every agency can search Idealista within its daily property-site allowance.

## Set it up

There is no account or key to add. To search Idealista from your own code, use the `idealista` source of [Property sources](https://www.fondaro.com/docs/api/properties/sources.md) with an API key that has the `sources:read` scope:

```bash
curl -X POST https://api.fondaro.com/property-sources/idealista/search \
  -H "X-API-Key: fondaro_pk_abc123" \
  -H "Content-Type: application/json" \
  -d '{"country":"es","locationIds":["<id from /property-sources/idealista/locations>"],"maxPrice":800000,"limit":20}'
```

The routes below are the dashboard's own Idealista routes. They take a signed-in dashboard session with an active organization; a property API key is refused. The same routes exist for every property site, under its source id (for example `/rightmove/...`).

## Check availability

### `GET /idealista/status`

```json
{ "connected": true }
```

`false` only when Idealista search is switched off for everyone.

## Search the map

### `POST /idealista/search`

Deprecated: use `POST /property-sources/idealista/search`. Responses carry `Deprecation: true` and a `Link` header naming the replacement.

Send exactly one of `polygon`, `circle`, or `locationId` (or `place`).

| Field | Type | Notes |
|---|---|---|
| `polygon` | `[lon, lat][]` | A drawn area |
| `circle` | `{ lat, lon, radiusKm }` | Around a point |
| `locationId`, `place` | string | A place from autocomplete; full filters apply |
| `country` | string | `es` (default), `it` or `pt` |
| `searchType` | string | `For_Sale` (default) or `For_Rent` |
| `propertyType` | string | Comma-separated Idealista types, for example `flat,duplex` |
| `minPrice`, `maxPrice` | number | In euros |
| `minSize`, `maxSize` | integer | m² |
| `bedrooms` | integer[] | `0` studio, `1`, `2`, `3`, `4` (4 or more) |
| `amenities` | string[] | Applied on place searches only |
| `floorHeights` | string[] | `groundFloor`, `intermediateFloor`, `topFloor` |
| `sortOrder` | string | |
| `page` | integer | From 1 |

```bash
curl -X POST https://api.fondaro.com/idealista/search \
  -H "Authorization: Bearer $SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"circle":{"lat":40.4168,"lon":-3.7038,"radiusKm":2},"maxPrice":800000,"bedrooms":[3]}'
```

```json
{
  "properties": [
    {
      "id": "104588621",
      "source": "idealista",
      "price": 750000,
      "currency": "EUR",
      "latitude": 40.43,
      "longitude": -3.69,
      "externalAgency": { "name": "...", "phone": "...", "micrositeShortName": "..." },
      "deeplinkUrl": "https://www.idealista.com/inmueble/104588621/"
    }
  ],
  "total": 3165,
  "page": 1,
  "totalPages": 64,
  "pageSize": 50
}
```

## Look up places

### `GET /idealista/autocomplete`

Deprecated: use `GET /property-sources/idealista/locations`. Takes `input` and `country`.

```json
{ "locations": [{ "name": "Marbella, Málaga", "locationId": "0-EU-ES-29-...", "subTypeText": "Municipio", "total": 12345, "divisible": true }] }
```

### `GET /idealista/sublocations`

Deprecated. Takes `locationId` and `country` and goes one level down (province, municipality, district), with counts.

## Read a listing

### `GET /idealista/detail/:propertyCode`

Deprecated: use `GET /property-sources/idealista/detail/:id`. Takes `country` (`es`, `it`, `pt`) and `locale` (default `en`).

```json
{ "property": { "id": "106387165", "source": "idealista", "bedrooms": 4, "bathrooms": 5, "livingArea": 263, "energyRating": "b", "images": ["..."], "deeplinkUrl": "..." } }
```

### `POST /idealista/resolve`

Turns a pasted Idealista link (`.com`, `.es`, `.it`, `.pt`, new-build links included) or a bare property code into the full listing. The country comes from the link; a bare code means Spain.

```bash
curl -X POST https://api.fondaro.com/idealista/resolve \
  -H "Authorization: Bearer $SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"input":"https://www.idealista.com/inmueble/106387165/","locale":"en"}'
```

```json
{ "property": { "id": "106387165", "source": "idealista" }, "propertyCode": "106387165", "country": "es" }
```

## Look up the agency

### `GET /idealista/agent/:micrositeShortName`

The agency behind a listing (`externalAgency.micrositeShortName`): name, phone, email, website, languages, years active and listing count. Takes `country`.

### `GET /idealista/agent/:micrositeShortName/locations`

Where that agency has listings, by province, municipality and district, with counts.

## Errors and limits

| Status | When |
|---|---|
| `400` | Missing or conflicting search area, or input that is not an Idealista link or code |
| `404` | The listing or agency does not exist or was withdrawn |
| `429` | Today's property-site allowance is used up; it resets at midnight UTC |
| `503` | Idealista did not answer properly; try again shortly |

Search, place lookups and detail each use one unit of the organization's daily property-site allowance (300 a day, shared with every other property site) when the answer is not already cached. There is no charge.

Source: https://www.fondaro.com/docs/api/idealista