# Idealista Search

## Overview

| Property | Value |
|----------|-------|
| **Status** | active |
| **Method** | `GET` |
| **Endpoint** | `/v2/idealista/search` |
| **Base URL** | `https://api.piloterr.com` |
| **Credit Cost** | 2 credits per call |
| **Documentation** | https://www.piloterr.com/library/idealista-search |

## Description

Search Idealista listings from a search URL and retrieve prices, specs, photos, agency info, and pagination.

## Authentication

- **Key Name:** `x-api-key`
- **Location:** HTTP Header
- **Get an API key:** https://app.piloterr.com/register

## Example Request

```bash
curl --location --request GET 'https://api.piloterr.com/v2/idealista/search' \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: YOUR_API_KEY'
```

## Example Response

### Search homes for sale in La Barceloneta, Barcelona

```json
{
  "results": [
    {
      "link": "https://www.idealista.com/fr/inmueble/111463799/",
      "price": 1650000,
      "title": "Appartement - Calle de Guzmán el Bueno, Gaztambide, Madrid",
      "details": [
        "4 ch.",
        "190 m²",
        "4ème étage logement sur rue avec ascenseur"
      ],
      "picture": "https://img4.idealista.com/blur/480_360_mq/0/id.pro.es.image.master/e7/b4/e6/1437388651.jpg",
      "currency": "€",
      "description": "Appartement de Luxe à Chamberí - Madrid | 190 m² | 4 ChambresDécouvrez votre nouveau chez-vous dans l'un des quartiers les plus exclusifs de Madrid! Nous vous présentons cet appartement spectaculaire de 190 m², entièrement rénové à neuf, situé dans la prestigieuse rue Guzmán el Bueno, au cœur de Chamberí. Situé au qu",
      "listing_company": "Hills Properties",
      "parking_included": false,
      "listing_company_url": "https://www.idealista.com/fr/pro/hillspropertiesbcn/"
    },
    {
      "link": "https://www.idealista.com/fr/inmueble/109948217/",
      "price": 968000,
      "title": "Appartement - Calle de Gaztambide, 39, Gaztambide, Madrid",
      "details": [
        "3 ch.",
        "126 m²",
        "1er étage logement sur rue avec ascenseur"
      ],
      "picture": "https://img4.idealista.com/blur/480_360_mq/0/id.pro.es.image.master/a9/12/99/1391364999.jpg",
      "currency": "€",
      "description": "Découvrez votre nouveau chez-vous au cœur du quartier de Gaztambide! Ce spectaculaire appartement, entièrement rénové et neuf, dispose de 126 m² construits qui offrent une ambiance lumineuse et accueillante. Avec 3 chambres et 2 salles de bain (dont une en suite), cet espace est idéal pour les familles ou pour ceux qui",
      "listing_company": "Gilmar Chamberi - Argüelles",
      "parking_included": false,
      "listing_company_url": "https://www.idealista.com/fr/pro/gilmarchamberi/"
    },
    {
      "link": "https://www.idealista.com/fr/inmueble/109948315/",
      "price": 1795000,
      "title": "Penthouse - Calle de Fernando el Católico, Gaztambide, Madrid",
      "details": [
        "4 ch.",
        "230 m²",
        "6ème étage logement sur rue avec ascenseur"
      ],
      "picture": "https://img4.idealista.com/blur/480_360_mq/0/id.pro.es.image.master/b5/00/c4/1391354207.jpg",
      "currency": "€",
      "description": "Découvrez ce spectaculaire penthouse situé dans le quartier prisé de Gaztambide, dans le district de Chamberí, à Madrid. Une propriété qui combine élégance, espace et possibilités infinies dans l'un des quartiers les plus exclusifs de la capitale. Avec une superficie construite de 230 m² et une impressionnante terrasse",
      "listing_company": "Gilmar Chamberi - Argüelles",
      "parking_included": false,
      "listing_company_url": "https://www.idealista.com/fr/pro/gilmarchamberi/"
    }
  ],
  "pagination": {
    "next": 2,
    "current": 1,
    "other_pages": [
      2,
      3,
      4,
      5,
      6
    ],
    "total_pages": 6,
    "has_next_page": true
  }
}
```

## Documentation

## Overview
Extract property listings from any Idealista search results page. Returns structured listings with price, title, details, thumbnail, agency info, parking flag, and pagination metadata via browser rendering.

## Quickstart
```
GET https://api.piloterr.com/v2/idealista/search?query=https://www.idealista.com/venta-viviendas/barcelona/ciutat-vella/la-barceloneta/
```

## Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| `query` | string | yes | Full Idealista search URL |

## Response fields
| Field | Type | Description |
|---|---|---|
| `results` | array | List of property listings |
| `results[].link` | string | Property detail URL |
| `results[].price` | integer \| null | Listing price |
| `results[].title` | string \| null | Listing title |
| `results[].details` | array | Short specs (bedrooms, surface, floor); may be empty |
| `results[].picture` | string | Thumbnail image URL |
| `results[].currency` | string \| null | Currency symbol (e.g. `€`) |
| `results[].description` | string \| null | Truncated listing description |
| `results[].listing_company` | string \| null | Agency name |
| `results[].listing_company_url` | string \| null | Agency profile URL |
| `results[].parking_included` | boolean | Whether parking is included |
| `pagination.current` | integer | Current page number |
| `pagination.next` | integer \| null | Next page number |
| `pagination.total_pages` | integer | Total pages |
| `pagination.other_pages` | array | Other available page numbers |
| `pagination.has_next_page` | boolean | Whether a next page exists |

## Notes
- Response is returned under `results` with a `pagination` object.
- Only full Idealista search URLs are accepted as `query`.
- Some cards may return partial data (`price`, `title`, `currency`, or `description` as `null`).
- `details` may be an empty array on incomplete cards.
- `listing_company` and `listing_company_url` may be `null` on private listings.
- Pass a property detail URL to the Idealista Property endpoint for full listing data.

## Main use cases
- Monitor for-sale inventory in Spanish and European markets
- Build lead lists with price, specs, and agency attribution
- Feed property discovery pipelines for real estate analytics
- Track pagination across Idealista search result pages