{ "openapi": "3.0.1", "info": { "title": "Idealista Data, API & Scraper — Spain, Italy, Portugal", "description": "Idealista scraper and API alternative for Spain, Italy and Portugal. Search sale and rental homes, new builds, rooms, garages, offices, land and commercial units by city, search URL, map area or CSV. Rows carry price, size, rooms, price drops, energy rating, photos and agency phones.", "version": "2.0", "x-build-id": "WKVvDghuf54kf6GOZ" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/sian.agency~smart-idealista-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-sian.agency-smart-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/sian.agency~smart-idealista-scraper/runs": { "post": { "operationId": "runs-sync-sian.agency-smart-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/sian.agency~smart-idealista-scraper/run-sync": { "post": { "operationId": "run-sync-sian.agency-smart-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": "🌍 Select the Idealista country domain", "default": "es" }, "operation": { "title": "🤝 Operation", "enum": [ "sale", "rent" ], "type": "string", "description": "🏠 What type of listing?", "default": "rent" }, "endpoint": { "title": "🗂️ Property Category", "enum": [ "listhomes", "listnewhomes", "liststoragerooms", "listbuildings", "listlands", "listgarages", "listcommercialproperties", "listoffices", "listrooms" ], "type": "string", "description": "🏘️ Select the type of property category to search", "default": "listhomes" }, "searchUrl": { "title": "🔗 Paste a Search URL", "type": "string", "description": "Paste any Idealista search-results URL and we'll auto-detect the location + filters from the page.\n\n**Example:** `https://www.idealista.com/en/venta-terrenos/jaen/la-loma-y-las-villas/`\n\n💸 **Pricing:** $0.005 per URL + $0.003 per property delivered (PAID tier only)." }, "polygonUrl": { "title": "🗺️ Paste a Polygon (Areas) URL", "type": "string", "description": "Paste an Idealista Areas URL with a drawn-polygon shape parameter.\n\n**Example:** `https://www.idealista.com/en/areas/venta-viviendas/?shape=((...))`\n\n💸 **Pricing:** $0.01 per search + $0.003 per property (PAID tier only)." }, "deepSingleUrl": { "title": "🔎 Deep-Scrape a Single Listing URL", "type": "string", "description": "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).\n\n**Example:** `https://www.idealista.com/en/inmueble/111577630/`\n\n💸 **Pricing:** $0.05 per URL (PAID tier only — replaces the per-property charge)." }, "deepFieldSet": { "title": "📋 Deep Mode — Field Set", "enum": [ "standard", "extended" ], "type": "string", "description": "Controls how many fields the deep-scrape returns.\n\n- **standard**: only fields the existing search API already exposes\n- **extended**: adds energy certificate, year built, community fees, IBI, price history, floor-plan + 3D-tour URLs", "default": "extended" }, "agencySlugs": { "title": "🏢 Agency Slugs or Agency URLs", "type": "array", "description": "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.\n\nOne entry per agency — the slug (`walterhauschamberi`) or the full agency URL (`https://www.idealista.com/pro/walterhauschamberi/`).\n\nEvery 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.", "items": { "type": "string" } }, "locationId": { "title": "📍 Location ID (Single Location)", "type": "string", "description": "📍 Single Idealista location ID, e.g. `0-EU-ES-28-07-001-079` (Madrid). For several locations use 'Multiple Locations' below.\n\n**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`).\n\n**Find it:** search your location on idealista.com, open DevTools (F12) → Network, run a search, then copy the `locationId=` parameter.", "default": "0-EU-ES-28-07-001-079" }, "locationName": { "title": "📍 Location Name (Single Location)", "type": "string", "description": "📍 Single location name (e.g., Madrid, Barcelona, Rome)\n\nRequired when using Location ID field above.\n\n💡 **FREE tier:** Single location only\n💎 **PAID tier:** Use CSV upload below for bulk locations", "default": "Madrid" }, "locationsCsv": { "title": "📁 Upload CSV File - Excel/Google Sheets Friendly (PAID Tier)", "type": "array", "description": "📁 CSV upload (PAID tier only) — scan many locations in one run.\n\n**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.\n\n```\nlocationId,locationName\n0-EU-ES-28-07-001-079,Madrid\n0-EU-IT-RM-01-001-097,Rome\n```\n\nMutually exclusive with the JSON field above.", "items": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "title": "URL of a web page", "format": "uri" } } } }, "postalCodes": { "title": "📮 Postal Codes", "type": "array", "description": "Search by postal code instead of a location. Each code is searched separately. Spanish codes are 5 digits, e.g. 28013. Leave empty to search by location.", "items": { "type": "string" } }, "numPages": { "title": "🔢 Number of Pages to Scrape", "minimum": 1, "maximum": 250, "type": "integer", "description": "📄 How many pages to scrape\n\n• Each page returns up to 50 properties\n• Every property delivered is charged once — no hidden minimum per page\n• Duplicates are removed automatically (pagination overlap)\n• Example: 5 pages = up to 250 unique properties\n\n💡 **Tip:** Start with 1-2 pages to test your filters, then scale up.", "default": 1 }, "order": { "title": "🔎 Sort Results By", "enum": [ "relevance", "lowestprice", "highestprice", "mostrecent", "leastrecent", "biggest", "smallest" ], "type": "string", "description": "📊 How to order the search results", "default": "mostrecent" }, "language": { "title": "🗣️ Result Language", "enum": [ "en", "es", "it", "pt", "de", "fr", "ca", "nl", "nb" ], "type": "string", "description": "🌐 Language for property descriptions", "default": "en" }, "enrichWithDetails": { "title": "🖼️ Full photo galleries and extra detail (charged)", "type": "boolean", "description": "OFF by default. Every result already includes a cover image. Turn this on to also get the complete photo gallery, videos, virtual tours, floor plans, the energy certificate and monthly community costs for each property. Charged per enriched property.", "default": false }, "minPrice": { "title": "💲 Minimum Price (EUR)", "minimum": 0, "type": "integer", "description": "Minimum property price in EUR" }, "maxPrice": { "title": "💲 Maximum Price (EUR)", "minimum": 0, "type": "integer", "description": "Maximum property price in EUR" }, "minSize": { "title": "📦 Minimum Size (m²)", "minimum": 0, "type": "integer", "description": "Minimum property size in square meters" }, "maxSize": { "title": "📦 Maximum Size (m²)", "minimum": 0, "type": "integer", "description": "Maximum property size in square meters" }, "bedrooms0": { "title": "🛏️ Studio (0 bedrooms)", "type": "boolean", "description": "Include studio apartments" }, "bedrooms1": { "title": "🛏️ 1 Bedroom", "type": "boolean", "description": "Include properties with 1 bedroom" }, "bedrooms2": { "title": "🛏️ 2 Bedrooms", "type": "boolean", "description": "Include properties with 2 bedrooms" }, "bedrooms3": { "title": "🛏️ 3 Bedrooms", "type": "boolean", "description": "Include properties with 3 bedrooms" }, "bedrooms4": { "title": "🛏️ 4+ Bedrooms", "type": "boolean", "description": "Include properties with 4 or more bedrooms" }, "flat": { "title": "🗂️ All Apartment Types", "type": "boolean", "description": "Include flats, penthouses, and duplexes (all apartment types)" }, "onlyFlats": { "title": "🏢 Only Flats", "type": "boolean", "description": "Only standard flats/apartments" }, "penthouse": { "title": "🏢 Penthouses", "type": "boolean", "description": "Include penthouse apartments" }, "duplex": { "title": "🏢 Duplex", "type": "boolean", "description": "Include duplex apartments" }, "chalet": { "title": "🗂️ All House Types", "type": "boolean", "description": "Include all house types (independent, semi-detached, terraced, country)" }, "countryHouse": { "title": "🏠 Country Houses", "type": "boolean", "description": "Include country houses" }, "atticStudioType": { "title": "🏢 Attic Studios", "type": "boolean", "description": "Include attic studio apartments" }, "newDevelopment": { "title": "🆕 New Development", "type": "boolean", "description": "Only new development properties" }, "good": { "title": "✅ Good Condition", "type": "boolean", "description": "Properties in good condition" }, "renew": { "title": "🛠️ To Renew", "type": "boolean", "description": "Properties that need renovation" }, "furnished": { "title": "🛋️ Furnished", "enum": [ "", "furnishedKitchen" ], "type": "string", "description": "Furnishing status (only for rent operation)", "default": "" }, "airConditioning": { "title": "❄️ Air Conditioning", "type": "boolean", "description": "Has air conditioning" }, "builtinWardrobes": { "title": "🚪 Built-in Wardrobes", "type": "boolean", "description": "Has built-in wardrobes" }, "elevator": { "title": "🛗 Elevator", "type": "boolean", "description": "Building has elevator" }, "exterior": { "title": "🪟 Exterior", "type": "boolean", "description": "Exterior-facing property" }, "garage": { "title": "🚗 Garage", "type": "boolean", "description": "Has garage/parking" }, "garden": { "title": "🌳 Garden", "type": "boolean", "description": "Has garden" }, "swimmingPool": { "title": "🏊 Swimming Pool", "type": "boolean", "description": "Has swimming pool" }, "terrance": { "title": "🪴 Terrace", "type": "boolean", "description": "Has terrace" }, "storeRoom": { "title": "🏪 Store Room", "type": "boolean", "description": "Has storage room" }, "accessible": { "title": "♿ Accessible", "type": "boolean", "description": "Wheelchair accessible" }, "luxury": { "title": "💎 Luxury", "type": "boolean", "description": "Luxury property" }, "petsAllowed": { "title": "🐕 Pets Allowed", "type": "boolean", "description": "Pets allowed (rent only)" }, "hasPlan": { "title": "🏢 Has Floor Plan", "type": "boolean", "description": "Property has floor plan available" }, "virtualTour": { "title": "🕶️ Virtual Tour", "type": "boolean", "description": "Has virtual tour available" }, "bankOffer": { "title": "🏦 Bank Offer", "type": "boolean", "description": "Bank-owned property" }, "topFloor": { "title": "🏢 Top Floor", "type": "boolean", "description": "Top floor only" }, "intermediateFloor": { "title": "🏢 Intermediate Floor", "type": "boolean", "description": "Intermediate floor only" }, "longTermResidential": { "title": "🏷️ Long-Term Residential", "type": "boolean", "description": "Long-term residential rental" }, "shortTerm": { "title": "📆 Short-Term/Seasonal", "type": "boolean", "description": "Short-term or seasonal rental (rent only)" }, "micrositeShortName": { "title": "🏢 Real Estate Agency", "type": "string", "description": "📍 Filter by specific real estate agency\n\nGet ads from a specific agency. Extract from agency URL:\nhttps://www.idealista.com/pro/cajal-gestion-inmobiliaria/\n→ use: cajal-gestion-inmobiliaria" }, "center": { "title": "🧭 GPS Coordinates", "type": "string", "description": "Latitude,longitude for radius search (e.g., '40.416,-3.703')" }, "distance": { "title": "🔎 Search Radius (meters)", "minimum": 100, "maximum": 100000, "type": "integer", "description": "Radius around GPS coordinates (100-100,000 meters). Only used when GPS coordinates are provided." } } }, "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 }, "PROXY_UNBLOCKER_UNITS": { "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 }, "PROXY_UNBLOCKER_UNITS": { "type": "integer", "example": 0 } } } } } } } } } }