Skip to main content
Network status
Log in
Piloterr
Back to library

Idealista Provinces API

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.

Active3 credits = 1 requestGET/v2/idealista/provinces
Try endpoint for freePiloterr

Endpoint Overview

Detailed documentation, pricing, and usage examples.

OverviewLink to 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.

QuickstartLink to 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/

ParametersLink to 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 fieldsLink to 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 casesLink to 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 codesLink to 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

Related APIs

Expand your data capabilities with these complementary tools.

View All
Idealista Property/v2/idealista/property

Extract full property details from an Idealista listing URL, including price, specs, photos by room, features, energy rating, and advertiser data.

GET3 credits = 1 requestActive
Idealista Search/v2/idealista/search

Search Idealista listings from a search URL and retrieve prices, specs, photos, agency info, and pagination. Pass a province URL from `/v2/idealista/provinces` (`results[].url`) as `query`. Madrid is `https://www.idealista.com/venta-viviendas/madrid-provincia/`.

GET3 credits = 1 requestActive

Ready to get started?

Your web scraping API is one click away. Start with +500 credits, no infrastructure to set up, no proxies to manage, and no credit card required.

  • +500 credits
  • No credit card required
  • All endpoints included
Start free (+500 credits)PiloterrTalk to a data expert