{ "openapi": "3.0.1", "info": { "title": "Idealista Scraper | Spain, Italy & Portugal Property Data", "description": "[$0.90 / 1K listings - no start fee] Scrape any Idealista search across Spain, Italy and Portugal: homes, rooms, garages, offices, premises, land, buildings, storage, for sale or rent. Price, m2, EUR/m2 vs market median, agency and price cuts per row, plus optional listing-page detail.", "version": "0.1", "x-build-id": "rDikIAkzNJTXLBUUf" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/webdata_labs~idealista-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-webdata_labs-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/webdata_labs~idealista-scraper/runs": { "post": { "operationId": "runs-sync-webdata_labs-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/webdata_labs~idealista-scraper/run-sync": { "post": { "operationId": "run-sync-webdata_labs-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 search URLs", "type": "array", "description": "Paste any Idealista search page URL, with whatever filters you already set on the site. This is the most reliable way to get exactly the search you see in your browser. When given, these replace the country, location and property type fields below.", "items": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "title": "URL of a web page", "format": "uri" } } } }, "country": { "title": "Country", "enum": [ "es", "it", "pt" ], "type": "string", "description": "Which Idealista site to search: Spain (idealista.com), Italy (idealista.it) or Portugal (idealista.pt). Property type coverage differs per site, see the README.", "default": "es" }, "locations": { "title": "Locations", "type": "array", "description": "One or more location slugs exactly as they appear in an Idealista URL, for example 'madrid-madrid', 'barcelona-barcelona' or 'valencia-valencia'. Open the search you want on Idealista and copy the part after the operation, e.g. idealista.com/venta-viviendas/madrid-madrid/. Each location is scraped as its own search.", "default": [ "madrid-madrid" ], "items": { "type": "string" } }, "operation": { "title": "Sale or rent", "enum": [ "sale", "rent" ], "type": "string", "description": "Whether to search properties for sale or to rent. Some property types exist for only one of the two: rooms are rent only, land and buildings are sale only.", "default": "sale" }, "propertyType": { "title": "Property type", "enum": [ "homes", "rooms", "garages", "offices", "premises", "land", "buildings", "storage" ], "type": "string", "description": "What kind of property to search. Spain covers all eight types. Italy covers homes, rooms, garages, offices, commercial premises, land and buildings. Portugal currently covers homes only.", "default": "homes" }, "includeDetails": { "title": "Also open each listing page", "type": "boolean", "description": "Adds the fields that only exist on the listing page itself: energy rating, year built, bathrooms, heating, orientation, the full advertiser description, photo and floor plan URLs. This opens one extra page per listing, so a run takes longer and each enriched listing is charged separately. Off by default.", "default": false }, "maxItems": { "title": "Maximum listings", "minimum": 0, "type": "integer", "description": "Stop after this many matching listings across all searches. Set 0 for no limit. The default keeps a first run small and cheap.", "default": 100 }, "sortBy": { "title": "Sort results by", "enum": [ "relevance", "newest", "cheapest", "cheapestPerSqm", "largest", "priceDrop" ], "type": "string", "description": "Idealista's own result ordering. Spain and Italy only: the Portuguese site exposes no sorting, so PT runs come back in Idealista's default order.", "default": "relevance" }, "maxPrice": { "title": "Maximum price", "minimum": 0, "type": "integer", "description": "Highest price to include, applied by Idealista itself as a search filter. There is no matching minimum-price filter on the Spanish or Italian sites, so use a search URL if you need a lower bound." }, "minArea": { "title": "Minimum area", "minimum": 0, "type": "integer", "description": "Smallest floor area to include, applied by Idealista itself as a search filter." }, "maxArea": { "title": "Maximum area", "minimum": 0, "type": "integer", "description": "Largest floor area to include, applied by Idealista itself as a search filter." }, "minRooms": { "title": "Minimum bedrooms", "minimum": 0, "type": "integer", "description": "Keep only listings with at least this many bedrooms. Applied to the scraped rows, not to the Idealista search." }, "onlyPrivateOwners": { "title": "Only private owners", "type": "boolean", "description": "Keep only listings posted by private owners, dropping everything marketed by an agency.", "default": false }, "onlyPriceDrops": { "title": "Only listings whose price was cut", "type": "boolean", "description": "Keep only listings Idealista marks as reduced. Every row carries the price-drop fields either way; this just filters to them.", "default": false }, "minPriceDropPercent": { "title": "Minimum price drop (%)", "minimum": 0, "maximum": 90, "type": "integer", "description": "Keep only listings reduced by at least this percentage. Leave empty for any reduction." }, "includeDescription": { "title": "Include the listing description", "type": "boolean", "description": "Include the short description text from each search card. Turn off for a narrower export.", "default": true } } }, "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 } } } } } } } } } }