{ "openapi": "3.0.1", "info": { "title": "Idealista Scraper API — Spain, Italy & Leads", "description": "Idealista scraper and unofficial Idealista API for Spain, Italy and Portugal — homes, offices, garages, land, sale or rent. 60+ fields per listing: price, €/m², size, rooms, amenities, energy rating, GPS + province/city/district, photos, plans, videos, 3D tours, agency contacts. From $0.70/1k.", "version": "1.1", "x-build-id": "6kyssIb2lNSIXQG43" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/pro100chok~idealista-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-pro100chok-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/pro100chok~idealista-scraper/runs": { "post": { "operationId": "runs-sync-pro100chok-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/pro100chok~idealista-scraper/run-sync": { "post": { "operationId": "run-sync-pro100chok-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": "Idealista URLs", "type": "array", "description": "Paste any Idealista URLs — search result pages, single property pages (/inmueble/, /immobile/, /imovel/), or agency pages (/pro/...). The type of each URL is detected automatically. This is the most reliable way to control exactly what is scraped: set your filters on idealista.com and paste the resulting URL. Works for idealista.com (Spain), idealista.it (Italy) and idealista.pt (Portugal).", "items": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "title": "URL of a web page", "format": "uri" } } } }, "location": { "title": "Location", "type": "string", "description": "Build a search without a URL: the location slug exactly as it appears in an Idealista URL, e.g. 'madrid-madrid', 'barcelona-barcelona', or a neighbourhood path like 'madrid/chamartin'. Combined with the fields below. Leave empty if you use 'Idealista URLs' above." }, "maxItems": { "title": "Max results", "minimum": 0, "type": "integer", "description": "Maximum number of records to output (0 = no limit).", "default": 10 }, "country": { "title": "Country", "enum": [ "es", "it", "pt" ], "type": "string", "description": "Idealista country/site to use when building a search from filters.", "default": "es" }, "operation": { "title": "Operation", "enum": [ "sale", "rent" ], "type": "string", "description": "Buy or rent.", "default": "sale" }, "propertyType": { "title": "Property type", "enum": [ "homes", "newDevelopments", "offices", "premises", "garages", "lands", "storageRooms", "buildings", "rooms" ], "type": "string", "description": "Type of property to search for.", "default": "homes" }, "sortBy": { "title": "Sort by", "enum": [ "relevance", "mostRecent", "leastRecent", "lowestPrice", "highestPrice", "biggest", "smallest", "highestPriceReduction" ], "type": "string", "description": "Ordering of the search results.", "default": "relevance" }, "minPrice": { "title": "Min price (€)", "minimum": 0, "type": "integer", "description": "Minimum price in euros." }, "maxPrice": { "title": "Max price (€)", "minimum": 0, "type": "integer", "description": "Maximum price in euros." }, "minSize": { "title": "Min size (m²)", "minimum": 0, "type": "integer", "description": "Minimum built size in m²." }, "maxSize": { "title": "Max size (m²)", "minimum": 0, "type": "integer", "description": "Maximum built size in m²." }, "bedrooms": { "title": "Bedrooms", "type": "array", "description": "Number of bedrooms (multiple allowed).", "items": { "type": "string", "enum": [ "studio", "1", "2", "3", "4" ], "enumTitles": [ "Studio", "1", "2", "3", "4+" ] } }, "homeType": { "title": "Home type", "type": "array", "description": "Filter by home sub-type (multiple allowed).", "items": { "type": "string", "enum": [ "flat", "penthouse", "duplex", "detachedHouse", "countryHouse", "studio" ], "enumTitles": [ "Flat", "Penthouse", "Duplex", "Detached house / chalet", "Country house", "Studio" ] } }, "condition": { "title": "Condition", "type": "array", "description": "Filter by property condition (multiple allowed).", "items": { "type": "string", "enum": [ "newDevelopment", "good", "renew" ], "enumTitles": [ "New development", "Good condition / second hand", "To renovate" ] } }, "floor": { "title": "Floor", "type": "array", "description": "Filter by floor level (multiple allowed).", "items": { "type": "string", "enum": [ "topFloor", "intermediateFloor", "groundFloor" ], "enumTitles": [ "Top floor", "Intermediate floor", "Ground floor" ] } }, "amenities": { "title": "Amenities", "type": "array", "description": "Filter by amenities (multiple allowed).", "items": { "type": "string", "enum": [ "airConditioning", "lift", "terrace", "garage", "garden", "swimmingPool", "storageRoom", "fittedWardrobes", "exterior", "luxury", "accessible", "seaViews" ], "enumTitles": [ "Air conditioning", "Lift", "Terrace", "Garage", "Garden", "Swimming pool", "Storage room", "Fitted wardrobes", "Exterior", "Luxury", "Accessible", "Sea views" ] } }, "publicationDate": { "title": "Published within", "enum": [ "", "24h", "48h", "week", "month" ], "type": "string", "description": "Only include listings published within this period.", "default": "" }, "propertyCodes": { "title": "Property codes", "type": "array", "description": "Scrape specific properties by their Idealista code (the number in /inmueble//). Uses the Country selected above.", "items": { "type": "string" } }, "agencySlugs": { "title": "Agency slugs", "type": "array", "description": "Scrape agency / professional profiles by slug (the part after /pro/ in the URL, e.g. 'gilmar-centro'). Uses the Country selected above.", "items": { "type": "string" } }, "fetchDetails": { "title": "Scrape full detail for each result", "type": "boolean", "description": "For every search result, also open its property page to get the full description, the grouped feature list, amenity flags, energy consumption and emissions, the complete photo gallery, floor plans, videos, 3D/360 tour links and the province/city/district/neighbourhood hierarchy. Coordinates and the multimedia counts already come back without this. Slower and costs more requests.", "default": true }, "fetchContacts": { "title": "Fetch advertiser / agency details", "type": "boolean", "description": "On detail pages, fetch the advertiser block (name, logo, microsite, agency id, reference). Reliable and recommended.", "default": true }, "fetchPhones": { "title": "Reveal phone numbers", "type": "boolean", "description": "Reveal the advertiser's phone number for each property (returned as contactInfo.phone). Adds a few extra requests per property. Not every listing publishes a phone.", "default": true }, "scrapeAgencies": { "title": "Output agencies instead of properties", "type": "boolean", "description": "For search URLs, return one row per unique agency/advertiser found (with profile details) instead of the properties.", "default": false }, "monitoringMode": { "title": "Monitoring mode (only new listings)", "type": "boolean", "description": "Only output listings not seen in previous runs of this Actor (tracked by property code). Great for daily alerts.", "default": false }, "splitByPrice": { "title": "Bypass the ~1,800 result limit", "type": "boolean", "description": "Idealista limits a single search to ~1,800 results. Enable this to automatically split the search into price bands and collect far more results (deduplicated).", "default": true }, "endPage": { "title": "Max pages per search", "minimum": 0, "type": "integer", "description": "Stop each search after this many result pages (0 = until the last page). ~30 results per page.", "default": 0 }, "maxConcurrency": { "title": "Concurrency", "minimum": 1, "maximum": 20, "type": "integer", "description": "How many properties/pages to process in parallel. Each parallel worker uses its own proxy IP. Higher = faster but more proxy traffic.", "default": 5 }, "maxRetries": { "title": "Max retries per request", "minimum": 1, "maximum": 20, "type": "integer", "description": "How many times to rotate the proxy IP and retry when a request is blocked.", "default": 8 }, "proxyConfiguration": { "title": "Proxy configuration", "type": "object", "description": "Proxy used for scraping. Residential proxies are strongly recommended and the egress country is matched to the site automatically (Spain for .com, Italy for .it, Portugal for .pt).", "default": { "useApifyProxy": true, "apifyProxyGroups": [ "RESIDENTIAL" ] } } } }, "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 } } } } } } } } } }