# Idealista Search

Search the live Idealista catalog. property_type accepts homes, newDevelopments, bedrooms, offices, premises, transfers, buildings, storageRooms, garages, vacationRentals, luxury, and lands. Country routes the request to ES, IT, PT, or FR. Agency stock uses microsite_short_name. Draw-area search: simplify a polygon first, then pass shape.

- **Documentation:** [https://scrappa.co/docs/idealista-api/idealista_search](https://scrappa.co/docs/idealista-api/idealista_search)
- **API group:** Idealista API
- **Endpoint:** `GET https://scrappa.co/api/idealista/search`

## Authentication

Send your Scrappa API key in the `X-API-KEY` request header. Paid endpoints also support accountless x402 payments when called without an API key.

## Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `country` | string | No | Market: es, it, pt, or fr. Default es. |
| `operation` | string | No | sale or rent. Room stock uses bedrooms + rent. |
| `property_type` | string | No | Live typology enum. Rejected aliases: rooms, warehouses, chalets, countryhouses, vacationRental. |
| `location_id` | string | No | Idealista location id, for example 0-EU-ES-28. |
| `center` | string | No | lat,lon for near-me search. |
| `distance` | integer | No | Radius in meters when using center. |
| `max_items` | integer | No | Page size honored by origin, 1-5. |
| `num_page` | integer | No | 1-based page number. |
| `microsite_short_name` | string | No | Anonymous agency stock filter, for example clikalia. |
| `chalet` | boolean | No | Apply-filter key. Send true on homes. |
| `current_occupation_type` | string | No | free, bareOwnership, tenanted, illegallyOccupied, or viager. |
| `auction` | string | No | IT only: onlyAuctions or excludeAuctions. |

## Example request

```bash
#!/bin/bash

curl -X GET \
    -H "x-api-key: YOUR_API_KEY_HERE" \
    "https://scrappa.co/api/idealista/search?country=es&operation=sale&property_type=homes&location_id=0-EU-ES-28&max_items=2"
```

## Example response

```json
{
    "success": true,
    "data": {
        "total": 30190,
        "elementList": [
            {
                "propertyCode": "110308026",
                "price": 250000
            }
        ]
    }
}
```

## Errors

| Status | Error | Description |
| --- | --- | --- |
| 404 | Not Found | The requested listing, zone, or agency was not found. This response is not billable. |
| 422 | Validation Error | A public parameter is invalid, including rejected property types. This response is not billable. |
| 503 | Service Unavailable | The service could not obtain a complete result. This response is not billable. |

## More Scrappa resources

- [API documentation](https://scrappa.co/docs)
- [Full LLM-readable API reference](https://scrappa.co/llms-full.txt)
- [OpenAPI specification](https://scrappa.co/docs/api.json)
- [Pricing](https://scrappa.co/pricing)