Idealista Scraper

Extract real estate listing data from Idealista.com across Spain, Italy, and Portugal. Get property prices, sizes, locations, features, photos, and agent contacts for homes, offices, garages, new developments, and more.

What It Does

• Scrape property listings for sale or rent across all property types
• Support for Spain (idealista.com), Italy (idealista.it), and Portugal (idealista.pt)
• 50+ data fields per listing including price, size, GPS coordinates, features, and agency info
• All property types: homes, offices, premises, garages, lands, storage rooms, buildings, bedrooms
• Automatic pagination — collects all available pages up to your configured maximum
• Bypass Idealista's DataDome anti-bot protection with residential proxy rotation
• Export to JSON, CSV, Excel, or XML

Input

Field	Type	Required	Default	Description
location	string	Yes*	—	City or area slug from Idealista URLs (e.g., madrid-madrid, barcelona-barcelona, lisboa, roma-roma)
operation	string	No	sale	Listing type: sale or rent
propertyType	string	No	homes	Property type (see list below)
country	string	No	es	Target country: es (Spain), pt (Portugal), it (Italy)
maxItems	integer	No	100	Maximum listings to scrape (max 1,800 per search)
startUrls	array	Yes*	—	Direct Idealista search URLs — overrides location/operation/propertyType
proxyConfiguration	object	Yes	RESIDENTIAL	Residential proxy is required

* At least one of location or startUrls is required.

Property Types

Value	Description
homes	Apartments, houses, villas
newDevelopments	Off-plan and new-build developments
offices	Office spaces
premises	Commercial premises / retail units
garages	Garages and parking spaces
lands	Plots and land
storageRooms	Storage rooms (trasteros)
buildings	Entire buildings
bedrooms	Rooms for rent

Example Input

{
    "location": "madrid-madrid",
    "operation": "sale",
    "propertyType": "homes",
    "country": "es",
    "maxItems": 50
}

Location Slug Reference

Find your slug by searching on Idealista and copying the location segment from the URL:

Country	Location	Slug
Spain	Madrid	madrid-madrid
Spain	Barcelona	barcelona-barcelona
Spain	Seville	sevilla-sevilla
Spain	Valencia	valencia-valencia
Spain	Marbella	marbella-malaga
Spain	Málaga	malaga-malaga
Portugal	Lisbon	lisboa
Portugal	Porto	porto
Portugal	Faro	faro
Italy	Rome	roma-roma
Italy	Milan	milano-milano
Italy	Florence	firenze-firenze

You can also paste a full Idealista URL directly into the location field, or use startUrls to scrape multiple search pages at once.

Output

Each property listing produces one dataset record with the following fields. All fields are omit-empty — only fields with actual values appear.

Core Fields

Field	Type	Description
propertyCode	string	Idealista property ID
url	string	Full URL to the property listing page
price	integer	Listing price in EUR
priceByArea	integer	Price per square meter in EUR
currency	string	Currency code (EUR)
size	integer	Property size in m²
rooms	integer	Number of bedrooms
bathrooms	integer	Number of bathrooms
floor	string	Floor level (e.g., 4ª planta exterior con ascensor)
exterior	boolean	Exterior-facing property
description	string	Full listing description text

Location Fields

Field	Type	Description
address	string	Street address or location label
province	string	Province or region
municipality	string	City or municipality
district	string	District or neighbourhood
country	string	Country code: es, pt, or it
latitude	number	GPS latitude
longitude	number	GPS longitude
showAddress	boolean	false if seller hides exact address
locationId	string	Idealista internal location identifier

Media Fields

Field	Type	Description
thumbnail	string	Primary listing photo URL
numPhotos	integer	Total number of photos
multimedia	array	Full media array (images, tags)
hasVideo	boolean	Video tour available
has3DTour	boolean	3D virtual tour available
has360	boolean	360° photo available
hasStaging	boolean	Virtual staging available
hasPlan	boolean	Floor plan available

Feature Fields

Field	Type	Description
hasLift	boolean	Building has an elevator
hasSwimmingPool	boolean	Property has a pool
hasTerrace	boolean	Property has a terrace
hasAirConditioning	boolean	Property has air conditioning
hasBoxRoom	boolean	Includes a storage room (trastero)
hasGarden	boolean	Property has a garden
hasParkingSpace	object	{ hasParkingSpace, isParkingSpaceIncludedInPrice }

Contact Fields

Field	Type	Description
contactInfo	object	Agency details: { commercialName, agencyLogo }

Status & Classification Fields

Field	Type	Description
propertyType	string	Property type (homes, offices, etc.)
operation	string	sale or rent
status	string	Listing status (e.g., good, renew)
newDevelopment	boolean	New construction development
newProperty	boolean	Newly built property
externalReference	string	Agency's own reference code
detailedType	object	Sub-type details from Idealista
topPlus	boolean	Top Plus premium placement
topNewDevelopment	boolean	Featured new development
visualHighlight	boolean	Visual highlight badge
urgentVisualHighlight	boolean	Urgent sale/rent badge
preferenceHighlight	boolean	Preference highlight
topHighlight	boolean	Top highlight placement
scrapedAt	string	ISO 8601 UTC timestamp of scrape

Sample Output

{
    "propertyCode": "107795847",
    "url": "https://www.idealista.com/inmueble/107795847/",
    "price": 1160000,
    "priceByArea": 5321,
    "currency": "EUR",
    "size": 218,
    "rooms": 3,
    "bathrooms": 2,
    "floor": "4ª planta exterior con ascensor",
    "exterior": true,
    "description": "Espectacular piso en venta en el barrio de Salamanca...",
    "address": "Piso en Calle de Jorge Juan, Recoletos, Madrid",
    "province": "Madrid",
    "municipality": "Madrid",
    "district": "Recoletos",
    "country": "es",
    "latitude": 40.4264,
    "longitude": -3.6886,
    "showAddress": true,
    "thumbnail": "https://img3.idealista.com/blur/WEB_LISTING/0/id.pro.es.image.master/...",
    "numPhotos": 24,
    "hasLift": true,
    "hasTerrace": true,
    "hasAirConditioning": true,
    "hasParkingSpace": {
        "hasParkingSpace": true,
        "isParkingSpaceIncludedInPrice": false
    },
    "contactInfo": {
        "commercialName": "Engel & Völkers Madrid",
        "agencyLogo": "https://img3.idealista.com/..."
    },
    "propertyType": "homes",
    "operation": "sale",
    "newDevelopment": false,
    "topPlus": false,
    "scrapedAt": "2026-06-23T10:00:00+00:00"
}

Sentinel Records

When the actor cannot return real listings, it emits a structured sentinel record instead of failing silently with 0 results. There are two reasons:

blocked — DataDome blocked all scraping attempts (temporary):

{
    "_status": "no_data",
    "_reason": "blocked",
    "_message": "All scraping attempts were blocked by Idealista's anti-bot protection (DataDome). This is a temporary block — try again in a few hours.",
    "_help": "This actor requires a residential proxy. Configure proxy with RESIDENTIAL group in Proxy Configuration.",
    "scrapedAt": "2026-06-23T10:00:00+00:00"
}

Wait a few hours and re-run — DataDome blocks are temporary and usually clear on their own.

no_results — Session bypassed anti-bot but found no listings (check your location slug):

{
    "_status": "no_data",
    "_reason": "no_results",
    "_message": "Session bypassed anti-bot but no property listings were extracted. The search may return 0 results for the given location/filters, or the page layout may have changed. Try a different location.",
    "scrapedAt": "2026-06-23T10:00:00+00:00"
}

This usually means the location slug is wrong. Check the Location Slug Reference table above — Italy requires Italian names (roma-roma, not rome), and Portugal uses Portuguese names (lisboa, not lisbon).

Use Cases

• Market analysis: Track property prices and trends across Spanish, Italian, and Portuguese cities
• Investment research: Compare prices per square meter across neighbourhoods and districts
• Competitive monitoring: Track competitor agency listings and pricing strategies
• Lead generation: Collect agency contact details for real estate businesses
• Portfolio management: Monitor listings in specific areas for property management firms
• Price alerts: Run on a schedule to detect new listings or price changes

Limitations

• Residential proxy required: Idealista uses DataDome anti-bot protection that blocks all datacenter IPs.
• Search result cap: Idealista caps search results at ~1,800 listings (60 pages) per query. Split large cities into districts for broader coverage.
• Rate limits: The scraper uses 2–4 second delays between pages to avoid detection. Expect ~30 listings per minute.
• No individual property pages: This version scrapes search result cards. Full detail pages (phone numbers, more photos) require navigating to each property URL individually.

FAQ

Do I need a login or cookies? No. Idealista listings are publicly accessible — no account required.

Why is a residential proxy required? Idealista uses DataDome, an enterprise anti-bot platform that blocks all datacenter IP ranges instantly. Residential proxies mimic real user traffic and are the only way to reliably access the site programmatically.

Which countries are supported? Spain (idealista.com), Portugal (idealista.pt), and Italy (idealista.it).

What property types can I scrape? Homes, new developments, offices, commercial premises, garages, plots/land, storage rooms, entire buildings, and rooms for rent.

How do I find the location slug? Search on Idealista and look at the URL. For idealista.com/venta-viviendas/madrid-madrid/, the slug is madrid-madrid. For Portugal: idealista.pt/comprar-casas/lisboa/ → lisboa. For Italy: idealista.it/vendita-case/roma-roma/ → roma-roma.

Why are some fields missing from the output? Fields are omitted when they have no value. For example, coordinates appear only when Idealista exposes them, and features like pool or terrace are only included when they are mentioned in the listing card.

How many listings can I scrape? Up to 1,800 per search query (Idealista's hard cap). For large cities, split the search by district or neighbourhood to get broader coverage.

How fast is the scraper? Each page takes 30–60 seconds (browser warmup + page load). A run of 100 listings typically takes 5–10 minutes depending on DataDome response time.

Can I scrape multiple cities in one run? Yes — use startUrls to provide multiple search page URLs (one per city or district). The actor scrapes them in sequence up to maxItems total.

What if the actor returns a sentinel record instead of listings? DataDome temporarily blocked all proxy attempts. Wait a few hours and try again — the block is not permanent.