# Idealista Provinces

## Overview

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

## Description

List the 50 Spanish provinces Idealista shows for homes for sale. Each row includes the sale search URL to pass as query to Idealista Search. Madrid is madrid-provincia.

## 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/provinces' \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: YOUR_API_KEY'
```

## Example Response

### Madrid province

```json
{
  "results": [
    {
      "url": "https://www.idealista.com/venta-viviendas/madrid-provincia/",
      "name": "Madrid",
      "slug": "madrid-provincia",
      "region": "Comunidad de Madrid",
      "listing_count": 34094
    }
  ]
}
```

## Documentation

## Overview
Returns the 50 Spanish provinces Idealista lists for homes for sale. Each row has a stable slug, the province name, the autonomous community, the sale-home count, and the search URL.

Pass `results[].url` as `query` to `/v2/idealista/search`. There are no parameters on this endpoint.

## Quickstart
The full province list:

```
GET https://api.piloterr.com/v2/idealista/provinces
```

Madrid, then its listings. `madrid-provincia` is the slug. The URL is the value to pass as `query` on search.

```
GET https://api.piloterr.com/v2/idealista/search?query=https://www.idealista.com/venta-viviendas/madrid-provincia/
```

## Parameters
This endpoint takes no parameters. The list comes from the Spanish Idealista homepage and covers homes for sale. The array length is 50 provinces.

## Response fields
| Field | Type | Description |
|---|---|---|
| `results` | array | 50 provinces, in the order shown on Idealista |
| `results[].slug` | string | Stable path slug, such as `madrid-provincia` or `alicante` |
| `results[].name` | string | Province name. Madrid's name is `Madrid` |
| `results[].url` | string | Homes-for-sale search URL. Pass it as `query` on `/v2/idealista/search` |
| `results[].region` | string | Autonomous community shown above the province |
| `results[].listing_count` | integer | Homes-for-sale count shown next to the province |

There is no `pagination`. The count changes over time. The Madrid URL stays `https://www.idealista.com/venta-viviendas/madrid-provincia/`.

## Use cases
- Fill a province menu, then call Idealista Search with the chosen `url`
- Store the slug and reuse the same search URL later

## Error codes
| Code | Meaning |
|---|---|
| 401 | Missing or invalid API key |
| 403 | Idealista blocked the request |
| 404 | The province list was not on the page |
| 500 | The page could not be fetched |