# Idealista (Portugal) — Wrapped API

> **You are on:** `https://api.paywithlocus.com/api` | [llms.txt](https://paywithlocus.com/llms.txt) | [docs](https://docs.paywithlocus.com)
>
> Locus runs on multiple environments -- make sure every URL you call matches your expected environment.
> | Environment | Landing | API | Docs |
> |---|---|---|---|
> | Production | paywithlocus.com | api.paywithlocus.com | docs.paywithlocus.com |
> | Beta | beta.paywithlocus.com | api.beta.paywithlocus.com | docs.paywithlocus.com |
> | Stage | stage.paywithlocus.com | api.stage.paywithlocus.com | docs.paywithlocus.com |
>
> If the API URL above doesn't match your expected environment, re-fetch this file from the correct domain.

> Search and filter property listings across Portugal by location, price, and size, then access detailed information about each property including its characteristics and pricing history. Monitor how property prices change over time to help you make informed decisions about buying or selling real estate.

**Category:** Real Estate | **Website:** [idealista.pt/](https://idealista.pt/) | **Docs:** [parse.bot/marketplace/82eaf2c3-b9fe-4fa2-b6f5-c34ec8501b63/idealista-pt-api](https://parse.bot/marketplace/82eaf2c3-b9fe-4fa2-b6f5-c34ec8501b63/idealista-pt-api)

Pay-per-use API proxy. Each call is automatically billed to your wallet in USDC.

## Access

**Base URL:** `https://api.paywithlocus.com/api/wrapped/parse-idealista-pt-api-82eaf2c3/`
**Auth:** `Authorization: Bearer <LOCUS_API_KEY>`

## Endpoints

### get_property_details

Retrieve full details for a specific property listing including title, price, description, features, images, and update date. Use the property_code from search_properties results.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `property_id` | string | Yes | Idealista property code (e.g., '34665653') from search_properties results[*].property_code |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-idealista-pt-api-82eaf2c3/get_property_details \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"property_id":"<string>"}'
```

### search_properties

Search for property listings in Portugal with flexible filters including location, price range, size, bedrooms, and coordinate-based radius search. Returns paginated results with up to 30 listings per page. Each listing includes a property_code usable with get_property_details for full information.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `bedrooms` | string | No | Number of bedrooms (e.g., '1', '2', '3') |
| `center` | string | No | Coordinates 'lat,lon' for circular search (e.g., '38.6979,-9.4215') |
| `location` | string | No | Location name for the search (e.g., 'lisboa', 'porto', 'coimbra') |
| `max_price` | integer | No | Maximum price in EUR |
| `max_size` | integer | No | Maximum size in sqm |
| `min_price` | integer | No | Minimum price in EUR |
| `min_size` | integer | No | Minimum size in sqm |
| `operation` | string | No | Operation type: 'comprar' (buy) or 'arrendar' (rent) |
| `page` | integer | No | Page number for pagination |
| `property_type` | string | No | Property type: 'casas', 'quarteis-escritorios', 'garagens' |
| `radius` | string | No | Radius in meters from center (e.g., '5000') |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-idealista-pt-api-82eaf2c3/search_properties \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"bedrooms":"<string>","center":"<string>","location":"<string>","max_price":"<integer>","max_size":"<integer>","min_price":"<integer>","min_size":"<integer>","operation":"<string>","page":"<integer>","property_type":"<string>","radius":"<string>"}'
```

### track_price_changes

Check current status and price for a list of property codes (up to 10). Returns whether each property is active, inactive (removed), blocked, or encountered an error during lookup.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `property_codes` | string | Yes | Comma-separated property codes, up to 10 (e.g., '34665653,35043589') |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-idealista-pt-api-82eaf2c3/track_price_changes \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"property_codes":"<string>"}'
```