{ "openapi": "3.0.1", "info": { "title": "Idealista Scraper 💰 $0.60/1K – Spain, Portugal, Italy & France", "description": "From $0.60/1K. Scrape Idealista listings in Spain, Portugal, Italy & France: price, €/m², size, rooms, GPS, photos, agent phones, price drops. Sear\nch by city, postal code, radius, agency or any search URL. No 1,500-result cap, no duplicates. Daily monitoring of new listings.", "version": "0.0", "x-build-id": "F2QuhcKZJE4pHG7hQ" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/lukass~idealista-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-lukass-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/lukass~idealista-scraper/runs": { "post": { "operationId": "runs-sync-lukass-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/lukass~idealista-scraper/run-sync": { "post": { "operationId": "run-sync-lukass-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", "required": [ "proxy", "operation", "country" ], "properties": { "district": { "title": "Location", "type": "string", "description": "Where you want to look for the real estates: a city, district or postal code, e.g. Madrid or 28013. For further filtering you can use the URL below." }, "districts": { "title": "More districts", "type": "array", "description": "Further locations or postal codes searched in the same run, e.g. Barcelona, 28013. Each is searched separately; maxItems caps the whole run.", "items": { "type": "string" } }, "postalCodes": { "title": "Postal codes", "type": "array", "description": "Postal codes searched in the same run, e.g. 28013, 08001. Each is searched separately like a district; maxItems caps the whole run.", "items": { "type": "string" } }, "country": { "title": "Country", "enum": [ "es", "pt", "it", "fr" ], "type": "string", "description": "Country to search with the district field. For startUrl, the country comes from the URL domain (idealista.com / .pt / .it / .fr).", "default": "es" }, "operation": { "title": "Operation", "enum": [ "sale", "rent" ], "type": "string", "description": "Select Listing sale or rent properties", "default": "sale" }, "propertyType": { "title": "Property type", "enum": [ "homes", "newDevelopments", "bedrooms", "vacationRentals", "offices", "premises", "transfers", "garages", "lands", "storageRooms", "buildings" ], "type": "string", "description": "Select type of property", "default": "homes" }, "maxItems": { "title": "Limit the number of items", "type": "integer", "description": "Maximum number of results. Leave empty to get every result (up to the page limit below)." }, "endPage": { "title": "Limit of scraped pages", "type": "integer", "description": "Last search page to scrape per search (50 results per page, at most 50 pages). Leave empty to use all 50. maxItems is the better way to cap a run." }, "fetchDetails": { "title": "Fetch full property details", "type": "boolean", "description": "For each item found in a search, fetch the full property detail page instead of using the (thinner) search-result data. Adds description text, energy certification, and more accurate floor/lift/location fields, but is slower and uses one extra request per property.", "default": false }, "splitByPrice": { "title": "Get all results from big searches", "type": "boolean", "description": "One Idealista search returns at most 2,500 listings. When a search has more, it is split into price bands automatically so you get the full result set (no duplicates). Turn off to stop at the first 2,500.", "default": true }, "monitoringMode": { "title": "Only new listings (monitoring)", "type": "boolean", "description": "Return only listings that previous runs with the same search did not return - ideal for scheduled daily runs. The first run returns everything. Changing a filter starts a new list.", "default": false }, "startUrl": { "title": "URL you want to scrape", "type": "array", "description": "URL(s) of places or pages what will be scraped. For example https://www.idealista.com/venta-viviendas/madrid/centro/con-de-tres-dormitorios,de-cuatro-cinco-habitaciones-o-mas,tres-banos-o-mas/", "items": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "title": "URL of a web page", "format": "uri" } } } }, "proxy": { "title": "Proxy configuration", "type": "object", "description": "Select proxies to be used by your crawler.", "default": { "useApifyProxy": true, "apifyProxyGroups": [ "RESIDENTIAL" ] } }, "minSize": { "title": "Min size", "enum": [ "any", "40", "50", "60", "70", "80", "90", "100", "110", "120", "130", "140", "150", "160", "170", "180", "190", "200", "220", "240", "260", "280", "300", "320", "340", "360", "380", "400", "420", "440", "460", "480", "500", "550", "600", "650", "700", "800", "900", "nolimit" ], "type": "string", "description": "Select min size of property", "default": "any" }, "maxSize": { "title": "Max size", "enum": [ "any", "40", "50", "60", "70", "80", "90", "100", "110", "120", "130", "140", "150", "160", "170", "180", "190", "200", "220", "240", "260", "280", "300", "320", "340", "360", "380", "400", "420", "440", "460", "480", "500", "550", "600", "650", "700", "800", "900", "nolimit" ], "type": "string", "description": "Select max size of property", "default": "any" }, "bedrooms": { "title": "Bedrooms", "type": "array", "description": "[\"studio\",\"1\",\"2\",\"3\",\"4\"] (leave empty for any)" }, "bathrooms": { "title": "Bathrooms", "type": "array", "description": "[\"1\",\"2\",\"3\"] (leave empty for any)" }, "homeType": { "title": "Type of home", "type": "array", "description": "[\"flat\",\"penthouse\",\"duplex\",\"studio\",\"chalet\",\"countryHouse\",\"apartment\",\"villa\",\"loft\",\"atticStudio\",\"casaBaja\"] (leave empty for any; several widen the search). \"detachedHouse\", \"semiDetachedHouse\" and \"terracedHouse\" all search houses (chalet) - Idealista has no separate filter for them." }, "condition": { "title": "Condition", "type": "array", "description": "[\"newDevelopment\",\"good\",\"renew\"] (leave empty for any)" }, "propertyStatus": { "title": "Current status of the property", "type": "array", "description": "[\"bareOwnership\",\"tenanted\",\"illegallyOccupied\",\"free\"] (leave empty for any)" }, "floorHeights": { "title": "Floor", "type": "array", "description": "[\"topFloor\",\"intermediateFloor\",\"groundFloor\"] (leave empty for any)" }, "features": { "title": "Features", "type": "array", "description": "[ \"airConditioning\", \"builtinWardrobes\", \"elevator\", \"exteriorDomesticSpace\", \"balcony\", \"terrance\", \"exterior\", \"garage\", \"garden\", \"swimmingPool\", \"storeRoom\", \"accessible\", \"luxury\", \"seaViews\", \"bankOffer\", \"virtualTour\", \"hasPlan\", \"petsAllowed\"] (leave empty for any; bankOffer = bank-owned, hasPlan = has a floor plan, petsAllowed = rent only)" }, "minPrice": { "title": "Min price (€)", "type": "integer", "description": "Lowest price, e.g. 150000 for sale or 800 for rent per month." }, "maxPrice": { "title": "Max price (€)", "type": "integer", "description": "Highest price." }, "publishedWithin": { "title": "Published within", "enum": [ "any", "last24Hours", "last48Hours", "lastWeek", "lastMonth" ], "type": "string", "description": "Only listings published recently. Idealista offers 24 hours for rent and 48 hours for sale only - the other one is replaced by it.", "default": "any" }, "sortBy": { "title": "Sort by", "enum": [ "weigh", "price", "publicationDate", "modificationDate", "priceDown", "ratioeurm2", "size", "distance" ], "type": "string", "description": "Order of the results. Distance only works with a radius search.", "default": "weigh" }, "sortOrder": { "title": "Sort order", "enum": [ "desc", "asc" ], "type": "string", "description": "Direction of the sort above.", "default": "desc" }, "language": { "title": "Results language", "enum": [ "en", "es", "ca", "pt", "it", "fr", "de", "nl" ], "type": "string", "description": "Language of titles and labels. Descriptions are always in the advertiser's original language.", "default": "en" }, "energyRating": { "title": "Energy rating", "enum": [ "any", "high", "medium", "low" ], "type": "string", "description": "Energy certificate band.", "default": "any" }, "furnished": { "title": "Furnished (rent only)", "enum": [ "any", "furnished", "furnishedKitchen" ], "type": "string", "description": "Only furnished rentals, or only rentals with a fitted kitchen. Ignored for sale searches.", "default": "any" }, "auction": { "title": "Auctions", "enum": [ "any", "only", "exclude" ], "type": "string", "description": "Include auction listings, show only auctions, or leave them out.", "default": "any" }, "onlyPriceDrops": { "title": "Only price drops", "type": "boolean", "description": "Return (and pay for) only listings whose price was reduced. With the default sort, results come sorted by the biggest drop first.", "default": false }, "minPriceDropPercent": { "title": "Min price drop (%)", "minimum": 0, "maximum": 100, "type": "integer", "description": "Return only listings whose price dropped by at least this percentage, e.g. 10. Implies Only price drops." }, "agency": { "title": "Agency", "type": "string", "description": "Only this agency's listings: its short name or page URL, e.g. https://www.idealista.com/pro/walterhauschamberi/. Replaces district when set." }, "propertyIds": { "title": "Property IDs", "type": "array", "description": "Listing IDs to fetch directly (the number in the listing URL), on the site of the Country above. Like property URLs in startUrl, billed as detail results.", "items": { "type": "string" } }, "latitude": { "title": "Latitude", "type": "number", "description": "Centre of a radius search, e.g. 40.4168. Use with longitude; replaces district when set." }, "longitude": { "title": "Longitude", "type": "number", "description": "Centre of a radius search, e.g. -3.7038." }, "radiusKm": { "title": "Radius (km)", "minimum": 1, "maximum": 100, "type": "integer", "description": "Search radius around the centre point.", "default": 5 }, "compact": { "title": "Compact output", "type": "boolean", "description": "One flat row per listing with the most used fields (price, size, rooms, location, agency, phone, main photo, ...) instead of the full nested record. Best for CSV and Excel.", "default": false }, "excludeEmptyFields": { "title": "Exclude empty fields", "type": "boolean", "description": "Leave out fields that are empty (null, empty text, empty lists), so each result carries only the data Idealista has for it.", "default": false }, "descriptionMaxLength": { "title": "Max description length", "minimum": 0, "type": "integer", "description": "Cut descriptions to this many characters (an ellipsis marks the cut). Leave empty or 0 for the full text." } } }, "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 } } } } } } } } } }