--- title: "Idealista API: Spanish Property Listings as JSON" description: "Search Idealista listings in Spain as JSON with one GET call: 1 credit per call, location IDs, price and size filters, and a real recorded response." url: https://perceptlayer.com/blog/idealista-api-property-listings --- [Blog](https://perceptlayer.com/blog) / [API guides](https://perceptlayer.com/blog/category/api-guides) # Idealista API: Spanish Property Listings as JSON 10 Sept 2026 Perceptlayer 7 min read You can get Idealista property listings as JSON with `GET /v1/idealista/search`. Pass `country=es`, an `operation` (sale or rent), a `property_type` and optionally a `location_id`, and send your key in the `X-API-Key` header. Each successful call costs 1 credit, failed calls cost nothing, and the free tier gives you 1,000 credits a month. The recorded response below comes from the sibling `map-search` endpoint, since we have no recorded `search` response. ## Key takeaways - `GET /v1/idealista/search` needs three parameters: `country`, `operation` and `property_type`. Add `location_id` to scope it to a province, city or neighbourhood. - The Idealista API in the [Perceptlayer catalogue](https://perceptlayer.com/apis/idealista) has 22 endpoints, and every one costs 1 credit per successful call. - The recorded `map-search` response (no `search` sample is recorded) has named fields such as `price`, `size`, `rooms`, `priceByArea`, `latitude`, `longitude` and `locationId`. - `locations` takes a `prefix` or `coordinates` and a `mode`; `locationId` appears in the recorded listings, and `location_id` is the filter parameter. - Check the terms on [idealista.com](https://www.idealista.com) before deciding. If you want a call today, a key here needs only a verified email and no credit card. ## How do you get Idealista listings as JSON? Call the search endpoint with a country, an operation and a property type. You get the listings that match, with price, size, rooms, address and coordinates as named JSON fields instead of HTML you'd have to parse. The request below asks for sale listings of type `homes` in the Madrid province ( `0-EU-ES-28`), with `max_items=2` set. ```bash curl "https://api.perceptlayer.com/v1/idealista/search?country=es&operation=sale&property_type=homes&location_id=0-EU-ES-28&max_items=2" \ -H "X-API-Key: $API_KEY" ``` You need a key that starts with `sk_live_`. [Get a free API key](https://perceptlayer.com/signup) by verifying an email address, with no credit card. The [authentication docs](https://docs.perceptlayer.com/authentication) cover the header and the `api_key` query parameter for clients that can't set headers. Prefer clicking first? The [Idealista API page](https://perceptlayer.com/apis/idealista) has a playground where you pick an endpoint, fill in the parameters and run a real call with your key. ## Which parameters does the search endpoint take? `search` takes three required parameters and a long list of optional filters. The required ones are `country`, `operation` and `property_type`. Everything else narrows the result: place, price, size, rooms, advertiser and sort order. The same parameter set applies to `map-search` (which also needs `mode`, `listings` or `pins`), `map-georeach` and `map-tiles` (which also needs `z`, `x` and `y`, all integers). | Parameter | Type | Required | Values or notes | | --- | --- | --- | --- | | `country` | string | yes | `es`, `it`, `pt`, `fr` | | `operation` | string | yes | `sale`, `rent` | | `property_type` | string | yes | `homes`, `newDevelopments`, `bedrooms`, `offices`, `premises`, `transfers`, `buildings`, `storageRooms`, `garages`, `vacationRentals`, `luxury`, `lands` | | `location_id` | string | no | Up to 80 characters | | `center`, `distance` | string, integer | no | Search around a point | | `min_price`, `max_price` | integer | no | Price range | | `min_size`, `max_size` | integer | no | Size range | | `min_rooms`, `max_rooms` | integer | no | Room range | | `sort`, `order` | string | no | `sort` is `asc` or `desc`; `order` is up to 40 characters | | `max_items`, `num_page` | integer | no | Integers; check the playground for how they behave | | `auction` | string | no | `onlyAuctions`, `excludeAuctions` | | `current_occupation_type` | string | no | `free`, `bareOwnership`, `tenanted`, `illegallyOccupied`, `viager` | | `chalet` | boolean | no | Chalet filter | | `advertiser_type`, `home_type`, `bank_offer` | string | no | Up to 40 characters each | | `shape` | string | no | Search inside an area | | `quality`, `gallery`, `locale` | string, boolean, string | no | `quality` is `high` or `low`; `locale` is up to 8 characters | The country list shows the endpoints cover more than Spain: `it`, `pt` and `fr` are accepted too. This post sticks to `es`. ## How do you find a location ID? Use `GET /v1/idealista/locations`. It takes `country` and `mode`, where `mode` is one of `suggest`, `reverse`, `vacational`, `picker` or `smart`. Pass a `prefix` with a place name, or `coordinates`, to look a place up. We have no recorded `locations` response, so check the [playground](https://perceptlayer.com/apis/idealista) for the exact shape before wiring it to `location_id` in other calls. | Parameter | Required | Notes | | --- | --- | --- | | `country` | yes | `es`, `it`, `pt`, `fr` | | `mode` | yes | `suggest`, `reverse`, `vacational`, `picker`, `smart` | | `prefix` | no | Text to match, up to 80 characters | | `coordinates` | no | Up to 40 characters | | `property_type`, `operation` | no | Same values as `search` | | `locale`, `language` | no | Up to 8 characters each | | `filter`, `location_id` | no | Up to 80 characters each | ```bash curl "https://api.perceptlayer.com/v1/idealista/locations?country=es&mode=suggest&prefix=Pozuelo" \ -H "X-API-Key: $API_KEY" ``` The recorded response below shows the ID format. The request used `0-EU-ES-28` for Madrid province, and a listing in Pozuelo de Alarcón carries `0-EU-ES-28-02-003-115-07-001` as its `locationId`. To look at one place, `GET /v1/idealista/location` takes `country` and `location_id`. ## What does a listing response look like? Each listing is one object in `data.elementList`, next to paging fields such as `total` and `totalPages`. The excerpt below is a recorded response from `GET /v1/idealista/map-search` with `mode=listings`, trimmed with `…`. We have no recorded `search` response, so treat these fields as what `map-search` returned and confirm them on `search` in the playground. It was requested like this: ```bash curl "https://api.perceptlayer.com/v1/idealista/map-search?country=es&mode=listings&property_type=homes&operation=sale&location_id=0-EU-ES-28" \ -H "X-API-Key: $API_KEY" ``` ```json { "success": true, "data": { "elementList": [ { "propertyCode": "110108160", "externalReference": "CA217051", "numPhotos": 33, "price": 2200000, "priceInfo": { "price": { "amount": 2200000, "currencySuffix": "€", "priceDropInfo": "…" } }, "propertyType": "chalet", "operation": "sale", "size": 480, "rooms": 5, "bathrooms": 5, "address": "Chalet pareado en Paseo Club Deportivo, La Finca, Pozuelo de Alarcón", "province": "Madrid", "municipality": "Pozuelo de Alarcón", "district": "Zona Prado de Somosaguas - La Finca", "country": "es", "neighborhood": "La Finca", "locationId": "0-EU-ES-28-02-003-115-07-001", "latitude": 40.4173893, "longitude": -3.8060585, "url": "https://www.idealista.com/inmueble/110108160/", "priceDropValue": 200000, "priceDropPercentage": 8, "priceByArea": 4583, "features": { "hasSwimmingPool": true, "hasTerrace": true, "hasAirConditioning": true, "hasBoxRoom": true, "hasGarden": true }, "detailedType": { "typology": "chalet", "subTypology": "semidetachedHouse" }, "…": "…" } ], "total": 33943, "totalPages": 16972, "actualPage": 1, "itemsPerPage": 2, "summary": [ "Comprar casas y pisos en Madrid provincia", "Todos los precios" ], "searchTitle": "Madrid provincia", "paginable": true }, "meta": { "duration_ms": 764, "endpoint_family": "map_search" } } ``` A few fields are worth knowing. The first listing has `price` 2200000, `size` 480 and `priceByArea` 4583; the field isn't documented, but those numbers are consistent with price divided by size, so check that on your own data. The same listing has `priceDropValue` 200000 and `priceDropPercentage` 8, and we don't document what they mean beyond their names. `locationId` is on each listing, so you can group results by it. `total` and `totalPages` show how large the result set is, so you can estimate the credits before paging. Listings also include contact details for the advertising agency. That's business data, but treat it with care: don't use it to contact people in bulk without a lawful basis. Data is collected from publicly available sources and returned as found at the time of the call. ## Which other endpoints take a listing or location? Four more endpoints are worth a look: `filters`, `listing-stats`, `home` and `listing`. We have no recorded response for any of them, so this section lists only their parameters. Each costs 1 credit per successful call. The [Filters](https://perceptlayer.com/apis/idealista/filters), [Listing Stats](https://perceptlayer.com/apis/idealista/listing-stats), [Home](https://perceptlayer.com/apis/idealista/home) and [Listing](https://perceptlayer.com/apis/idealista/listing) pages and the playground show what each returns. | Endpoint | Required parameters | Optional parameters | | --- | --- | --- | | `GET /v1/idealista/filters` | `country`, `operation`, `property_type`, `location_id` | `locale`, `quality`, `gallery` | | `GET /v1/idealista/listing-stats` | `country`, `ad_id` | `language` | | `GET /v1/idealista/home` | `country` | `locale`, `quality` | | `GET /v1/idealista/listing` | `country`, `ad_id` | `include[]`, `typology`, `from_date`, `to_date`, `guests`, `quality`, `locale`, `language`, `max_items` | `ad_id` is a required string on `listing` and `listing-stats`. The recorded listings carry a `propertyCode` such as `110108160`, but we haven't confirmed that it is the value `ad_id` expects, so test it in the playground first. `listing` accepts `include[]` values of `multimedia`, `comment`, `stats` and `recommendation`. ## What does it cost? Every endpoint in the Idealista API costs 1 credit per successful call, and a failed call costs 0 and returns `X-Credits-Used: 0`. Credits come in prepaid packs that last 12 months, and the free tier gives you 1,000 credits a month. [Pricing](https://perceptlayer.com/pricing) has what credits cost; this post only counts them. A worked example: a daily check of 20 saved searches, with one `listing` call for each of 10 listings. - Searches: 20 calls × 1 credit = 20 credits a day. - Listing calls: 10 calls × 1 credit = 10 credits a day. - Over 30 days: 30 credits × 30 = 900 credits, inside the 1,000 free credits. Every response carries `X-Credits-Used` and `X-Credits-Remaining`, so you can log the balance after each call. Request limits are per account and counted per minute: free accounts get 1 request a second. The [rate limits docs](https://docs.perceptlayer.com/rate-limits) explain what happens past that, and the [errors docs](https://docs.perceptlayer.com/errors) list the codes, including `invalid_parameters` (422) for a bad filter value. The [credits docs](https://docs.perceptlayer.com/credits) cover the rest. ## How does this compare with Idealista's own API? Idealista runs a [developer access request form](https://developers.idealista.com/access-request), so the official route is by application. We haven't seen its quotas, fields or permitted uses, so we won't describe them. Here is a rule you can apply without them. - Need access under an agreement with Idealista itself, for example because your use case or your lawyers require it? Apply there and read the terms on [idealista.com](https://www.idealista.com) first. - Need JSON from the search endpoints today, with no application step? A key here needs only a verified email, no credit card, and 1,000 free credits a month. - Need Italy, Portugal or France as well as Spain? These endpoints accept `es`, `it`, `pt` and `fr`. - Need an agent to call it as a tool? The same key works over HTTP and over [MCP](https://docs.perceptlayer.com/ai-agents), and the catalogue covers 248 websites and 1,659 endpoints. You can also start here and apply for official access in parallel. For other property markets, see the [Immobilienscout24 guide](https://perceptlayer.com/blog/immobilienscout24-api-listings) and the [Rightmove guide](https://perceptlayer.com/blog/rightmove-api-property-data). Next step: [run a search in the playground](https://perceptlayer.com/apis/idealista) with your free key, then copy the cURL call into your code. ## APIs in this post - [Idealista **1 credit per call** · 22 endpoints](https://perceptlayer.com/apis/idealista) ## Frequently asked questions ### Is there an official Idealista API? Idealista has a [developer access request form](https://developers.idealista.com/access-request), so apply there if you need access under Idealista's own agreement. Perceptlayer's Idealista endpoints are a separate route: verify an email, get a key and call them the same day, with failed calls costing nothing. ### How much does an Idealista API call cost? Each successful call to any of the 22 Idealista endpoints costs 1 credit. A failed call costs nothing and returns `X-Credits-Used: 0`. Free accounts get 1,000 credits a month after verifying an email address, with no credit card. See [pricing](https://perceptlayer.com/pricing) for what credits cost. ### Can I search countries other than Spain? The `country` parameter accepts `es`, `it`, `pt` and `fr`, so the same endpoints take Italy, Portugal and France as well as Spain. The recorded `map-search` response in this post is for Spain ( `country=es`). We haven't recorded the other countries, so check them in the playground before you rely on their fields. ### How do I get more than one page of results? `num_page` and `max_items` are integer parameters; confirm how they page in the playground. The recorded `map-search` response includes `total`, `totalPages` and `actualPage`, which tell you how many pages exist. Each page is a separate call at 1 credit, so check `total` first and set a budget. Calls are counted per minute; see the [rate limits docs](https://docs.perceptlayer.com/rate-limits). ### What happens if a request fails? You get an HTTP status and a JSON body with `error.code`, `error.message` and `error.request_id`. For example, `invalid_parameters` (422) means a value was rejected, and `rate_limited` (429) carries a `Retry-After` header. Failed calls aren't billed. The [errors docs](https://docs.perceptlayer.com/errors) list every code. real estate idealista spain property listings api ## More from the blog 1. [API guides](https://perceptlayer.com/blog/category/api-guides) 1 Jul 2026 Updated 26 Oct 2026 Perceptlayer 9 min read ## [Zillow Listings API: Get Property Data as JSON](https://perceptlayer.com/blog/zillow-listings-api-json) One GET to /v1/zillow/search returns listings near a point as JSON with price, beds, baths and address. Parameters, a real response, 1 credit per call. 2. [API guides](https://perceptlayer.com/blog/category/api-guides) 15 Oct 2026 Perceptlayer 7 min read ## [Redfin API: Search Homes, Then Property and Valuation](https://perceptlayer.com/blog/redfin-api-property-valuation) Four Redfin endpoints at 1 credit each: find a region, search homes with a real JSON response, then call property and valuation by property\_id. 3. [API guides](https://perceptlayer.com/blog/category/api-guides) 8 Oct 2026 Perceptlayer 6 min read ## [Realestate.com.au API: Australian Listings as JSON](https://perceptlayer.com/blog/realestate-com-au-api-listings) Search realestate.com.au by location and channel (buy, rent, sold), then open each listing by URL. Parameters, a recorded Sydney response and the cost.