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

Sale and rent home search by location ID Search any Idealista area with locationId, such as 0-EU-ES-28-07-001-079, and switch between sale and rent with operation. IDs come from the suggestions and sublocations endpoints, so a city can be narrowed to a district.
Property-type flags with group shortcuts Flags such as flat, penthouse, duplex, chalet, villaType, countryHouse, loftType, atticStudioType and cortijoType select home types. Setting flat returns flats, penthouses and duplex together, and chalet returns independent, semi-detached, terraced and country houses together.
Building and comfort amenity filters Narrow results to homes with airConditioning, swimmingPool, garden, terrance, garage, elevator, exterior, builtinWardrobes, storeRoom or accessible, and to floor positions through topFloor and intermediateFloor.
Bedroom and bathroom count flags The bedrooms0 to bedrooms4 flags and the bathrooms1, bathrooms2 and bathroom3 flags filter by room counts without needing a numeric range parameter.
Rental-only terms For operation=rent, furnished accepts furnished or furnishedKitchen, petsAllowed keeps pet-friendly homes, and shortTerm or longTermResidential separate seasonal from long-term lets.
Special-situation sale flags isTenanted, isIllegallyOccupied, isBareOwnership, bankOffer and isFree surface or exclude properties sold under tenancy, occupation, bare-ownership or bank-offer conditions.
Listing cards with price, location and media In the probed response each elementList card exposes propertyCode, price and priceByArea, size, rooms, bathrooms, address, latitude and longitude, url, photo, video and virtual-tour data, plus contactInfo for the advertiser.
Twelve sort orders with page and count controls order ranks by relevance, price, price per m2, size, floor, recency or price reduction. numPage and maxItems page through results, and maxItems=0 is documented to return just the count, with total and totalPages in the response.

Live API Demo

GET /api/project/idealista/list-home-properties

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-home-properties?key=<API_KEY>&locale=es&location=es&locationId=<locationId>&maxItems=30&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

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.

Related operations

Guides

View Subscription Plans →