# Smart Idealista Scraper - Spain, Italy, Portugal Properties (`sian.agency/smart-idealista-scraper`) Actor

Idealista scraper and property data API for Spain, Italy and Portugal. Search sale and rental homes, new builds, rooms, garages, offices, land and commercial units by city, search URL, map polygon or CSV; return price, size, rooms, energy rating, year built and price history.

- **URL**: https://apify.com/sian.agency/smart-idealista-scraper.md
- **Developed by:** [SIÁN OÜ](https://apify.com/sian.agency) (community)
- **Categories:** Real estate, Lead generation, Agents
- **Stats:** 649 total users, 49 monthly users, 98.1% runs succeeded, 20 bookmarks
- **User rating**: 4.38 out of 5 stars

## Pricing

Pay per event

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.
Actors are written with capital "A".

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

## Smart Idealista Scraper 🏠

[![SIÁN Agency Store](https://img.shields.io/badge/Store-SI%C3%81N%20Agency-1AE392)](https://apify.com/sian.agency?fpr=sian)
[![Zillow Property Scraper](https://img.shields.io/badge/Store-Zillow%20Property%20Scraper-1F4E79)](https://apify.com/sian.agency/zillow-property-scraper?fpr=sian)
[![Bayut Property Scraper](https://img.shields.io/badge/Store-Bayut%20Property%20Scraper-93D500)](https://apify.com/sian.agency/bayut-property-scraper?fpr=sian)
[![Zoopla Property Scraper](https://img.shields.io/badge/Store-Zoopla%20Property%20Scraper-8046F1)](https://apify.com/sian.agency/zoopla-property-scraper?fpr=sian)

#### 🎉 NEW: Search by URL, draw an area on the map, or deep-scrape a single listing — plus self-healing location IDs that never go stale. Still 40 properties/page with a 33% FREE bonus on every extraction!

##### Perfect for real estate professionals, investors, and market researchers who need reliable property data without the headache.

### 🔎 What is the Idealista Scraper — and when should you use it?

The **Idealista Scraper** turns Idealista listings across Spain, Italy and Portugal into clean, structured rows you can filter, export and feed straight into a spreadsheet, database or AI agent. No account, no portal API key, no browser automation to maintain.

**Use it when you need:** sale or rental homes, new builds, rooms, garages, offices, land and commercial units — price, size, rooms, energy rating, year built and price history — plus agency profiles with phone and address.

**Use something else when:** you need a different country. Use [Funda Property Scraper](https://apify.com/sian.agency/funda-property-scraper?fpr=sian) for the Netherlands. Use [Otodom Property Scraper](https://apify.com/sian.agency/otodom-property-scraper?fpr=sian) for Poland. Use [Immobiliare Property Scraper](https://apify.com/sian.agency/immobiliare-property-scraper?fpr=sian) for the native Italian portal.

### 🤖 Use with AI agents

Already connected to the [Apify MCP server](https://mcp.apify.com)? Just ask for this Actor by name: sian.agency/smart-idealista-scraper

**Your agent can pay for its own runs.** This Actor is eligible for [agentic payments](https://docs.apify.com/platform/actors/publishing/monetize), so an agent can discover it, run it and settle the bill over [x402](https://www.x402.org/) (USDC on Base) or [Skyfire](https://www.skyfire.xyz/) — without an Apify account or API token of its own. Billing is the same either way: per successful row, never for errors.

Otherwise copy this prompt into Claude, ChatGPT, Cursor or any MCP-enabled assistant:

```text
I want Spanish, Italian or Portuguese property data from Idealista using the Apify Actor `sian.agency/smart-idealista-scraper`.

Use it when I need: sale or rental homes, new builds, rooms, garages, offices, land and commercial units — price, size, rooms, energy rating, year built and price history — plus agency profiles with phone and address.

Don't use it when: you need a different country — use funda-property-scraper or otodom-property-scraper or immobiliare-property-scraper instead.

How to call it: `country` (`es`, `it`, `pt`) and `operation` (`sale` or `rent`) are both required; then choose an `endpoint` such as `listhomes` and give a `locationName`, `searchUrl` or `polygonUrl`.

Start with this input:
{
  "country": "es",
  "operation": "sale",
  "endpoint": "listhomes",
  "locationName": "Madrid",
  "numPages": 2
}

Ask me which country and city, and whether you want sale or rent, then run the Actor and summarise the results as a table.
```

**Things you can ask your agent for:**

- *Compare asking prices per m² across Madrid, Barcelona and Valencia.*
- *Find garages for sale in Lisbon under €30k.*
- *Enrich a list of Idealista agencies with phone numbers and office addresses.*

Machine-readable API, MCP config and OpenAPI definition for this Actor are published at [apify.com/sian.agency/smart-idealista-scraper.md](https://apify.com/sian.agency/smart-idealista-scraper.md).

### 📋 Overview

**Smart Idealista Scraper is ridiculously simple to use.** No training required - just configure your search and get perfect property data instantly. Unlike complicated scrapers that break constantly, our API-based architecture never stops working.

Perfect for real estate professionals, investors, and market researchers who need reliable property data from Spain, Italy, and Portugal. Just configure, run, and download clean data in JSON or CSV format.

**Why thousands of professionals choose us:**

- ✅ **Zero Learning Curve**: Configure with filters, click Run, get results
- ⚡ **Lightning Fast**: 40 properties per page in seconds
- 🎯 **API-Reliable**: Never breaks - consistent data structure
- 💰 **Best Price**: $0.003/property + 33% bonus (40 delivered, 30 charged)
- 📁 **CSV Bulk Upload**: Analyze entire cities at once
- 🌍 **3 Countries**: Spain, Italy, Portugal covered
- 🚫 **No Maintenance**: No broken scrapers, no API keys to manage

### ✨ Revolutionary Features

- 📁 **NEW: CSV Bulk Upload**: Upload unlimited locations via Excel/Google Sheets-friendly CSV
- 🎯 **Zero Learning Curve**: Configure with filters, click Run, get perfect results
- ⚡ **Instant Results**: ~40 properties per page in seconds
- 🔄 **Automatic Everything**: No setup, no maintenance, no broken scrapers
- 📊 **Perfect Data**: Clean, structured output with 50+ data points
- 🌍 **3 Countries Support**: Spain, Italy, Portugal properties
- 💰 **Best Price**: $0.003/property + 33% bonus (40 delivered, 30 charged)
- 🚫 **No Breakage**: API-based architecture - never stops working
- 📈 **Multi-page**: Extract hundreds of properties automatically
- 🏘️ **9 Categories**: Homes, offices, land, garages, commercial, rooms
- 🔗 **Search by URL**: Paste any Idealista search link — no location codes to look up
- 🗺️ **Draw-an-Area (Polygon) Search**: Pull every listing inside a map-drawn boundary
- 🔎 **Deep Single-Property Profiles**: Energy rating, year built, fees & IBI, price-change history, floor-plan/3D-tour links
- 🏢 **NEW: Agency Profiles Mode**: Turn agency slugs into structured agency profiles — phone, office address with GPS, years active, and a listings-by-location breakdown
- 🛡️ **Self-Healing Location IDs**: Outdated codes auto-resolve to the current one — old bookmarks and CSV lists keep working
- 🔁 **Resilient Under Load**: Automatic retry with smart backoff absorbs traffic-spike rate limits — clear errors instead of empty results

### 🎬 Quick Start

So simple, no training needed! Just provide location details and run.

```bash
## Using API
curl -X POST https://api.apify.com/v2/acts/sian.agency/smart-idealista-scraper/runs?token=[YOUR_TOKEN] \
-d '{
  "country": "es",
  "operation": "rent",
  "locationId": "0-EU-ES-28-07-001-079",
  "locationName": "Madrid",
  "numPages": 2
}'
```

### 🚀 Getting Started (2 Simple Steps)

#### Step 1: Choose Your Input Mode

**Option A: Single Location** - Perfect for targeted searches

- Provide `country`, `operation`, `locationId`, `locationName`
- Add filters (price, size, bedrooms, etc.)
- Specify `numPages` (1-250)

**Option B: 🆕 CSV Bulk Upload** - Ideal for city/region analysis

- Upload CSV with `locationId` and `locationName` columns
- Excel/Google Sheets friendly
- PAID tier only - unlimited locations

**Option C: 🆕 Agency Profiles** - Enrich the agencies behind the listings

- Fill `agencySlugs` with agency slugs or agency page URLs (found in every property row's `agencyUrl` field)
- Get one structured profile per agency: name, phone, office address with GPS, years active, languages, total listings, and a listings-by-location breakdown
- PAID tier only

#### Step 2: Click Run & Download

One click and our API gets to work instantly. Download clean JSON or CSV with 50+ data points per property.

**That's it! In seconds, you'll have:**

- Complete property data (price, size, rooms, features)
- Location information (address, coordinates, neighborhood)
- Contact details (agency, phone, website)
- Media URLs (photos, videos, virtual tours)
- Auto-calculated metrics (price per m²)

### 📥 Input Configuration

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| country | string | Yes | Country code: `es` (Spain), `it` (Italy), `pt` (Portugal) |
| operation | string | Yes | Operation type: `sale` or `rent` |
| locationId | string | Yes\* | Idealista location ID (hierarchical format) |
| locationName | string | Yes\* | Human-readable location name |
| searchUrl | string | No | 🔗 Paste any Idealista search-results URL — location + filters auto-detected (PAID) |
| polygonUrl | string | No | 🗺️ Paste an Idealista Areas URL with a drawn shape — every listing inside it (PAID) |
| deepSingleUrl | string | No | 🔎 One listing URL — full deep profile with premium fields (PAID) |
| deepFieldSet | string | No | Deep mode field set: `standard` or `extended` (energy, fees, history) |
| agencySlugs | array | No | 🏢 Agency slugs or agency URLs — one structured agency profile per entry (PAID) |
| endpoint | string | No | Property category (default: `listhomes`) |
| numPages | integer | No | Number of pages to scrape (1-250, default: 1) |
| order | string | No | Sort order (default: `mostrecent`) |
| language | string | No | Result language (default: `en`) |

\*Not required when using one of the URL modes (`searchUrl`, `polygonUrl`, `deepSingleUrl`) or agency profiles mode (`agencySlugs`).

**Property Categories (endpoint):**

- `listhomes` - All homes (apartments, houses) **\[Default]**
- `listnewhomes` - New developments
- `liststoragerooms` - Storage rooms
- `listbuildings` - Buildings
- `listlands` - Land parcels
- `listgarages` - Garages/Parking
- `listcommercialproperties` - Commercial properties
- `listoffices` - Office spaces
- `listrooms` - Individual rooms

**Location ID Format:**

- Spain: `0-EU-ES-XX-YYY-ZZZ` (e.g., `0-EU-ES-28-07-001-079` = Madrid)
- Italy: `0-EU-IT-XX-YYY-ZZZ` (e.g., `0-EU-IT-RM-01-001-097` = Rome)
- Portugal: `0-EU-PT-XX-YYY` (e.g., `0-EU-PT-11-06` = Lisbon)

**How to find Location ID:** Go to idealista.com → search → DevTools (F12) → Network tab → Find `locationId` in API calls

**CSV Bulk Upload:** Upload file with `locationId,locationName` columns (headers optional)

**Search Filters (64+ available):**

- Price: `minPrice`, `maxPrice`
- Size: `minSize`, `maxSize`
- Bedrooms/Bathrooms: `bedrooms0-4`, `bathrooms1-3`
- Property Types: `flat`, `penthouse`, `duplex`, `chalet`, `villaType`, etc.
- Condition: `newDevelopment`, `good`, `renew`, `furnished`
- Features: `airConditioning`, `elevator`, `garage`, `pool`, `garden`
- Floor/Time: `topFloor`, `intermediateFloor`, `sinceDate`
- Rental: `longTermResidential`, `shortTerm`
- Advanced: `micrositeShortName` (agency filter), `center` (GPS), `distance`

### 📤 Output

| Field | Type | Description |
|-------|------|-------------|
| propertyCode | string | Unique Idealista ID |
| title | string | Property title |
| price | number | Price in EUR |
| size | number | Size in square meters |
| pricePerSqm | number | Price per square meter *(auto-calculated)* |
| rooms | number | Number of rooms |
| bathrooms | number | Number of bathrooms |
| address | string | Full address |
| neighborhood | string | Neighborhood name |
| district | string | District |
| municipality | string | City/Municipality |
| province | string | Province/State |
| country | string | Country code |
| locationId | string | Idealista location ID |
| latitude | number | GPS latitude |
| longitude | number | GPS longitude |
| description | string | Full property description |
| url | string | Property URL |
| thumbnail | string | Main image URL |
| images | array | All image URLs |
| propertyType | string | Type (flat, house, etc.) |
| operation | string | Sale or rent |
| numPhotos | number | Number of photos |
| hasVideo | boolean | Has video tour |
| has3DTour | boolean | Has 3D tour |
| hasPlan | boolean | Has floor plan |
| features | object | All features object |
| agencyName | string | Agency name |
| agencyUrl | string | Agency website |

**Agency profile rows (`agencySlugs` mode):**

| Field | Type | Description |
|-------|------|-------------|
| agencySlug | string | Agency identifier (from the agency page URL) |
| agencyName | string | Commercial name |
| agencyPhone | string | Contact phone |
| agencyWebsite | string | Agency's own website (when published) |
| agencyUrl | string | Agency page URL on the portal |
| agencyAddress | object | Office street, city, postal code + GPS coordinates |
| activeSinceYear | string | Year the agency joined the portal |
| totalListings | number | Active listings right now |
| languages | array | Languages the agency serves |
| portfolioLocations | array | Listings-by-location breakdown (province → municipality → district) |

**Example:**

```json
{
  "propertyCode": "103887563",
  "title": "Studio apartment in paseo de Juan Antonio Vallejo-Nájera Botas, 29",
  "subtitle": "Acacias, Madrid",
  "price": 950,
  "size": 30,
  "pricePerSqm": 32,
  "rooms": 0,
  "bathrooms": 1,
  "address": "paseo de Juan Antonio Vallejo-Nájera Botas, 29",
  "district": "Arganzuela",
  "neighborhood": "Acacias",
  "municipality": "Madrid",
  "province": "Madrid",
  "country": "es",
  "locationId": "0-EU-ES-28-07-001-079-02-002",
  "latitude": 40.4022241,
  "longitude": -3.7099448,
  "description": "INDIVIDUAL RENT furnished studio...",
  "url": "https://www.idealista.com/inmueble/103887563/",
  "thumbnail": "https://img4.idealista.com/blur/480_360_mq/...",
  "propertyType": "studio",
  "operation": "rent",
  "numPhotos": 17
}
```

### 💼 Use Cases & Examples

#### Real Estate Market Analysis

Extract property prices and features for market research across multiple locations.

**Input:** Country + location + price/size filters
**Output:** Property data with price per m² analysis
**Use:** Market reports, price trends, investment analysis

#### Investment Property Search

Find rental properties with specific ROI criteria.

**Input:** Operation=rent + max price + bedrooms + amenities
**Output:** Matching properties with yield calculations
**Use:** Investment analysis, rental yield projections

#### Competitive Analysis

Monitor competitor listings and pricing strategies.

**Input:** Location + agency filter + sort order
**Output:** Competitor's full portfolio with pricing
**Use:** Pricing strategy, market positioning

#### Multi-Location Market Research

Analyze entire cities or regions at once.

**Input:** CSV file with multiple locations + filters
**Output:** Consolidated data across all locations
**Use:** Regional analysis, expansion planning

#### Price Per m² Benchmarks

Calculate accurate price-per-square-meter across neighborhoods.

**Input:** Location + property type filters
**Output:** Properties with auto-calculated pricePerSqm
**Use:** Valuation benchmarks, fair price analysis

#### New Development Tracking

Monitor new construction projects in target areas.

**Input:** Endpoint=listnewhomes + location
**Output:** All new development listings
**Use:** Market supply analysis, upcoming inventory

### 🔗 Integration Examples

#### JavaScript/Node.js

```javascript
const { ApifyClient } = require('apify-client');
const client = new ApifyClient({ token: 'YOUR_TOKEN' });

const run = await client.actor('sian.agency/smart-idealista-scraper').call({
  country: 'es',
  operation: 'rent',
  locationId: '0-EU-ES-28-07-001-079',
  locationName: 'Madrid',
  numPages: 3,
  maxPrice: 2000,
  bedrooms2: true
});

const { items } = await client.dataset(run.defaultDatasetId).listItems();
console.log(`Found ${items.length} properties`);
```

#### Python

```python
from apify_client import ApifyClient
client = ApifyClient('YOUR_TOKEN')

run = client.actor('sian.agency/smart-idealista-scraper').call(
    run_input={
        'country': 'es',
        'operation': 'sale',
        'locationId': '0-EU-ES-46-02-002-250',
        'locationName': 'Valencia',
        'numPages': 2,
        'minPrice': 250000,
        'maxPrice': 350000
    }
)

items = client.dataset(run['defaultDatasetId']).list_items().items
print(f"Found {len(items)} properties")
```

#### cURL

```bash
curl -X POST 'https://api.apify.com/v2/acts/sian.agency/smart-idealista-scraper/runs?token=YOUR_TOKEN' \
-H 'Content-Type: application/json' \
-d '{
  "country": "it",
  "operation": "sale",
  "locationId": "0-EU-IT-MI-01-001-135",
  "locationName": "Milan",
  "numPages": 1,
  "flat": true
}'
```

#### Automation Tool Workflows (n8n, Zapier, Make, etc.)

1. **Trigger**: Manual/schedule/webhook
2. **HTTP Request**: Call this actor's API
3. **Process**: Filter and analyze properties
4. **Action**: Save to database, send alerts, generate reports

### 📊 Performance & Pricing

**View current pricing in the [Apify Console](https://apify.com/sian.agency/smart-idealista-scraper#pricing)**

#### Performance

- **Speed**: ~40 properties per page (15-20 seconds)
- **Concurrent runs**: FREE=1, PAID=5
- **Timeout**: 7 days (for large extractions)
- **Reliability**: API-based - never breaks

#### Pricing Model

- **Start Fee**: $0.005 per run
- **Per Property**: $0.003
- **Per Agency Profile**: $0.003 (agencySlugs mode)
- **🎁 Launch Bonus**: Get 33% more properties FREE!
  - You pay for 30 properties/page
  - You get 40 properties/page

#### Cost Examples

- **1 page (40 properties)**: $0.095
- **5 pages (200 properties)**: $0.455
- **10 pages (400 properties)**: $0.905

#### Tier Limits

- **FREE**: ~200 properties/month recommended
- **PAID**: Unlimited properties, CSV bulk upload

### ❓ Frequently Asked Questions

**Q: How do I find my Location ID?**
A: Go to idealista.com, search for your location, open DevTools (F12), look at Network tab during search, find `locationId` in API calls.

**Q: Can I extract from private listings?**
A: Only public listings are accessible. No authentication required.

**Q: How many properties can I extract?**
A: FREE tier: ~200/month recommended. PAID tier: unlimited.

**Q: Is the data reliable?**
A: Yes! We use API-based architecture, never screen scraping. No breakage, consistent data structure.

**Q: Is this an Idealista API?**
A: Idealista doesn't offer a public API. Smart Idealista Scraper is the most reliable Idealista API alternative — it extracts the same structured property data you see on idealista.com (Spain), idealista.it (Italy), and idealista.pt (Portugal), delivered as clean JSON with 50+ fields per property. Use it whenever you'd otherwise want an "Idealista API" or "idealista data" feed.

**Q: Can I export to Excel?**
A: Yes! Download as CSV and open directly in Excel.

**Q: How fast is it?**
A: Approximately 15-20 seconds per page, delivering 40 properties each.

**Q: What if my location ID is outdated?**
A: Nothing to fix — location IDs are self-healing. If a saved code has changed on the site, the scraper resolves the current one automatically and your search completes anyway. Old bookmarks, saved tasks, and CSV lists keep working.

**Q: Can I just paste a search URL instead of looking up location codes?**
A: Yes (PAID tier). Paste any Idealista search-results link into the `searchUrl` field and the location and filters are detected automatically. You can also paste a map link with a hand-drawn area (`polygonUrl`) or a single listing URL for a deep profile (`deepSingleUrl`).

**Q: Does it work with GPS coordinates?**
A: Yes! Use `center` (lat,lng) and `distance` (radius in meters) instead of locationId.

**Q: What's the CSV upload format?**
A: Simple CSV with `locationId,locationName` columns. Headers optional. Excel/Google Sheets friendly.

### 🐛 Troubleshooting

**No results returned**

- Verify locationId format (hierarchical code)
- Check if location exists in that country
- Try with broader search filters

**Invalid locationId error**

- Double-check the location ID format
- Ensure country code matches location
- Use DevTools to extract correct location ID

**Rate limiting on FREE tier**

- Monitor your monthly usage
- Upgrade to PAID for unlimited access
- Use specific filters to reduce results

**Timeout errors**

- Reduce numPages per run
- Use multiple smaller runs
- Retry the run — transient data-service slowdowns usually clear within minutes

**Unexpected property types**

- Verify `endpoint` parameter
- Check property type filters
- Review location for property availability

### 🇪🇸 Idealista API & Data Extraction — Para Usuarios en España

**Looking for an Idealista API, a way to scrape Idealista listings, or to extract Idealista data?** Smart Idealista Scraper is the most reliable Idealista scraper available — structured JSON output, no breakage, no coding. Built for Spanish real estate professionals, developers, and investors who need clean property data from idealista.com.

**¿Buscas una API de Idealista o una forma fiable de extraer datos de Idealista?** Smart Idealista Scraper te entrega datos estructurados de propiedades de idealista.com sin código, sin mantenimiento y con datos siempre limpios. Es la alternativa más fiable a una API oficial (que Idealista no ofrece públicamente).

#### Why this Idealista scraper works

- ✅ **Idealista API alternative**: Idealista datos en JSON estructurado, 50+ campos por propiedad
- ⚡ **40 propiedades por página** en segundos
- 💰 **$0.003 por propiedad** + 33% gratis (paga 30, recibe 40)
- 📁 **Carga masiva CSV**: analiza ciudades enteras de una vez
- 🎯 **API-reliable**: nunca se rompe — datos consistentes

#### Quick example — extract Idealista data for Madrid (alquiler)

```bash
curl -X POST 'https://api.apify.com/v2/acts/sian.agency/smart-idealista-scraper/runs?token=TU_TOKEN' \
-H 'Content-Type: application/json' \
-d '{
  "country": "es",
  "operation": "rent",
  "locationId": "0-EU-ES-28-07-001-079",
  "locationName": "Madrid",
  "numPages": 2,
  "maxPrice": 1500
}'
```

#### Casos de uso comunes en España

- **Análisis de mercado**: precios, tendencias y comparativas por barrio
- **Inversión inmobiliaria**: encuentra propiedades de alquiler con ROI específico
- **Análisis competitivo**: monitoriza listados de inmobiliarias y cambios de precio
- **Valoración por m²**: calcula precio por metro cuadrado con precisión
- **Obra nueva**: descubre nuevas promociones (`endpoint: listnewhomes`)

#### FAQ — España

- **¿Cómo encuentro mi `locationId`?** Ve a idealista.com → busca tu zona → DevTools (F12) → pestaña Network → busca `locationId` en las llamadas API.
- **¿Funciona con coordenadas GPS?** Sí, usa `center` (lat,lng) y `distance` (radio en metros).
- **¿Puedo exportar a Excel?** Sí, descarga en CSV y ábrelo directamente en Excel o Google Sheets.
- **¿Es legal?** Solo se accede a listados públicos de idealista.com. Es responsabilidad del usuario cumplir con el RGPD y los términos de uso.

#### 🇮🇹 Per utenti in Italia

Smart Idealista Scraper supporta anche **idealista.it** — stesso prezzo, stesse funzionalità. Esempio rapido per Milano in vendita:

```bash
curl -X POST 'https://api.apify.com/v2/acts/sian.agency/smart-idealista-scraper/runs?token=IL_TUO_TOKEN' \
-H 'Content-Type: application/json' \
-d '{
  "country": "it",
  "operation": "sale",
  "locationId": "0-EU-IT-MI-01-001-135",
  "locationName": "Milano",
  "numPages": 2,
  "flat": true
}'
```

***

### ⚖️ Is it legal to scrape data?

Our actors are ethical and do not extract any private user data, such as email addresses, gender, or location. They only extract what the user has chosen to share publicly. We therefore believe that our actors, when used for ethical purposes by Apify users, are safe.

However, you should be aware that your results could contain personal data. Personal data is protected by the **GDPR** in the European Union and by other regulations around the world. You should not scrape personal data unless you have a legitimate reason to do so. If you're unsure whether your reason is legitimate, consult your lawyers.

You can also read Apify's blog post on the [legality of web scraping](https://blog.apify.com/is-web-scraping-legal/).

***

### 🤝 Support

[![Telegram Support](https://img.shields.io/badge/Telegram-Support%20Group-0088cc?logo=telegram)](https://t.me/+vyh1sRE08sAxMGRi)

**Join our active support community**

- 🐛 Found a bug? File an issue in the Apify Console Issues tab
- ⭐ Loving the tool? Leave a 5-star review — it helps us build more
- Check [SIÁN Agency Store](https://apify.com/sian.agency?fpr=sian) for more automation tools
- 📧 <apify@sian-agency.online>

***

**Built by [SIÁN Agency](https://www.sian-agency.online)** | **[More Tools](https://apify.com/sian.agency?fpr=sian)**

**🎯 Not sure which tier you need?** Start with FREE - no credit card required. Upgrade when you're ready to scale!

# Actor input Schema

## `country` (type: `string`):

🌍 Select the Idealista country domain

## `operation` (type: `string`):

🏠 What type of listing?

## `endpoint` (type: `string`):

🏘️ Select the type of property category to search

## `searchUrl` (type: `string`):

Paste any Idealista search-results URL and we'll auto-detect the location + filters from the page.

**Example:** `https://www.idealista.com/en/venta-terrenos/jaen/la-loma-y-las-villas/`

💸 **Pricing:** $0.005 per URL + $0.003 per property delivered (PAID tier only).

## `polygonUrl` (type: `string`):

Paste an Idealista Areas URL with a drawn-polygon shape parameter.

**Example:** `https://www.idealista.com/en/areas/venta-viviendas/?shape=((...))`

💸 **Pricing:** $0.01 per search + $0.003 per property (PAID tier only).

## `deepSingleUrl` (type: `string`):

Paste one Idealista detail URL and get the full extended-field set (energy certificate, year built, community fees, price-change history, floor-plan / 3D-tour URLs).

**Example:** `https://www.idealista.com/en/inmueble/111577630/`

💸 **Pricing:** $0.05 per URL (PAID tier only — replaces the per-property charge).

## `deepFieldSet` (type: `string`):

Controls how many fields the deep-scrape returns.

- **standard**: only fields the existing search API already exposes
- **extended**: adds energy certificate, year built, community fees, IBI, price history, floor-plan + 3D-tour URLs

## `agencySlugs` (type: `array`):

Turn agency identifiers into agency profiles: commercial name, phone, office address with GPS, active-since year, languages, total listings and a listings-by-location breakdown.

One entry per agency — the slug (`walterhauschamberi`) or the full agency URL (`https://www.idealista.com/pro/walterhauschamberi/`).

Every property row includes an `agencyUrl`, so run a property search first, then enrich the agencies behind those listings. Uses the Country and Operation fields above. PAID tier only.

## `locationId` (type: `string`):

📍 Single Idealista location ID, e.g. `0-EU-ES-28-07-001-079` (Madrid). For several locations use 'Multiple Locations' below.

**Formats:** Spain `0-EU-ES-XX-YYY`, Italy `0-EU-IT-XX-YYY` (Rome `0-EU-IT-RM-01-001-097`), Portugal `0-EU-PT-XX` (Lisbon `0-EU-PT-11`).

**Find it:** search your location on idealista.com, open DevTools (F12) → Network, run a search, then copy the `locationId=` parameter.

## `locationName` (type: `string`):

📍 Single location name (e.g., Madrid, Barcelona, Rome)

Required when using Location ID field above.

💡 **FREE tier:** Single location only
💎 **PAID tier:** Use CSV upload below for bulk locations

## `locationsCsv` (type: `array`):

📁 CSV upload (PAID tier only) — scan many locations in one run.

**Columns:** `locationId` (e.g. `0-EU-ES-28-07-001-079`) and `locationName` (e.g. `Madrid`). Header row optional; `location_id` / `id` also accepted. Duplicates are removed automatically.

```
locationId,locationName
0-EU-ES-28-07-001-079,Madrid
0-EU-IT-RM-01-001-097,Rome
```

Mutually exclusive with the JSON field above.

## `numPages` (type: `integer`):

📄 How many pages to scrape

• Each page contains ~30 properties (charged for 30)
• 🎁 **Launch Bonus:** Get 40 properties per page - 10 extra FREE!
• Duplicates are automatically removed (pagination overlap)
• Example: 5 pages = ~145-150 unique properties (up to 200 with bonus!)

💡 **Tip:** Start with 1-2 pages to test your filters, then scale up as needed.

## `order` (type: `string`):

📊 How to order the search results

## `language` (type: `string`):

🌐 Language for property descriptions

## `minPrice` (type: `integer`):

Minimum property price in EUR

## `maxPrice` (type: `integer`):

Maximum property price in EUR

## `minSize` (type: `integer`):

Minimum property size in square meters

## `maxSize` (type: `integer`):

Maximum property size in square meters

## `bedrooms0` (type: `boolean`):

Include studio apartments

## `bedrooms1` (type: `boolean`):

Include properties with 1 bedroom

## `bedrooms2` (type: `boolean`):

Include properties with 2 bedrooms

## `bedrooms3` (type: `boolean`):

Include properties with 3 bedrooms

## `bedrooms4` (type: `boolean`):

Include properties with 4 or more bedrooms

## `bathrooms1` (type: `boolean`):

Include properties with 1 bathroom

## `bathrooms2` (type: `boolean`):

Include properties with 2 bathrooms

## `bathrooms3` (type: `boolean`):

Include properties with 3 or more bathrooms

## `flat` (type: `boolean`):

Include flats, penthouses, and duplexes (all apartment types)

## `onlyFlats` (type: `boolean`):

Only standard flats/apartments

## `penthouse` (type: `boolean`):

Include penthouse apartments

## `duplex` (type: `boolean`):

Include duplex apartments

## `chalet` (type: `boolean`):

Include all house types (independent, semi-detached, terraced, country)

## `independantHouse` (type: `boolean`):

Include independent/detached houses

## `semidetachedHouse` (type: `boolean`):

Include semi-detached houses

## `terracedHouse` (type: `boolean`):

Include terraced/row houses

## `countryHouse` (type: `boolean`):

Include country houses

## `apartamentoType` (type: `boolean`):

Specific apartment classification

## `villaType` (type: `boolean`):

Include villas

## `loftType` (type: `boolean`):

Include loft spaces

## `cortijoType` (type: `boolean`):

Include cortijos (traditional Spanish farmhouses)

## `atticStudioType` (type: `boolean`):

Include attic studio apartments

## `casaBajaType` (type: `boolean`):

Include ground floor houses (casa baja)

## `newDevelopment` (type: `boolean`):

Only new development properties

## `good` (type: `boolean`):

Properties in good condition

## `renew` (type: `boolean`):

Properties that need renovation

## `furnished` (type: `string`):

Furnishing status (only for rent operation)

## `isBareOwnership` (type: `boolean`):

Properties sold as bare ownership

## `isTenanted` (type: `boolean`):

Properties currently tenanted

## `isIllegallyOccupied` (type: `boolean`):

Properties illegally occupied

## `isFree` (type: `boolean`):

Properties that are free without restrictions

## `airConditioning` (type: `boolean`):

Has air conditioning

## `builtinWardrobes` (type: `boolean`):

Has built-in wardrobes

## `elevator` (type: `boolean`):

Building has elevator

## `exterior` (type: `boolean`):

Exterior-facing property

## `garage` (type: `boolean`):

Has garage/parking

## `garden` (type: `boolean`):

Has garden

## `swimmingPool` (type: `boolean`):

Has swimming pool

## `terrance` (type: `boolean`):

Has terrace

## `storeRoom` (type: `boolean`):

Has storage room

## `accessible` (type: `boolean`):

Wheelchair accessible

## `luxury` (type: `boolean`):

Luxury property

## `petsAllowed` (type: `boolean`):

Pets allowed (rent only)

## `hasPlan` (type: `boolean`):

Property has floor plan available

## `virtualTour` (type: `boolean`):

Has virtual tour available

## `bankOffer` (type: `boolean`):

Bank-owned property

## `topFloor` (type: `boolean`):

Top floor only

## `intermediateFloor` (type: `boolean`):

Intermediate floor only

## `sinceDate` (type: `string`):

📅 Filter by publication date

**Options:**
• Any Time: (default) - All listings
• Last 24h: T - **Rent operation only**
• Last 48h: Y - **Buy/Sale operation only**
• Last Week: W - Available for both operations
• Last Month: M - Available for both operations

⚠️ Note: T (24h) only works with rent, Y (48h) only works with sale

## `longTermResidential` (type: `boolean`):

Long-term residential rental

## `shortTerm` (type: `boolean`):

Short-term or seasonal rental (rent only)

## `micrositeShortName` (type: `string`):

📍 Filter by specific real estate agency

Get ads from a specific agency. Extract from agency URL:
https://www.idealista.com/pro/cajal-gestion-inmobiliaria/
→ use: cajal-gestion-inmobiliaria

## `center` (type: `string`):

Latitude,longitude for radius search (e.g., '40.416,-3.703')

## `distance` (type: `integer`):

Radius around GPS coordinates (100-100,000 meters). Only used when GPS coordinates are provided.

## Actor input object example

```json
{
  "country": "es",
  "operation": "rent",
  "endpoint": "listhomes",
  "searchUrl": "https://www.idealista.com/en/venta-viviendas/madrid-madrid/",
  "polygonUrl": "https://www.idealista.com/en/areas/venta-viviendas/?shape=((sample_polyline))",
  "deepSingleUrl": "https://www.idealista.com/en/inmueble/111577630/",
  "deepFieldSet": "extended",
  "locationId": "0-EU-ES-28-07",
  "locationName": "Madrid",
  "numPages": 1,
  "order": "mostrecent",
  "language": "en",
  "furnished": "",
  "sinceDate": "",
  "center": "40.416775,-3.703790"
}
```

# Actor output Schema

## `results` (type: `string`):

Processed property data with cleaned fields, calculated metrics, and structured format

## `htmlReport` (type: `string`):

HTML summary showing successful and failed results with key metrics

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {};

// Run the Actor and wait for it to finish
const run = await client.actor("sian.agency/smart-idealista-scraper").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {}

# Run the Actor and wait for it to finish
run = client.actor("sian.agency/smart-idealista-scraper").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"])
for item in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{}' |
apify call sian.agency/smart-idealista-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.apify.com/?tools=sian.agency/smart-idealista-scraper",
                "--header",
                "Authorization: Bearer <YOUR_API_TOKEN>"
            ]
        }
    }
}

```

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/0qnMmz76dLymEDVGf/builds/TAMpi4x9UPqzXML7Q/openapi.json