List Homes for Sale or Rent with 50+ Filters
View all Idealista Property Listings API for Spain, Portugal & Italy endpoints →Returns one page of Idealista home listings (Buy/Rent > Homes) for a single location. Required inputs: locationId (an Idealista location ID such as 0-EU-ES-28-07-001-079, resolved with the suggestions and sublocations endpoints), location (country site: es, pt or it), locale (language of the ads: es, it, pt, en, ca, de, fr, nl or nb), operation (sale or rent), order (one of twelve sort orders from relevance to lowestfloors), maxItems (page size, default 30, documented maximum 40, 0 returns only the count) and numPage (page number, 1 in the example). Optional inputs add minPrice and maxPrice bounds, minSize and maxSize bounds in m2, a publication window through sinceDate (T last 24h for rent only, Y last 48h for sale only, W last week, M last month), an agency filter through micrositeShortName, a furnished option for rentals, and 49 boolean flags covering property type, bedrooms, bathrooms, building features, sale conditions and rental terms. Boolean flags are only ever sent as true; omit a flag to leave it unfiltered. Observed in a live probe (sale search, locale es, location es, maxItems 5, numPage 1, order relevance, no filters): HTTP 200 with a JSON object holding elementList (the listing cards), total, totalPages, actualPage, itemsPerPage, numPaginations, summary, filter, alertName, totalAppliedFilters, searchTitle, geoReach, lowerRangePosition, upperRangePosition and paginable. Each probed listing card carried propertyCode, url, price, priceInfo, priceByArea, propertyType, operation, size, rooms, bathrooms, floor, exterior, address, province, municipality, district, neighborhood, locationId, latitude, longitude, numPhotos, thumbnail, multimedia (images, videos, virtual3DTours), contactInfo (agency name, user type, contact method, micrositeShortName), a features object and price-drop fields such as priceDropValue and priceDropPercentage. Rent searches, filtered searches, the maxItems=0 count mode and flag combinations were not exercised by that probe, so their behavior is taken from the parameter reference and is unverified here; no response schema is attached, so confirm field presence on a live response before mapping.
API Features
Live API Demo
🔒 Sign in to try it live
Log in to call this API with your own API key. New accounts get 100 free credits — no card required.
Log in / Sign upNo active API key found. Create one in your Dashboard, then reload this page. Dashboard →
/api/project/idealista/list-home-properties API Response (JSON)
{} curl -X GET 'https://api.opendata-api.com/api/project/idealista/list-home-properties?key=<API_KEY>&locale=es&location=es&locationId=<locationId>&maxItems=30&numPage=<numPage>&operation=sale&order=relevance'
Query Result
Use Cases
- Neighbourhood rent tracker: run the same filtered rent search every week for one district and store total and asking prices to chart the trend.
- Relocation feed for pet-friendly or unfurnished rentals: combine petsAllowed or furnished with bedroom flags and a price ceiling, using maxItems=0 counts to compare with the unfiltered total.
- Distressed-asset investor screen: scan sale listings flagged with isTenanted, isIllegallyOccupied, isBareOwnership or bankOffer and rank them by priceByArea.
- Short-term versus long-term rental comparison: run shortTerm and longTermResidential searches for the same locationId and compare how many homes each returns.
- New-listing alert bot: poll with sinceDate set to W or T and order set to mostrecent, and de-duplicate on propertyCode to push only unseen homes.
- Price-reduction watcher: sort sale results by highestpricereduction and read priceDropValue and priceDropPercentage to flag motivated sellers.
- Luxury segment report: combine luxury, villaType, penthouse, swimmingPool and garden to size the high-end market in a given municipality.
- Remote-buyer shortlist: set virtualTour and keep homes that expose virtual3DTours so overseas buyers can pre-screen without travelling.
Frequently asked questions
Which parameters are required for the home listings search?
Seven query parameters are required: locationId, location, locale, operation, order, maxItems and numPage. The other 56 parameters are optional filters, 49 of them booleans.
How do I get a locationId?
Resolve a place name with the suggestions endpoint and drill down from a city to its districts with the sublocations endpoint. The documented example is 0-EU-ES-28-07-001-079, which the probe used and which returned a Madrid result set.
How do the boolean filters work?
Send a flag as true to apply it and leave it out to ignore it; the reference says false is expressed by omitting the parameter. How several flags combine, for example whether two property types are OR-ed or AND-ed, is not documented, so test the combinations you rely on.
Which filters only work for rentals or only for sales?
furnished, petsAllowed, shortTerm and longTermResidential are documented as rent-only. For sinceDate, T (last 24h) is rent-only and Y (last 48h) is sale-only, while W (last week) and M (last month) have no stated restriction.
What do the flat and chalet flags include?
flat returns flats, penthouses and duplex together, and chalet returns independent houses, semi-detached houses, terraced houses and country houses together. The narrower flags (penthouse, duplex, independantHouse, semidetachedHouse, terracedHouse, countryHouse) pick one type.
How many listings can I request per page, and how do I page?
maxItems defaults to 30 with a documented maximum of 40; larger values are ignored. Increase numPage to move through pages, using totalPages and actualPage from the response. The probe used maxItems 5 and numPage 1.
What does maxItems=0 do?
The reference says 0 returns the item count with a fast response. The probe did not exercise it, so check a live response for the exact shape before depending on it.
Which response fields were actually observed?
The probed sale search returned elementList, total, totalPages, actualPage, itemsPerPage, numPaginations, summary, filter, alertName, totalAppliedFilters, searchTitle, geoReach, lowerRangePosition, upperRangePosition and paginable. Cards included propertyCode, price, size, rooms, bathrooms, coordinates, url, multimedia and contactInfo. No response schema is attached, so rent results and filtered results are not confirmed.
Can I list the homes of a single agency?
Yes, set micrositeShortName to the agency's microsite short name, which is the last path segment of its professional page, for example cajal-gestion-inmobiliaria. Cards in the probe also carry contactInfo.micrositeShortName; whether the filter expects that same value is not documented, so verify it on a live call.
Which sort orders are available?
order accepts relevance, lowestprice, highestprice, mostrecent, leastrecent, highestpricereduction, lowestpricem2, highestpricem2, biggest, smallest, highestfloors and lowestfloors. Send exactly one.