List new-build homes for sale or rent on Idealista

View all Idealista Property Listings API for Spain, Portugal & Italy endpoints →

Lists new-build home properties (Buy/Rent > New home) on Idealista for one location, with optional filters. Required inputs are the country site (location: es, it or pt), the response language (locale), a locationId from the suggestions or sublocations endpoints, the operation (sale or rent), a sort order, the page number (numPage) and the page size (maxItems, up to 40; 0 returns only the item count). Optional filters cover finished new builds, rent-to-own, state-subsidized housing, bank offers, flats, houses or chalets, bedroom counts (bedrooms0 to bedrooms4, where bedrooms4 means four or more) and minPrice/maxPrice. In an observed sample call (locale=es, location=es, locationId=0-EU-ES-28-07-001-079, operation=sale, order=relevance, maxItems=5) the response was a JSON object with elementList (array of listings), total, totalPages, actualPage, itemsPerPage, numPaginations, summary, filter, alertName, totalAppliedFilters, searchTitle, lowerRangePosition, upperRangePosition and paginable. Each observed listing carried fields such as propertyCode, price, priceInfo, propertyType, operation, address, municipality, district, locationId, latitude, longitude, url, description, numPhotos, multimedia, contactInfo, newDevelopmentFinished, isRentToOwn and promoName.

API Features

Finished versus in-progress builds The finished flag restricts results to completed new homes, and every returned row exposes newDevelopmentFinished so you can split finished stock from projects still under construction.
Rent-to-own and subsidized switches rentToOwn selects rentals with a buying option and stateSubsidized selects subsidized housing; rows report isRentToOwn, which makes affordability-focused portals easy to build.
Bedroom and home-type switches Five bedroom flags (bedrooms0 to bedrooms4, with bedrooms4 meaning four or more) plus flats and housesOrChalets narrow a development search to the layouts a buyer asked for.
Bank-offer flag for lender partners bankOffer keeps only new homes flagged as bank offers, which lets mortgage and finance sites surface financeable developments without post-filtering.
Count-only fast mode Setting maxItems to 0 returns only the item count as a fast response, a cheap way to size the new-build market in a location before paging through rows.
Map-ready rows with contact type and media flags Observed listing rows include latitude, longitude, thumbnail, numPhotos, multimedia, contactInfo and promoName, enough to plot developments on a map and link to the portal page via url.
Pagination envelope Responses report total, totalPages, actualPage, itemsPerPage and paginable (for example 271 matches over 55 pages at five items per page in the sample), so crawlers know exactly when to stop.

Live API Demo

GET /api/project/idealista/list-new-homes

Request cost is temporarily unavailable. No price is assumed.

View pricing

API Response (JSON)

{}
curl -X GET 'https://api.opendata-api.com/api/project/idealista/list-new-homes?key=<API_KEY>&locale=es&location=es&locationId=<locationId>&maxItems=30%2C40&numPage=<numPage>&operation=sale&order=relevance'
📢
Need Help?
If you encounter API issues or need other API requirements, please contact us.
Contact Us

Use Cases

Frequently asked questions

What does the response contain?

In an observed call the response was a JSON object with an elementList array of listings plus total, totalPages, actualPage, itemsPerPage, numPaginations, summary, filter, alertName, totalAppliedFilters, searchTitle, lowerRangePosition, upperRangePosition and paginable. Listings carried propertyCode, price, priceInfo, address, latitude, longitude, url, contactInfo, multimedia flags, newDevelopmentFinished, isRentToOwn and promoName, among others.

How do I count new-build listings without downloading them?

Set maxItems to 0, which the parameter documentation describes as returning the item count as a fast response. The observed sample used maxItems=5 instead, so the count-only mode comes from the documentation rather than from a captured call.

How do I get only finished new homes?

Set finished to true. Leave it unset to include new builds at every stage; each row also reports newDevelopmentFinished so you can classify stock yourself.

Can I search rentals, rent-to-own or subsidized homes?

Set operation to rent for rentals and combine it with rentToOwn=true for rentals with a buying option. Set stateSubsidized=true to filter subsidized housing. Rows expose an isRentToOwn flag in the observed response.

Where do I get locationId and which country should I use?

Resolve a place name with the suggestions endpoint of this API and drill down with the sublocations endpoint. The sample ID 0-EU-ES-28-07-001-079 returned results for Madrid (filter.locationName was Madrid) with location=es. Use es, it or pt for the country that matches the ID.

How do the bedroom filters work?

bedrooms0 to bedrooms3 are separate boolean switches and bedrooms4 means four or more bedrooms. Combining several switches is expected to widen the match like a multi-select, but that behaviour was not exercised in the observed call, so test the combination you need.

What is the maximum page size and how do I paginate?

maxItems accepts up to 40; larger values are ignored. Increase numPage and stop at totalPages. In the observed sample, numPage=1 with maxItems=5 returned actualPage 1, itemsPerPage 5, total 271 and totalPages 55, so totals reflect the market at call time.

Does it identify the development behind each unit?

Observed rows include promoName and a newDevelopment flag, but no dedicated promotion identifier field was seen in the sample. Check a live response before wiring results into the promotion-units endpoint of this API.

Related operations

Guides

View Subscription Plans →