Hello and welcome to Idealista Unofficial API. This API requests live data from Idealista app, so you can get updated and real-time data from the platform.

Subscribe to Basic plan for free

You can test the API without paying! Simply subscribe to BASIC plan and enjoy 200 requests per month for free. If you like the API, you can purchase another plan later on.

Getting Location Suggestions (Auto Suggestions)

To start getting ads from the API, you first need to get a location ID. Idealista offers an auto suggestion feature where you can type any prefix and returns location suggestions as you type. For example, if we want to get ads from “Madrid” in Spain, you’d type: madrid. We also need to set the location to Spain (es), Italy (it) or Portugal (pt).

Required Parameters:

• prefix: any location search.
• location: es, it or pt.
• propertyType: by default homes. Change this if you want to get the number of properties available at the suggested locations based on the type of property (the number you see on the right).

Response: JSON object that contains an array of objects named “locations”. The objects inside that array have these fields:

• name
• locationId: this one is the important parameter! Location ID.
• divisible: true|false. If true means the location contains sublocations inside.
• type
• suggestedLocationId
• subTypeText: subtype text as shown in app.
• total: number of properties that are available on this location.

Getting Properties from a Location

Once we have the location ID, we can start scraping some ads. We have 2 types of endpoints:

• Listing Properties: endpoints that return a specific type of property. Examples are “new homes”, “homes”, “rooms”, “offices”, etc. Here we use the “locationId” we retrieved previously on the suggestions.
• Property Details: get extra details about a property. Some data such as postal code is not available only on the “listing” request. For extracting that data, you should call this endpoint with the property ID.

All listing properties endpoints use pagination, meaning you need to set numPage to 1 and increment it as you need new data. Each request by default gets 40 ads that include most of the property’s information. You can change the number of ads returned in each request by changing the maxItems parameter. If you set maxItems to 0, you get the number of ads available.

Response: JSON object that contains the search data. This object contains the following fields:

• elementList: array containing 40 properties (or less if no more ads are available). Inside each property you can find many details such as price, contact info, photos URL and many more! We recommend using a JSON parser to find out the parameters you’d like to get: https://jsonformatter.curiousconcept.com/
• total: number of ads available.
• totalPages
• actualPage
• itemsPerPage
• summary: here you can check the filters are as you wanted.

Retrieve only up to 50 pages per Location!!

It is known that Idealista returns random entries once the numPage parameter goes beyond 50 (40 entries per request * 50 pages = 2000 ads). This is due to the fact that it has an anti-scraping system when you try to get 2000 ads or more (they assume a normal user won’t go that far away). Therefore, if you would like to get all the ads in a location with over 2000 ads you MUST divide the locations into sublocations and then perform a recursive search.

Filters

Listing properties endpoints have associated filters. The filters change depending on the type of property to search. Most of the filters are BOOLEAN type meaning it’s true or false. If it’s a STRING, read the instructions associated to the parameter.

Please follow the rules in every filter param because otherwise Idealista will return an error.

Contact us

Go to tab Discussions and open a ticket if you have any problem or question with the API’s usage.