Idealista Property Listings API for Spain, Portugal & Italy — Try the interactive demo
A guided live test. Prefer the raw endpoints? See the API reference & playground →
Enter an API key from your Dashboard to enable the examples below. Requests send it to this platform for authentication.
Log in / Sign up · Dashboard →
Please paste your API key first.
Endpoints
Your API key is attached automatically to each call.
/api/project/idealista/get-sublocations List sublocations inside a divisible Idealista location, with listing totals per area
Details
Returns the child locations of a parent Idealista location, such as the districts or municipalities under a province, so you can drill down from a coarse place to a finer one. Send the country code (location: es, pt or it), the parent locationId (it must be a location flagged divisible=true, for example 0-EU-ES-28), and the operation and propertyType filters that decide which listings are counted in each child's total. The bedrooms property type only works together with the rent operation. In the recorded probe (location=es, locationId=0-EU-ES-28, operation=sale, propertyType=homes) the endpoint answered HTTP 200 with a JSON object holding a locations array and an integer total; each locations entry carried name, locationId, divisible, type, suggestedLocationId, subTypeText and an integer total. The endpoint returns places and counts only, never the property listings themselves.
| Parameter | In | Value |
|---|---|---|
| query | ||
| query | ||
| query | ||
| query |
Request cost is temporarily unavailable. No price is assumed.
/api/project/idealista/get-microsite-locations List the locations where an Idealista agency microsite has properties
Details
Returns the places where a given agency microsite (professional profile) has properties, so you can see the agency's coverage area. Identify the agency with micrositeShortName (the slug that appears after /pro/ in its profile address, for example sumainmobiliaria), choose the country with location (es, pt or it), the response language with locale (es, it, pt, en, ca, de, fr, nl or nb), and supply a locationId (documented example 0-EU-ES-28) and an operation (documented example sale). All five inputs are required. No successful probe was recorded for this operation, so the exact response fields are not verified here; the endpoint is documented as returning the locations where the microsite has properties, and its structure should be checked on the first call before you build parsers around it.
| Parameter | In | Value |
|---|---|---|
| query | ||
| query | ||
| query | ||
| query | ||
| query |
Request cost is temporarily unavailable. No price is assumed.
/api/project/idealista/get-microsite-profile Get an Idealista agency microsite profile with name, website, contact info and languages
Details
Returns the profile of one agency microsite, identified by micrositeShortName (the slug after /pro/ in the agency's profile address), within the countries given in location (es, pt, it; the documented default is es,pt,it). In the recorded probe (location=es, micrositeShortName=jaime-valcarce-consulting-inmobiliario) the endpoint answered HTTP 200 with a JSON object containing shortName, activeSinceYear, commercialName, agencyWebUrl, slogan, defaultTypology, defaultOperation, contactInfo (phone, a contactPhone object with formatted and dialing variants, showContactButton, proAgent and an address object with street, locality, postal code and coordinates), multimedias (mainImage and brandingLogo), an integer total, a languages array, commercialDataId, hasChatEnabled, micrositeLeadAllowed and corporatePhrase (text and autoTranslated). The profile does not include the agency's property listings.
| Parameter | In | Value |
|---|---|---|
| query | ||
| query |
Request cost is temporarily unavailable. No price is assumed.
/api/project/idealista/get-suggestions Autocomplete place names into Idealista location IDs
Details
Resolves the beginning of a place name to matching Idealista locations in Spain, Portugal or Italy. Send location (es, pt or it), operation (sale or rent), prefix (the text typed so far, for example madrid) and propertyType (homes, newDevelopments, bedrooms, offices, premises, garages, lands, storageRooms or buildings); all four are required. The response is a JSON object with a locations array and an integer total. In a live check with location=es, operation=sale, prefix=madrid and propertyType=homes, every locations entry carried name, locationId, divisible, type, suggestedLocationId, subTypeText and its own total, and the matches mixed municipalities, the Madrid province and individual districts. The per-entry total counts the properties offered for the chosen operation and property type, and the locationId values are the identifiers the listing endpoints take as their locationId input.
| Parameter | In | Value |
|---|---|---|
| query | ||
| query | ||
| query | ||
| query |
Request cost is temporarily unavailable. No price is assumed.
/api/project/idealista/list-buildings Search whole buildings on Idealista by area, price and size
Details
Returns a paged list of whole-building listings from Idealista for one location. Required inputs are locale, location (country site es, it or pt), locationId (for example 0-EU-ES-28-07-001-079 for the Madrid municipality), operation (sale or rent), order (one of twelve sort orders), maxItems and numPage. Optional inputs narrow the search with minPrice and maxPrice, minSize and maxSize, a sinceDate publication window (T, Y, W or M) and micrositeShortName to keep only one agency's buildings. No live sample or response example has been recorded for this endpoint yet, so its response fields are not listed here; inspect a response from your own request before mapping fields.
| Parameter | In | Value |
|---|---|---|
| query | ||
| query | ||
| query | ||
| query | ||
| query | ||
| query | ||
| query | ||
| query | ||
| query | ||
| query | ||
| query | ||
| query | ||
| query |
Request cost is temporarily unavailable. No price is assumed.
/api/project/idealista/list-commercial-properties List Commercial Premises for Sale or Rent
Details
Returns one page of Idealista commercial premises listings 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, it or pt), locale (language code: 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 (listed values 30, 40 and 0) and numPage (page number, 1 in the example). Optional inputs narrow the search by minPrice, maxPrice, minSize and maxSize; by publication window through sinceDate (T last 24h for rent only, Y last 48h for sale only, W last week, M last month); by agency through micrositeShortName; by premises type (premises, industrialBuilding, storehouse and three saleWarehouse flags); by business activity (for example pharmacy, catering, retail, barsAndNightclub, accommodation); and by placement (street, mezzanine, ontopfloor, underground, shoppingcenter, otherLocations). No live response sample or response schema is attached to this endpoint, so the listing fields are not verified here: inspect a live response before mapping fields. How several boolean flags combine is not documented, so test the combinations you rely on.
| Parameter | In | Value |
|---|---|---|
| query | ||
| query | ||
| query | ||
| query | ||
| query | ||
| query | ||
| query | ||
| query | ||
| query | ||
| query | ||
| query | ||
| query | ||
| query | ||
| query | ||
| query | ||
| query | ||
| query | ||
| query | ||
| query | ||
| query | ||
| query | ||
| query | ||
| query | ||
| query | ||
| query | ||
| query | ||
| query | ||
| query | ||
| query | ||
| query | ||
| query | ||
| query | ||
| query | ||
| query | ||
| query | ||
| query | ||
| query | ||
| query | ||
| query |
Request cost is temporarily unavailable. No price is assumed.
/api/project/idealista/list-home-properties List Homes for Sale or Rent with 50+ Filters
Details
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.
| Parameter | In | Value |
|---|---|---|
| query | ||
| query | ||
| query | ||
| query | ||
| query | ||
| query | ||
| query | ||
| query | ||
| query | ||
| query | ||
| query | ||
| query | ||
| query | ||
| query | ||
| query | ||
| query | ||
| query | ||
| query | ||
| query | ||
| query | ||
| query | ||
| query | ||
| query | ||
| query | ||
| query | ||
| query | ||
| query | ||
| query | ||
| query | ||
| query | ||
| query | ||
| query | ||
| query | ||
| query | ||
| query | ||
| query | ||
| query | ||
| query | ||
| query | ||
| query | ||
| query | ||
| query | ||
| query | ||
| query | ||
| query | ||
| query | ||
| query | ||
| query | ||
| query | ||
| query | ||
| query | ||
| query | ||
| query | ||
| query | ||
| query | ||
| query | ||
| query | ||
| query | ||
| query | ||
| query | ||
| query | ||
| query | ||
| query |
Request cost is temporarily unavailable. No price is assumed.
/api/project/idealista/list-lands List land plots for sale or rent on Idealista
Details
Returns a paginated list of land plots advertised on Idealista for sale or rent in one location. Required inputs are the country site (location: es, it or pt), the response language (locale), a locationId taken from the suggestions or sublocations endpoints, the operation (sale or rent), a sort order, the page number (numPage) and the page size (maxItems). Optional filters narrow the search by land type (urban, buildingLand for buildable plots, nonBuildingLand for non-buildable plots), minimum and maximum price, minimum and maximum plot size, a publication window (sinceDate: T last 24 hours for rent only, Y last 48 hours for sale only, W last week, M last month) and an agency microsite short name. No live response was captured for this endpoint, so its response fields are unverified; it is expected to follow the paginated listing envelope seen on the new-homes listing (an elementList array of properties plus total, totalPages and actualPage), which you should confirm with a first call.
| Parameter | In | Value |
|---|---|---|
| query | ||
| query | ||
| query | ||
| query | ||
| query | ||
| query | ||
| query | ||
| query | ||
| query | ||
| query | ||
| query | ||
| query | ||
| query | ||
| query | ||
| query | ||
| query |
Request cost is temporarily unavailable. No price is assumed.
/api/project/idealista/list-new-homes List new-build homes for sale or rent on Idealista
Details
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.
| Parameter | In | Value |
|---|---|---|
| query | ||
| query | ||
| query | ||
| query | ||
| query | ||
| query | ||
| query | ||
| query | ||
| query | ||
| query | ||
| query | ||
| query | ||
| query | ||
| query | ||
| query | ||
| query | ||
| query | ||
| query | ||
| query | ||
| query |
Request cost is temporarily unavailable. No price is assumed.
/api/project/idealista/list-offices List offices for sale or rent on Idealista
Details
Returns a paginated list of office properties advertised on Idealista under Buy/Rent > Offices for one location. Required inputs are the country site (location: es, it or pt), the response language (locale), a locationId taken 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 price and size bounds (minPrice, maxPrice, minSize, maxSize), a publication window (sinceDate: T last 24 hours for rent only, Y last 48 hours for sale only, W last week, M last month), an agency microsite short name, building type (exclusive for offices-only buildings or mixed for mixed use), layout (openPlan or withWalls), a bank-owned flag and boolean amenity flags for accessible, airConditioning, elevator, exterior, garage, hasPlan (floor plan), heating, hotWater and security. No live response was captured for this endpoint, so its response fields are unverified; it is expected to follow the paginated listing envelope seen on the new-homes listing of this API (an elementList array of properties plus total, totalPages and actualPage), which you should confirm with a first call.
| Parameter | In | Value |
|---|---|---|
| query | ||
| query | ||
| query | ||
| query | ||
| query | ||
| query | ||
| query | ||
| query | ||
| query | ||
| query | ||
| query | ||
| query | ||
| query | ||
| query | ||
| query | ||
| query | ||
| query | ||
| query | ||
| query | ||
| query | ||
| query | ||
| query | ||
| query | ||
| query | ||
| query |
Request cost is temporarily unavailable. No price is assumed.
/api/project/idealista/list-promotion-properties List the homes or garages of a new-build promotion on Idealista
Details
Lists the individual units of one new-build promotion (development) on Idealista, described by the source as brand new homes or garages. Four inputs are required and there are no pagination or filter parameters: the country site (location: es, pt or it), the response language (locale), parentPromotionId, which the source says to take from promotionProperties -> promotionId, and propertyType (homes or garages), which the source says to take from promotionProperties -> propertyType. The documented sample promotion ID is 104907187. No live response was captured for this endpoint, so its response fields are unverified. The new-homes listing sample of this API exposed a promoName field and a development flag but no dedicated promotion identifier, so confirm on a live response where the promotionProperties values appear before chaining calls.
| Parameter | In | Value |
|---|---|---|
| query | ||
| query | ||
| query | ||
| query |
Request cost is temporarily unavailable. No price is assumed.
/api/project/idealista/list-storage-rooms List storage rooms for sale or rent on Idealista
Details
Returns a paginated list of storage rooms (trasteros) advertised on Idealista for sale or rent in one location. Required inputs are the country site (location: es, it or pt), the response language (locale), a locationId taken from the suggestions or sublocations endpoints, the operation (sale or rent), a sort order, the page number (numPage) and the page size (maxItems). Optional filters are limited to minimum and maximum price, minimum and maximum size, a publication window (sinceDate: T last 24 hours for rent only, Y last 48 hours for sale only, W last week, M last month) and an agency microsite short name; there are no amenity flags. No live response was captured for this endpoint, so its response fields are unverified; it is expected to follow the paginated listing envelope seen on the new-homes listing of this API (an elementList array of properties plus total, totalPages and actualPage), which you should confirm with a first call.
| Parameter | In | Value |
|---|---|---|
| query | ||
| query | ||
| query | ||
| query | ||
| query | ||
| query | ||
| query | ||
| query | ||
| query | ||
| query | ||
| query | ||
| query | ||
| query |
Request cost is temporarily unavailable. No price is assumed.
/api/project/idealista/property-details Get Idealista property details by listing ID
Details
Returns the full record of a single Idealista property ad, identified by its numeric propertyId. Inputs: propertyId (required, the ad ID, echoed back as adid), location (required, the Idealista market: es for Spain, pt for Portugal, it for Italy) and language (required, the language of the ad text: en, es, it, pt, ca, de, fr, nl or nb). Fields observed in a live probe of one Spain sale listing (propertyId 112272495, language en, location es, HTTP 200): adid, price and priceInfo (amount, currencySuffix), operation, propertyType, extendedPropertyType, homeType, state, country, multimedia (images with url, tag, localizedName, width and height, plus videos, virtual3DTours and hasMultimediasMadeByIdealista), ubication (title, latitude, longitude, hasHiddenAddress, administrativeAreaLevel1 to 4, locationId, locationName), moreCharacteristics (roomNumber, bathNumber, constructedArea, floor, lift, garden, swimmingPool, exterior, energyPerformance and more), energyCertification, priceDropInfo, propertyComment and comments (with language and autoTranslated flags), translatedTexts, suggestedTexts, detailedType, labels, contactInfo (commercialName, userType, micrositeShortName, professional and related advertiser fields), detailWebLink, several allows* feature flags, tracking and modificationDate (an object with value and text). No published response example was supplied for this operation, so every field named here comes from that single probe; other listings, such as rentals, other countries or withdrawn ads, may omit or add fields. modificationDate reflects the last change to the ad, not its first publication date.
| Parameter | In | Value |
|---|---|---|
| query | ||
| query | ||
| query |
Request cost is temporarily unavailable. No price is assumed.