# Idealista Scraper (`datacut/idealista-scraper`) Actor Fast Idealista scraper for Spain, Italy, and Portugal. Returns 100+ fields per listing including AI summaries, Q\&A pairs, deal signals, engagement scores, and price tracking. Supports 60+ search filters, multiple locations per run, and outputs data optimized for RAG pipelines and answer engines. - **URL**: https://apify.com/datacut/idealista-scraper.md - **Developed by:** [Datacut](https://apify.com/datacut) (community) - **Categories:** AI, Real estate, Developer tools - **Stats:** 6 total users, 2 monthly users, 100.0% runs succeeded, NaN bookmarks - **User rating**: No ratings yet ## Pricing from $0.005 / property listing 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 a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases. 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. In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js.md): ```bash npm install apify-client ``` In Python projects, use official [Python client library](https://docs.apify.com/api/client/python.md): ```bash pip install apify-client ``` In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md): ````bash # MacOS / Linux curl -fsSL https://apify.com/install-cli.sh | bash # Windows irm https://apify.com/install-cli.ps1 | iex ```bash In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/platform/integrations/mcp.md). If your project is in a different language, use 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 ## Idealista Scraper Fast, lightweight scraper for Idealista real estate listings in Spain, Italy, and Portugal. Extracts 100+ fields per listing with AI-ready enrichment for RAG, vector search, and answer engines. Built by [datacut](https://apify.com/datacut) — AI-first data extraction. ### Features - **60+ search filters** — every filter Idealista supports (property type, price, size, features, rental criteria, and more) - **Full property details** — floor plans, energy certificates, building characteristics, agent info - **Engagement stats** — views, emails, favorites, shares per listing - **AI/LLM enrichment** — 15+ computed fields for RAG, AEO, classification, and analytics - **Price tracking** — cross-run price change detection with delta and percentage - **3 countries** — Spain (13,400+ locations), Italy, Portugal - **Multiple locations** — search across multiple cities in a single run with deduplication - **Self-healing** — adaptive pacing, circuit breaker, identity rotation, checkpoint/resume - **Proxy pool** — rotate across multiple HTTP/HTTPS proxies on identity change - **Graceful shutdown** — SIGINT/SIGTERM saves progress, resume from checkpoint - **Discord/Slack alerts** — breaker trips, identity rotations, run summaries - **Low resource usage** — ~15MB Docker image, 128MB RAM, no browser needed ### Quick Start ```bash ## Build go build -o ./idealista-scraper . ## Search by city name APIFY_INPUT='{"location":"Madrid","maxItems":10}' ./idealista-scraper ## Search with filters APIFY_INPUT='{"location":"Barcelona","operation":"rent","maxItems":20,"minPrice":500,"maxPrice":1500,"bedrooms":"2","elevator":true}' ./idealista-scraper ## Full details + stats (best for AI) APIFY_INPUT='{"location":"Madrid","maxItems":5,"fetchDetails":true,"fetchStats":true}' ./idealista-scraper ## Multiple locations APIFY_INPUT='{"locations":["Madrid","Barcelona","Valencia"],"maxItems":100}' ./idealista-scraper ## With proxy pool + Discord alerts APIFY_INPUT='{"location":"Madrid","maxItems":50,"proxyUrls":["http://user:pass@proxy1:8080"],"webhookUrl":"https://discord.com/api/webhooks/..."}' ./idealista-scraper ## Docker docker build -t idealista-scraper . docker run -e APIFY_INPUT='{"location":"Madrid","maxItems":5}' idealista-scraper ```` ### Input #### Core | Param | Type | Default | Description | |-------|------|---------|-------------| | `country` | string | `"es"` | Country: `es` (Spain), `it` (Italy), `pt` (Portugal) | | `operation` | string | `"sale"` | `sale` or `rent` | | `propertyType` | string | `"homes"` | `homes`, `offices`, `premises`, `garages`, `lands`, `bedrooms`, `storageRooms`, `buildings` | | `location` | string | | City name (`"Madrid"`) or location ID (`"0-EU-ES-28"`) | | `locations` | string\[] | | Multiple locations, max 10 (searched sequentially, results deduplicated) | | `propertyCodes` | string\[] | | Specific listing IDs to fetch (max 100) | | `maxItems` | int | `50` | Max listings to collect (max 500 per run) | | `sortBy` | string | `"relevance"` | `relevance`, `price_asc`, `price_desc`, `size_asc`, `size_desc`, `date_desc`, `price_per_m2_asc`, `price_drop` | #### Price & Size | Param | Type | Description | |-------|------|-------------| | `minPrice` / `maxPrice` | float | Price range (EUR) | | `minSize` / `maxSize` | float | Size range (m²) | | `bedrooms` | string | Bedrooms (e.g. `"2"`, `"3+"`) | | `bathrooms` | string | Bathrooms | #### Property Subtypes (boolean) `flat`, `penthouse`, `duplex`, `studio`, `chalet`, `countryHouse` #### Building Features (boolean) `airConditioning`, `elevator`, `garage`, `garden`, `swimmingPool`, `terrace`, `storeRoom`, `builtinWardrobes`, `exterior`, `heating`, `hotWater`, `security`, `corner`, `smokeVentilation`, `clotheslineSpace`, `accessible`, `luxury`, `seaViews` #### Multimedia (boolean) `virtualTour`, `pictures`, `professionalVideo`, `hasPlan` #### Building Details | Param | Type | Description | |-------|------|-------------| | `furnished` | string | Furnishing status | | `preservations` | string | Conservation status | | `floorHeights` | string | Floor height filter | | `buildingType` | string | Building type | | `buildingTypes` | string\[] | Multiple building types | #### Listing Type (boolean) `bankOffer`, `newDevelopment`, `stateSubsidized`, `rentToOwn`, `finished`, `transfer` #### Owner | Param | Type | Description | |-------|------|-------------| | `ownerType` | string | `"privateOwner"` or `"professionalOwner"` | #### Rental / Roommate | Param | Type | Description | |-------|------|-------------| | `petsAllowed` | bool | Pets allowed | | `petsPolicy` | string | Pet policy | | `childrenAllowed` | bool | Children allowed | | `couplesAllowed` | bool | Couples allowed | | `gayPartners` | bool | LGBTQ+ friendly | | `newGender` | string | Gender preference | | `housemates` | string | Housemate info | | `occupation` | string | Occupancy type | | `ownerNotLiving` | bool | Owner not living in property | | `smokingPolicy` | string | Smoking policy | #### Other Filters | Param | Type | Description | |-------|------|-------------| | `sinceDate` | string | Listing date filter (`T`=today, `W`=week, `M`=month, `Y`=year) | | `distance` | int | Distance radius (meters) | | `promotionId` | string | Promotion ID | | `agency` | string | Agency filter | | `landTypes` | string\[] | Land type filter | | `typologies` | string\[] | Property typologies | | `subTypology` | string\[] | Sub-typologies | #### Data Fetching | Param | Type | Default | Description | |-------|------|---------|-------------| | `fetchDetails` | bool | `false` | Full details per listing (energy cert, characteristics, comments). +1 API call/listing. | | `fetchStats` | bool | `false` | Engagement stats (views, emails, favorites). +1 API call/listing. | #### Proxy & Notifications | Param | Type | Description | |-------|------|-------------| | `proxyUrl` | string | Single proxy URL | | `proxyUrls` | string\[] | Proxy pool — rotated on identity change | | `webhookUrl` | string | Discord/Slack webhook for real-time alerts | ### Output #### Base Listing Fields Every listing includes all fields returned by Idealista's API: `propertyCode`, `propertyType`, `operation`, `country`, `price`, `priceByArea`, `size`, `rooms`, `bathrooms`, `floor`, `address`, `municipality`, `district`, `neighborhood`, `province`, `latitude`, `longitude`, `description`, `url`, `thumbnail`, `status`, `exterior`, `hasLift`, `numPhotos`, `contactInfo`, `features`, `parkingSpace`, `multimedia`, `suggestedTexts`, `priceDropPercentage`, `priceDropValue` With `fetchDetails: true`: `moreCharacteristics`, `ubication`, `energyCertification`, `propertyComment`, `comments`, `priceReferenceIndex`, `labels` With `fetchStats: true`: `stats` (views, emails, favourites, shares) #### AI/LLM Enrichment Every listing is enriched with computed fields optimized for AI consumption: | Field | Type | Description | |-------|------|-------------| | `aiSummary` | string | Natural language paragraph — reads like an analyst brief. Includes engagement, area pricing, amenities, market signals. | | `llmContext` | object | Flat, denormalized key-value map. No nested JSON to parse. Omits empty/null/zero values to save tokens. | | `keyFacts` | string\[] | Scannable bullet-point array: `["3-bed/2-bath, 120m²", "€10/m²", "A/C", "Pool", "90 views, 27 saves"]` | | `qaReady` | object\[] | Pre-computed Q\&A pairs for Answer Engine Optimization (AEO). Matches how people search: *"How much is a 3-bedroom flat to rent in Sitges?"* | | `amenities` | string\[] | Flat, deduplicated amenity list extracted from all nested sources (features, characteristics, parking, energy cert). | | `tags` | string\[] | Keyword array for faceted search and RAG classification. Covers: type, operation, features, price bracket, engagement tier, location, seller type. | | `searchableText` | string | Dense plain-text blob for vector embeddings and full-text search. Includes both metric and imperial, English translations from multilingual comments. | | `engagementScore` | float | Weighted 0-100 composite of views, favorites, contacts, shares. Log-scaled. | | `priceContext` | object | Area comparison: `vsAreaMedianPercent`, `pricePosition` (well-below-average to well-above-average), `areaMedianPricePerM2`. Falls back from municipality to province for small datasets. | | `dataQuality` | object | Completeness score (0-100) with weighted field breakdown and list of missing fields. | | `rankInArea` | object | Relative position within municipality: `cheapest-in-area`, `largest-in-area`, `most-popular-in-area`, `priceRank`, `totalInArea`. | | `dealIndicator` | string | Market timing signal: `hot-deal`, `price-reduced`, `just-listed`, `trending`, `fresh`, `stable`, `aging`, `stale` | | `daysOnMarket` | int | Multi-signal estimated listing age (engagement-based when API dates are unreliable) | | `daysOnMarketEstimated` | bool | `true` when age is estimated from engagement data rather than exact dates | | `priceSegment` | string | `budget`, `mid`, `upper`, `premium`, `luxury` (rent-aware thresholds) | | `goldenVisaEligible` | bool | Investment threshold check (>=500k in ES/PT) | | `sizeInSqft` | float | Imperial size conversion | | `priceByAreaSqft` | float | Price per sqft | | `googleMapsUrl` | string | Direct Google Maps link | #### Price Tracking On repeat runs, each listing gets: | Field | Type | Description | |-------|------|-------------| | `isNew` | bool | `true` if listing wasn't in previous run | | `priceChange` | float | Absolute price change (EUR) | | `previousPrice` | float | Price from previous run | | `priceChangePercent` | float | Percentage change | #### Example AI Summary > 3-bedroom flat for rent at €1,600/month in Sitges, Barcelona. The property offers 102m² (1,098 sqft) with 3 bedrooms and 2 bathrooms on floor 1. Features include elevator, exterior-facing, parking available, and pets allowed. Very high interest: 2937 views, 236 saves. At €16/m², this is 10% above the area median. Seasonal rental — limited-term contract. Listed by ABC Inmobiliaria (agency). #### Example keyFacts ```json ["3-bed/2-bath, 102m²", "€16/m²", "Good condition", "Elevator", "Exterior", "Parking", "Pets OK", "Energy INPROCESS", "2937 views, 236 saves", "Seasonal rental"] ``` #### Example qaReady ```json [ {"q": "How much is a 3-bedroom flat to rent in Sitges?", "a": "€1,600/month for a 102m² 3-bedroom flat (listing 109185499)."}, {"q": "How big are 3-bedroom flats in Sitges?", "a": "This 3-bedroom flat in Sitges is 102m² (1,098 sqft)."}, {"q": "What amenities does this flat in Sitges have?", "a": "This property includes: elevator, exterior-facing, parking available, and pets allowed."}, {"q": "Are there pet-friendly flats for rent in Sitges?", "a": "Yes — this flat in Sitges allows pets. €1,600/month, 102m²."}, {"q": "Is this flat in Sitges popular?", "a": "It has 2937 views and 236 saves, with an engagement score of 100/100."} ] ``` ### Resilience | Layer | Mechanism | Purpose | |-------|-----------|---------| | Timing | Poisson-distributed delays | Human-like, non-fingerpritable inter-request timing | | Pacing | Adaptive pacer (sliding window) | Learn safe throughput from observed responses | | Identity | UA rotation + device fingerprint | New identity on every rotation | | Proxy | Pool rotation on identity change | Distribute traffic across IPs | | Recovery | Circuit breaker with slow-start | Stop on repeated failures, probe cautiously | | Lifecycle | Session retirement after N requests | Preemptive rotation before detection | | Auth | Proactive token refresh | Refresh before expiry | | Resumability | Checkpoint per page | Resume from crash without re-scraping | | Shutdown | SIGINT/SIGTERM handler | Save partial results on graceful stop | | Alerts | Discord/Slack webhooks | Real-time visibility into run events | ### Tests ```bash go test ./... ``` ### Countries | Code | Country | Locations | |------|---------|-----------| | `es` | Spain | 13,400+ | | `it` | Italy | Bundled | | `pt` | Portugal | Bundled | ### Deployment #### Docker ```bash docker build -t idealista-scraper . docker run -e APIFY_INPUT='{"location":"Madrid","maxItems":5}' idealista-scraper ``` #### Apify Set environment variables: - `APIFY_TOKEN` — API token - `APIFY_DEFAULT_KEY_VALUE_STORE_ID` — Input store - `APIFY_DEFAULT_DATASET_ID` — Output dataset Or use file-based I/O: - Input: `storage/key_value_stores/default/INPUT.json` - Output: `storage/datasets/default/*.json` - Report: `storage/key_value_stores/default/REPORT.md` #### Recommended Settings | Setting | Value | Why | |---------|-------|-----| | Memory | 128 MB | Pure HTTP, no browser | | Timeout | 3600s | Allows large multi-location runs | | Proxy | Residential | Datacenter IPs are blocked | | `fetchDetails` | `true` | Unlocks energy cert, full descriptions, multilingual comments | | `fetchStats` | `true` | Unlocks engagement data (views, favorites) — powers AI enrichment | # Actor input Schema ## `country` (type: `string`): Which Idealista site to search. ## `operation` (type: `string`): Search for properties for sale or rent. ## `propertyType` (type: `string`): Type of property to search for. ## `location` (type: `string`): City name (e.g. 'Madrid', 'Barcelona') or Idealista location ID. City names are resolved automatically. ## `locations` (type: `array`): Search multiple cities in one run (max 10). Results are deduplicated. Use this OR 'location', not both. ## `maxItems` (type: `integer`): Maximum number of listings to scrape. Capped at 500 per run to avoid detection. ## `sortBy` (type: `string`): How to sort search results. ## `fetchDetails` (type: `boolean`): Fetch full property details (energy cert, characteristics, comments). 1 extra API call per listing. ## `fetchStats` (type: `boolean`): Fetch engagement stats (views, emails, favourites, shares). 1 extra API call per listing. ## `minPrice` (type: `number`): Minimum price in euros (sale) or euros/month (rent). Leave empty for no limit. ## `maxPrice` (type: `number`): Maximum price in euros (sale) or euros/month (rent). Leave empty for no limit. ## `minSize` (type: `number`): Minimum property size in square meters. ## `maxSize` (type: `number`): Maximum property size in square meters. ## `bedrooms` (type: `string`): Minimum number of bedrooms. ## `bathrooms` (type: `string`): Minimum number of bathrooms. ## `publicationDate` (type: `string`): Filter by listing age. ## `condition` (type: `string`): Filter by property condition. ## `furnished` (type: `string`): Filter by furnishing level (mainly for rentals). ## `ownerType` (type: `string`): Filter by property owner type. ## `floor` (type: `string`): Filter by apartment floor level. ## `flat` (type: `boolean`): Only show flats/apartments. ## `penthouse` (type: `boolean`): Only show penthouses. ## `duplex` (type: `boolean`): Only show duplexes. ## `studio` (type: `boolean`): Only show studios. ## `chalet` (type: `boolean`): Only show chalets/houses. ## `countryHouse` (type: `boolean`): Only show country houses / fincas. ## `airConditioning` (type: `boolean`): Only show properties with air conditioning. ## `elevator` (type: `boolean`): Only show properties with elevator access. ## `garage` (type: `boolean`): Only show properties with garage or parking. ## `garden` (type: `boolean`): Only show properties with garden. ## `swimmingPool` (type: `boolean`): Only show properties with swimming pool. ## `terrace` (type: `boolean`): Only show properties with terrace. ## `storeRoom` (type: `boolean`): Only show properties with storage room. ## `builtinWardrobes` (type: `boolean`): Only show properties with built-in wardrobes. ## `exterior` (type: `boolean`): Only show exterior-facing properties. ## `heating` (type: `boolean`): Only show properties with heating. ## `accessible` (type: `boolean`): Only show accessible properties. ## `luxury` (type: `boolean`): Only show luxury properties. ## `seaViews` (type: `boolean`): Only show properties with sea views. ## `bankOffer` (type: `boolean`): Only show bank-owned properties. ## `newDevelopment` (type: `boolean`): Only show new development listings. ## `rentToOwn` (type: `boolean`): Only show rent-to-own properties. ## `stateSubsidized` (type: `boolean`): Only show state-subsidized housing. ## `petsAllowed` (type: `boolean`): Only show rentals that allow pets. ## `smokingPolicy` (type: `string`): Filter by smoking policy. ## `newGender` (type: `string`): Roommate gender preference (only for shared rooms). ## `occupation` (type: `string`): Roommate occupation filter (only for shared rooms). ## `propertyCodes` (type: `array`): Specific Idealista property codes to fetch directly (max 100). Skips search and goes straight to detail. ## `proxyConfiguration` (type: `object`): Select proxies. Residential proxies recommended for best results. ## `webhookUrl` (type: `string`): Discord or Slack webhook URL for real-time alerts (breaker trips, run completion, errors). ## Actor input object example ```json { "country": "es", "operation": "sale", "propertyType": "homes", "location": "Madrid", "maxItems": 5, "sortBy": "relevance", "fetchDetails": true, "fetchStats": true, "bedrooms": "", "bathrooms": "", "publicationDate": "", "condition": "", "furnished": "", "ownerType": "", "floor": "", "flat": false, "penthouse": false, "duplex": false, "studio": false, "chalet": false, "countryHouse": false, "airConditioning": false, "elevator": false, "garage": false, "garden": false, "swimmingPool": false, "terrace": false, "storeRoom": false, "builtinWardrobes": false, "exterior": false, "heating": false, "accessible": false, "luxury": false, "seaViews": false, "bankOffer": false, "newDevelopment": false, "rentToOwn": false, "stateSubsidized": false, "petsAllowed": false, "smokingPolicy": "", "newGender": "", "occupation": "", "proxyConfiguration": { "useApifyProxy": true, "apifyProxyGroups": [ "RESIDENTIAL" ] } } ``` # Actor output Schema ## `overview` (type: `string`): No description ## `aiEnrichment` (type: `string`): No description ## `priceTracking` (type: `string`): No description ## `allData` (type: `string`): No description ## `report` (type: `string`): No description # 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 '' with your token const client = new ApifyClient({ token: '', }); // Prepare Actor input const input = { "location": "Madrid", "maxItems": 5, "fetchDetails": true, "fetchStats": true, "proxyConfiguration": { "useApifyProxy": true, "apifyProxyGroups": [ "RESIDENTIAL" ] } }; // Run the Actor and wait for it to finish const run = await client.actor("datacut/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 '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = { "location": "Madrid", "maxItems": 5, "fetchDetails": True, "fetchStats": True, "proxyConfiguration": { "useApifyProxy": True, "apifyProxyGroups": ["RESIDENTIAL"], }, } # Run the Actor and wait for it to finish run = client.actor("datacut/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 '{ "location": "Madrid", "maxItems": 5, "fetchDetails": true, "fetchStats": true, "proxyConfiguration": { "useApifyProxy": true, "apifyProxyGroups": [ "RESIDENTIAL" ] } }' | apify call datacut/idealista-scraper --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=datacut/idealista-scraper", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "Idealista Scraper", "description": "Fast Idealista scraper for Spain, Italy, and Portugal. Returns 100+ fields per listing including AI summaries, Q&A pairs, deal signals, engagement scores, and price tracking. Supports 60+ search filters, multiple locations per run, and outputs data optimized for RAG pipelines and answer engines.", "version": "1.0", "x-build-id": "kuoTw31zBJn98qUj5" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/datacut~idealista-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-datacut-idealista-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } }, "/acts/datacut~idealista-scraper/runs": { "post": { "operationId": "runs-sync-datacut-idealista-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor and returns information about the initiated run in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/runsResponseSchema" } } } } } } }, "/acts/datacut~idealista-scraper/run-sync": { "post": { "operationId": "run-sync-datacut-idealista-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } } }, "components": { "schemas": { "inputSchema": { "type": "object", "properties": { "country": { "title": "Country", "enum": [ "es", "it", "pt" ], "type": "string", "description": "Which Idealista site to search.", "default": "es" }, "operation": { "title": "Operation", "enum": [ "sale", "rent" ], "type": "string", "description": "Search for properties for sale or rent.", "default": "sale" }, "propertyType": { "title": "Property Type", "enum": [ "homes", "offices", "premises", "garages", "lands", "storageRooms", "buildings", "bedrooms" ], "type": "string", "description": "Type of property to search for.", "default": "homes" }, "location": { "title": "Location", "type": "string", "description": "City name (e.g. 'Madrid', 'Barcelona') or Idealista location ID. City names are resolved automatically." }, "locations": { "title": "Multiple Locations", "type": "array", "description": "Search multiple cities in one run (max 10). Results are deduplicated. Use this OR 'location', not both.", "items": { "type": "string" } }, "maxItems": { "title": "Max Items", "minimum": 1, "maximum": 500, "type": "integer", "description": "Maximum number of listings to scrape. Capped at 500 per run to avoid detection.", "default": 50 }, "sortBy": { "title": "Sort By", "enum": [ "relevance", "price_asc", "price_desc", "size_asc", "size_desc", "date_desc", "price_per_m2_asc", "price_drop" ], "type": "string", "description": "How to sort search results.", "default": "relevance" }, "fetchDetails": { "title": "Fetch Details", "type": "boolean", "description": "Fetch full property details (energy cert, characteristics, comments). 1 extra API call per listing.", "default": false }, "fetchStats": { "title": "Fetch Stats", "type": "boolean", "description": "Fetch engagement stats (views, emails, favourites, shares). 1 extra API call per listing.", "default": false }, "minPrice": { "title": "Min Price", "type": "number", "description": "Minimum price in euros (sale) or euros/month (rent). Leave empty for no limit." }, "maxPrice": { "title": "Max Price", "type": "number", "description": "Maximum price in euros (sale) or euros/month (rent). Leave empty for no limit." }, "minSize": { "title": "Min Size (m²)", "type": "number", "description": "Minimum property size in square meters." }, "maxSize": { "title": "Max Size (m²)", "type": "number", "description": "Maximum property size in square meters." }, "bedrooms": { "title": "Bedrooms", "enum": [ "", "0", "1", "2", "3", "4" ], "type": "string", "description": "Minimum number of bedrooms.", "default": "" }, "bathrooms": { "title": "Bathrooms", "enum": [ "", "1", "2", "3" ], "type": "string", "description": "Minimum number of bathrooms.", "default": "" }, "publicationDate": { "title": "Published Since", "enum": [ "", "T", "W", "M", "Y" ], "type": "string", "description": "Filter by listing age.", "default": "" }, "condition": { "title": "Condition", "enum": [ "", "newConstruction", "goodCondition", "needsRenovation" ], "type": "string", "description": "Filter by property condition.", "default": "" }, "furnished": { "title": "Furnished", "enum": [ "", "furnished", "partiallyFurnished", "unfurnished" ], "type": "string", "description": "Filter by furnishing level (mainly for rentals).", "default": "" }, "ownerType": { "title": "Owner Type", "enum": [ "", "privateOwner", "professionalOwner" ], "type": "string", "description": "Filter by property owner type.", "default": "" }, "floor": { "title": "Floor", "enum": [ "", "groundFloor", "firstFloor", "secondFloor", "thirdFloor", "fourthOrHigher" ], "type": "string", "description": "Filter by apartment floor level.", "default": "" }, "flat": { "title": "Flat / Apartment", "type": "boolean", "description": "Only show flats/apartments.", "default": false }, "penthouse": { "title": "Penthouse", "type": "boolean", "description": "Only show penthouses.", "default": false }, "duplex": { "title": "Duplex", "type": "boolean", "description": "Only show duplexes.", "default": false }, "studio": { "title": "Studio", "type": "boolean", "description": "Only show studios.", "default": false }, "chalet": { "title": "Chalet / House", "type": "boolean", "description": "Only show chalets/houses.", "default": false }, "countryHouse": { "title": "Country House", "type": "boolean", "description": "Only show country houses / fincas.", "default": false }, "airConditioning": { "title": "Air Conditioning", "type": "boolean", "description": "Only show properties with air conditioning.", "default": false }, "elevator": { "title": "Elevator", "type": "boolean", "description": "Only show properties with elevator access.", "default": false }, "garage": { "title": "Garage / Parking", "type": "boolean", "description": "Only show properties with garage or parking.", "default": false }, "garden": { "title": "Garden", "type": "boolean", "description": "Only show properties with garden.", "default": false }, "swimmingPool": { "title": "Swimming Pool", "type": "boolean", "description": "Only show properties with swimming pool.", "default": false }, "terrace": { "title": "Terrace", "type": "boolean", "description": "Only show properties with terrace.", "default": false }, "storeRoom": { "title": "Storage Room", "type": "boolean", "description": "Only show properties with storage room.", "default": false }, "builtinWardrobes": { "title": "Built-in Wardrobes", "type": "boolean", "description": "Only show properties with built-in wardrobes.", "default": false }, "exterior": { "title": "Exterior", "type": "boolean", "description": "Only show exterior-facing properties.", "default": false }, "heating": { "title": "Heating", "type": "boolean", "description": "Only show properties with heating.", "default": false }, "accessible": { "title": "Accessible", "type": "boolean", "description": "Only show accessible properties.", "default": false }, "luxury": { "title": "Luxury", "type": "boolean", "description": "Only show luxury properties.", "default": false }, "seaViews": { "title": "Sea Views", "type": "boolean", "description": "Only show properties with sea views.", "default": false }, "bankOffer": { "title": "Bank Offer", "type": "boolean", "description": "Only show bank-owned properties.", "default": false }, "newDevelopment": { "title": "New Development", "type": "boolean", "description": "Only show new development listings.", "default": false }, "rentToOwn": { "title": "Rent to Own", "type": "boolean", "description": "Only show rent-to-own properties.", "default": false }, "stateSubsidized": { "title": "State Subsidized (VPO)", "type": "boolean", "description": "Only show state-subsidized housing.", "default": false }, "petsAllowed": { "title": "Pets Allowed", "type": "boolean", "description": "Only show rentals that allow pets.", "default": false }, "smokingPolicy": { "title": "Smoking Policy", "enum": [ "", "allowed", "notAllowed" ], "type": "string", "description": "Filter by smoking policy.", "default": "" }, "newGender": { "title": "Gender Preference", "enum": [ "", "mixed", "female", "male" ], "type": "string", "description": "Roommate gender preference (only for shared rooms).", "default": "" }, "occupation": { "title": "Occupation", "enum": [ "", "worker", "student" ], "type": "string", "description": "Roommate occupation filter (only for shared rooms).", "default": "" }, "propertyCodes": { "title": "Property Codes", "type": "array", "description": "Specific Idealista property codes to fetch directly (max 100). Skips search and goes straight to detail.", "items": { "type": "string" } }, "proxyConfiguration": { "title": "Proxy Configuration", "type": "object", "description": "Select proxies. Residential proxies recommended for best results.", "default": { "useApifyProxy": true, "apifyProxyGroups": [ "RESIDENTIAL" ] } }, "webhookUrl": { "title": "Webhook URL", "type": "string", "description": "Discord or Slack webhook URL for real-time alerts (breaker trips, run completion, errors)." } } }, "runsResponseSchema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "actId": { "type": "string" }, "userId": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "finishedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "status": { "type": "string", "example": "READY" }, "meta": { "type": "object", "properties": { "origin": { "type": "string", "example": "API" }, "userAgent": { "type": "string" } } }, "stats": { "type": "object", "properties": { "inputBodyLen": { "type": "integer", "example": 2000 }, "rebootCount": { "type": "integer", "example": 0 }, "restartCount": { "type": "integer", "example": 0 }, "resurrectCount": { "type": "integer", "example": 0 }, "computeUnits": { "type": "integer", "example": 0 } } }, "options": { "type": "object", "properties": { "build": { "type": "string", "example": "latest" }, "timeoutSecs": { "type": "integer", "example": 300 }, "memoryMbytes": { "type": "integer", "example": 1024 }, "diskMbytes": { "type": "integer", "example": 2048 } } }, "buildId": { "type": "string" }, "defaultKeyValueStoreId": { "type": "string" }, "defaultDatasetId": { "type": "string" }, "defaultRequestQueueId": { "type": "string" }, "buildNumber": { "type": "string", "example": "1.0.0" }, "containerUrl": { "type": "string" }, "usage": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "integer", "example": 1 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } }, "usageTotalUsd": { "type": "number", "example": 0.00005 }, "usageUsd": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "number", "example": 0.00005 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } } } } } } } } } ```