{ "openapi": "3.0.1", "info": { "title": "Idealista Scraper — Extract Listings, Prices & Agency Contacts", "description": "Scrape Idealista real estate listings across Spain, Italy & Portugal. Extract price, GPS coordinates, energy rating, rooms, size, photos, and agency contact. DataDome bypass with stealth browser. Export scraped data, run the scraper via API, schedule and monitor runs, or integrate with other tools.", "version": "1.0", "x-build-id": "WaYl44tXYcZM7Vbt0" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/muhammadafzal~idealista-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-muhammadafzal-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/muhammadafzal~idealista-scraper/runs": { "post": { "operationId": "runs-sync-muhammadafzal-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/muhammadafzal~idealista-scraper/run-sync": { "post": { "operationId": "run-sync-muhammadafzal-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": { "startUrls": { "title": "Start URLs (full Idealista search URLs)", "type": "array", "description": "Use this field when the user provides one or more full Idealista search URLs (e.g. https://www.idealista.com/venta-viviendas/madrid-madrid/). Do NOT use this when the user describes a city or location — use location/country/operation instead. All UI filters in the URL are respected as passthrough.", "items": { "type": "object", "properties": { "url": { "title": "URL", "type": "string", "description": "Full Idealista search URL (e.g. https://www.idealista.com/venta-viviendas/madrid-madrid/). All UI filters in the URL are respected as passthrough." } }, "required": [ "url" ] } }, "operation": { "title": "Operation", "enum": [ "sale", "rent" ], "type": "string", "description": "Listing operation: sale or rent. Use with location + country. Ignored when startUrls is provided.", "default": "sale" }, "propertyType": { "title": "Property Type", "enum": [ "homes", "newDevelopments", "offices", "premises", "garages", "lands", "storageRooms", "buildings", "bedrooms" ], "type": "string", "description": "Type of property to scrape. Ignored when startUrls is provided.", "default": "homes" }, "country": { "title": "Country", "enum": [ "es", "it", "pt" ], "type": "string", "description": "Idealista country site. es=idealista.com, it=idealista.it, pt=idealista.pt. Determines residential proxy region.", "default": "es" }, "location": { "title": "Location (URL slug or city name)", "type": "string", "description": "Idealista location URL slug (e.g. 'madrid-comunidad_de_madrid' or 'barcelona-barcelona') OR a plain city name (best-effort resolution). Use this when the user names a place — NOT when they provide a full URL (use startUrls for URLs).", "default": "madrid-madrid" }, "maxItems": { "title": "Max items", "minimum": 1, "maximum": 1800, "type": "integer", "description": "Maximum number of listings to extract. Idealista caps search results at ~1800 per query. The actor will split queries by price band to bypass this cap when set above 1500.", "default": 100 }, "sortBy": { "title": "Sort By", "enum": [ "relevance", "lowestPrice", "highestPrice", "mostRecent", "biggest", "smallest", "lowestPriceM2", "highestPriceM2" ], "type": "string", "description": "Sorting method applied to search results.", "default": "relevance" }, "minPrice": { "title": "Min price (€)", "minimum": 0, "type": "integer", "description": "Minimum price filter. 0 = any.", "default": 0 }, "maxPrice": { "title": "Max price (€)", "minimum": 0, "type": "integer", "description": "Maximum price filter. 0 = any.", "default": 0 }, "minSize": { "title": "Min size (m²)", "minimum": 0, "type": "integer", "description": "Minimum size in square meters. 0 = any.", "default": 0 }, "maxSize": { "title": "Max size (m²)", "minimum": 0, "type": "integer", "description": "Maximum size in square meters. 0 = any.", "default": 0 }, "publicationDate": { "title": "Publication date", "enum": [ "", "Y", "T", "W", "M" ], "type": "string", "description": "Filter by publication recency. Empty = any. Use W/T/M for incremental scheduled runs.", "default": "" }, "bedrooms": { "title": "Bedrooms", "uniqueItems": true, "type": "array", "description": "Bedroom counts to include. Empty = any. Idealista uses '0','1','2','3','4','5'.", "items": { "type": "string" }, "default": [] }, "bathrooms": { "title": "Bathrooms", "uniqueItems": true, "type": "array", "description": "Bathroom counts to include. Empty = any.", "items": { "type": "string" }, "default": [] }, "homeType": { "title": "Home type", "uniqueItems": true, "type": "array", "description": "Home subtypes. Only used when propertyType=homes. Empty = any.", "items": { "type": "string" }, "default": [] }, "condition": { "title": "Condition", "uniqueItems": true, "type": "array", "description": "Property condition filter. Empty = any.", "items": { "type": "string" }, "default": [] }, "floor": { "title": "Floor", "uniqueItems": true, "type": "array", "description": "Floor positions. Empty = any.", "items": { "type": "string" }, "default": [] }, "airConditioning": { "title": "Air conditioning", "type": "boolean", "description": "Only show listings with air conditioning.", "default": false }, "fittedWardrobes": { "title": "Fitted wardrobes", "type": "boolean", "description": "Only show listings with fitted wardrobes.", "default": false }, "lift": { "title": "Lift", "type": "boolean", "description": "Only show listings with a lift.", "default": false }, "balcony": { "title": "Balcony", "type": "boolean", "description": "Only show listings with a balcony.", "default": false }, "terrace": { "title": "Terrace", "type": "boolean", "description": "Only show listings with a terrace.", "default": false }, "exterior": { "title": "Exterior", "type": "boolean", "description": "Only show exterior-facing listings.", "default": false }, "garage": { "title": "Garage", "type": "boolean", "description": "Only show listings with garage / parking.", "default": false }, "garden": { "title": "Garden", "type": "boolean", "description": "Only show listings with a garden.", "default": false }, "swimmingPool": { "title": "Swimming pool", "type": "boolean", "description": "Only show listings with swimming pool.", "default": false }, "storageRoom": { "title": "Storage room", "type": "boolean", "description": "Only show listings with storage room.", "default": false }, "accessible": { "title": "Accessible", "type": "boolean", "description": "Only show wheelchair-accessible listings.", "default": false }, "seaViews": { "title": "Sea views", "type": "boolean", "description": "Only show listings with sea views.", "default": false }, "luxury": { "title": "Luxury", "type": "boolean", "description": "Only show luxury listings.", "default": false }, "plan": { "title": "Floor plan available", "type": "boolean", "description": "Only show listings with floor plan.", "default": false }, "virtualTour": { "title": "Virtual tour available", "type": "boolean", "description": "Only show listings with virtual tour.", "default": false }, "fetchDetails": { "title": "⭐ Fetch listing details (richer data, slower)", "type": "boolean", "description": "Visit each listing's detail page to enrich with address, geo coords, bathrooms, energy rating, agency phone, and full amenities. ~10× more requests — slower and higher block risk. Adds the 'enriched-listing' charge on top of standard dataset-item billing.", "default": false }, "maxConcurrency": { "title": "Max concurrency", "minimum": 1, "maximum": 10, "type": "integer", "description": "Maximum concurrent browser pages for detail-page fetches. Lower for hardened DataDome regions.", "default": 3 }, "customProxyUrl": { "title": "Custom Proxy URL (BYO premium residential)", "type": "string", "description": "Optional: full proxy URL (http://user:pass@host:port). Overrides Apify proxy. Recommended for hardened DataDome targets — Apify residential pool may be burned. Use Decodo / Bright Data / IPRoyal ES residential." }, "proxyConfiguration": { "title": "Proxy Configuration", "type": "object", "description": "Apify proxy. Defaults to residential Spain (ES). Change apifyProxyCountry to IT or PT when scraping idealista.it / idealista.pt.", "default": { "useApifyProxy": true, "apifyProxyGroups": [ "RESIDENTIAL" ], "apifyProxyCountry": "ES" } } } }, "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 } } } } } } } } } }