Blog / API guides

Idealista API: Spanish Property Listings as JSON

10 Sept 2026Perceptlayer7 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.

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.

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 by verifying an email address, with no credit card. The authentication docs cover the header and the api_key query parameter for clients that can't set headers.

Prefer clicking first? The Idealista API page 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).

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 for the exact shape before wiring it to location_id in other calls.

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:

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"

{
  "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, Listing Stats, Home and Listing pages and the playground show what each returns.

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 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 explain what happens past that, and the errors docs list the codes, including invalid_parameters (422) for a bad filter value. The credits docs cover the rest.

How does this compare with Idealista's own API?

Idealista runs a developer access request form, 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 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, 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 and the Rightmove guide.

Next step: run a search in the playground with your free key, then copy the cURL call into your code.

real estateidealistaspainproperty listingsapi