{ "openapi": "3.0.1", "info": { "title": "Idealista Scraper - Spain, Italy, Portugal Listings", "description": "Scrape Idealista property listings in Spain, Italy and Portugal: price, size, rooms, GPS, photos, agency name and phone, price drops. Sale, rent and rooms. Export to JSON, CSV or Excel.", "version": "0.1", "x-build-id": "slClKyZ36eOfLipaf" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/nice_dev~idealista-listings-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-nice_dev-idealista-listings-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/nice_dev~idealista-listings-scraper/runs": { "post": { "operationId": "runs-sync-nice_dev-idealista-listings-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/nice_dev~idealista-listings-scraper/run-sync": { "post": { "operationId": "run-sync-nice_dev-idealista-listings-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": "Idealista site to search: Spain (idealista.com), Italy (idealista.it) or Portugal (idealista.pt). Pasted URLs keep their own country.", "default": "es" }, "operation": { "title": "Operation", "enum": [ "sale", "rent" ], "type": "string", "description": "For sale or for rent.", "default": "sale" }, "propertyType": { "title": "Property type", "enum": [ "homes", "newDevelopments", "bedrooms", "vacationRentals", "offices", "premises", "transfers", "garages", "storageRooms", "lands", "buildings" ], "type": "string", "description": "**Rooms to share** and **Holiday rentals** exist for rent only, **Businesses for transfer** for sale only.", "default": "homes" }, "location": { "title": "Location", "maxLength": 200, "type": "string", "description": "City, district, province or neighbourhood as typed on idealista (e.g. `Madrid`, `Milano`, `Lisboa`), or an idealista location ID (`0-EU-ES-28-07-001-079`). The best match of the site's location search is used and written in the log." }, "locations": { "title": "More locations", "maxItems": 100, "uniqueItems": true, "type": "array", "description": "Several locations in one run (same country): one search per location, times each keyword below (locations × keywords: max 500). Added to **Location**; listings found by several searches are saved once.", "default": [], "items": { "type": "string" } }, "query": { "title": "Keyword", "maxLength": 200, "type": "string", "description": "Free text searched by idealista in the listings (e.g. `ático terraza`). With a location: keyword inside that location. Without one: keyword inside each search URL, agency, point or area, or the whole country if there is none." }, "searchQueries": { "title": "More keywords", "maxItems": 100, "uniqueItems": true, "type": "array", "description": "Several keywords in one run: one search per keyword (times each location). Added to **Keyword**.", "default": [], "items": { "type": "string" } }, "startUrls": { "title": "Start URLs", "maxItems": 1000, "type": "array", "description": "idealista search-result URLs (idealista.com, .it, .pt — the country, operation, property type and location, or the map area, of the URL are kept; set the filters with the fields below) or single listing URLs (`https://www.idealista.com/inmueble/12345678/`). Added to the searches above. Max 1 000 URLs.", "default": [], "items": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "title": "URL of a web page", "format": "uri" } } } }, "listingIds": { "title": "Listing IDs", "maxItems": 1000, "uniqueItems": true, "type": "array", "description": "idealista listing codes (the number `12345678` of a listing URL such as https://www.idealista.com/inmueble/12345678/) of the chosen **Country**, fetched directly.", "default": [], "items": { "type": "string" } }, "agencies": { "title": "Agencies", "maxItems": 100, "uniqueItems": true, "type": "array", "description": "Every listing of these agencies: the agency name as it appears in its idealista page URL (`engel-volkers` in `https://www.idealista.com/pro/engel-volkers/`) or the whole URL. The operation, type and filters below still apply.", "default": [], "items": { "type": "string" } }, "latitude": { "title": "Latitude (map search)", "maxLength": 20, "type": "string", "description": "Search around a point instead of a location: latitude in decimal degrees (e.g. `40.4168`), with **Longitude** and **Radius**." }, "longitude": { "title": "Longitude (map search)", "maxLength": 20, "type": "string", "description": "Longitude in decimal degrees (e.g. `-3.7038`)." }, "radiusKm": { "title": "Radius (km)", "minimum": 0.1, "maximum": 50, "type": "number", "description": "Radius around the point, in kilometres (0.1 to 50).", "default": 1 }, "polygon": { "title": "Map area (polygon)", "maxLength": 5000, "type": "string", "description": "Search inside an area drawn on the idealista map: paste the whole map URL or its shape value (`((_puuFnrsU?o}@n}@??n}@o}@?))`), or at least 3 points such as `40.42,-3.71;40.42,-3.70;40.41,-3.70`." }, "maxItems": { "title": "Max listings", "minimum": 0, "maximum": 1000000, "type": "integer", "description": "Maximum number of listings to save for the whole run (after deduplication and filters). 0 = no limit.", "default": 100 }, "maxItemsPerQuery": { "title": "Max listings per search", "minimum": 0, "maximum": 1000000, "type": "integer", "description": "Cap for EACH search (location × keyword, agency, URL…), so that the first search cannot use up the whole **Max listings** budget. 0 = no per-search cap.", "default": 0 }, "splitLargeSearches": { "title": "Get more than 2 500 results per search", "type": "boolean", "description": "idealista shows at most 2 500 listings per search. When a search has more, split it by price ranges automatically to reach every listing.", "default": true }, "sortBy": { "title": "Sort by", "enum": [ "relevance", "newest", "lastUpdated", "priceLow", "priceHigh", "priceDrops", "pricePerM2Low", "pricePerM2High", "sizeLarge", "sizeSmall" ], "type": "string", "description": "Order of the results (it decides which listings come first when **Max listings** stops the run). A search of more than 2 500 listings is read by price ranges: a price sort keeps its order over the whole search, any other sort only inside each range.", "default": "relevance" }, "includeDetails": { "title": "Open each listing page", "type": "boolean", "description": "1 extra request per listing for: exact address fields, all photos, energy certificate, community costs, the advertiser's office address and website, description in every language, last update date. Off = the search fields only (already with phone, GPS, description, photos).", "default": false }, "enrichEmails": { "title": "Find the agency e-mail on its website", "type": "boolean", "description": "Visit the agency website and read its e-mail address. Needs **Add the agency profile** (fast: no listing page opened) or **Open each listing page** — the website is on both. One visit per agency website (not per listing). Charged separately, only when an e-mail is found.", "default": false }, "includeAgencyProfile": { "title": "Add the agency profile", "type": "boolean", "description": "For each listing of an agency: its idealista agency page — year it joined idealista, number of listings, description, cover photo, video, office address, GPS and phone, website. One extra request per agency (not per listing). Charged separately, only for listings that got it (private sellers have none).", "default": false }, "language": { "title": "Language of the texts", "enum": [ "", "en", "es", "it", "pt", "fr", "de", "ca", "nl", "ru", "pl", "sv", "fi", "no", "da", "ro", "el", "zh" ], "type": "string", "description": "Language of the descriptions and labels returned by idealista (automatic translation by the site when the advertiser did not write it).", "default": "" }, "minPrice": { "title": "Min price", "minimum": 0, "maximum": 1000000000, "type": "integer", "description": "In euros (monthly rent for rentals)." }, "maxPrice": { "title": "Max price", "minimum": 0, "maximum": 1000000000, "type": "integer", "description": "In euros (monthly rent for rentals)." }, "minSize": { "title": "Min size", "minimum": 0, "maximum": 1000000, "type": "integer", "description": "Built area, m²." }, "maxSize": { "title": "Max size", "minimum": 0, "maximum": 1000000, "type": "integer", "description": "Built area, m²." }, "bedrooms": { "title": "Bedrooms", "uniqueItems": true, "type": "array", "description": "Keep these bedroom counts (several = any of them). `4` = 4 or more.", "items": { "type": "string", "enum": [ "0", "1", "2", "3", "4" ], "enumTitles": [ "Studio (0)", "1", "2", "3", "4 or more" ] }, "default": [] }, "bathrooms": { "title": "Bathrooms", "uniqueItems": true, "type": "array", "description": "Keep these bathroom counts. `3` = 3 or more.", "items": { "type": "string", "enum": [ "1", "2", "3" ], "enumTitles": [ "1", "2", "3 or more" ] }, "default": [] }, "condition": { "title": "Condition", "uniqueItems": true, "type": "array", "description": "New build, good condition, or to renovate.", "items": { "type": "string", "enum": [ "newDevelopment", "good", "renew" ], "enumTitles": [ "New build", "Good condition", "To renovate" ] }, "default": [] }, "homeTypes": { "title": "Home types", "uniqueItems": true, "type": "array", "description": "For **Homes**: flats, penthouses, duplexes, studios, lofts, detached / semi-detached / terraced houses, villas, country houses.", "items": { "type": "string", "enum": [ "flat", "penthouse", "duplex", "studio", "loft", "detachedHouse", "semidetachedHouse", "terracedHouse", "villa", "countryHouse" ], "enumTitles": [ "Flat / apartment", "Penthouse", "Duplex", "Studio", "Loft", "Detached house", "Semi-detached house", "Terraced house", "Villa", "Country house" ] }, "default": [] }, "floors": { "title": "Floor", "uniqueItems": true, "type": "array", "description": "Ground floor, intermediate floors, top floor.", "items": { "type": "string", "enum": [ "groundFloor", "intermediateFloor", "topFloor" ], "enumTitles": [ "Ground floor", "Intermediate floors", "Top floor" ] }, "default": [] }, "energyRating": { "title": "Energy rating", "uniqueItems": true, "type": "array", "description": "High (A-B), medium (C-D) or low (E-G) energy efficiency.", "items": { "type": "string", "enum": [ "high", "medium", "low" ], "enumTitles": [ "High", "Medium", "Low" ] }, "default": [] }, "publishedSince": { "title": "Published since", "enum": [ "", "lastDay", "last2Days", "lastWeek", "lastMonth" ], "type": "string", "description": "idealista's own date filter (publication or last price drop). idealista offers 48 hours on sales and 24 hours on rentals: the other one searches the next wider period. For an exact date, see **Posted after**.", "default": "" }, "features": { "title": "Must have", "uniqueItems": true, "type": "array", "description": "Keep only the listings with ALL of these.", "items": { "type": "string", "enum": [ "elevator", "airConditioning", "parking", "garden", "swimmingPool", "terrace", "balcony", "storeRoom", "builtinWardrobes", "exterior", "accessible", "luxury", "seaViews", "virtualTour", "hasPlan", "exteriorDomesticSpace" ], "enumTitles": [ "Lift", "Air conditioning", "Garage / parking space", "Garden", "Swimming pool", "Terrace", "Balcony", "Storage room", "Built-in wardrobes", "Exterior", "Accessible home", "Luxury home", "Sea views", "Virtual tour", "Floor plan", "Outdoor space" ] }, "default": [] }, "bankOffer": { "title": "Bank-owned properties only", "type": "boolean", "description": "Only the properties sold by banks.", "default": false }, "auction": { "title": "Auctions", "enum": [ "", "excludeAuctions", "onlyAuctions" ], "type": "string", "description": "Keep, exclude or only show the auctions (sale).", "default": "" }, "occupationStatus": { "title": "Occupation status", "uniqueItems": true, "type": "array", "description": "Sale: free, rented (with tenant), bare ownership, illegally occupied.", "items": { "type": "string", "enum": [ "free", "tenanted", "bareOwnership", "illegallyOccupied" ], "enumTitles": [ "Free", "Rented (with tenant)", "Bare ownership", "Illegally occupied" ] }, "default": [] }, "furnished": { "title": "Furnished", "enum": [ "", "furnished", "furnishedKitchen" ], "type": "string", "description": "Rent: furnished home, or equipped kitchen only.", "default": "" }, "rentalTypes": { "title": "Rental type", "uniqueItems": true, "type": "array", "description": "Rent: long-term residential and / or seasonal.", "items": { "type": "string", "enum": [ "longTerm", "seasonal" ], "enumTitles": [ "Long term", "Seasonal" ] }, "default": [] }, "petsAllowed": { "title": "Pets allowed", "type": "boolean", "description": "Rent: only the homes that accept pets.", "default": false }, "roomGender": { "title": "Flatmates' gender", "enum": [ "", "female", "male" ], "type": "string", "description": "Room for a woman or a man.", "default": "" }, "roomOccupation": { "title": "Tenant profile", "enum": [ "", "students", "workers" ], "type": "string", "description": "Students or workers.", "default": "" }, "roomBedType": { "title": "Bed", "enum": [ "", "single", "double", "twoBeds", "none" ], "type": "string", "description": "Bed in the room.", "default": "" }, "roomFlatmates": { "title": "People living in the flat", "uniqueItems": true, "type": "array", "description": "Number of people already living in the flat.", "items": { "type": "string", "enum": [ "2", "3", "4" ], "enumTitles": [ "1", "2", "3 or more" ] }, "default": [] }, "roomRules": { "title": "Allowed / offered", "uniqueItems": true, "type": "array", "description": "Keep only the rooms with ALL of these.", "items": { "type": "string", "enum": [ "smokingAllowed", "petsAllowed", "couplesAllowed", "childrenAllowed", "lgbtFriendly", "privateBathroom", "ownerNotLiving", "houseKeeper", "streetViewWindow", "onlineBooking" ], "enumTitles": [ "Smoking allowed", "Pets allowed", "Couples allowed", "Children allowed", "LGBT friendly", "Private bathroom", "Owner does not live there", "Cleaning service", "Window on the street", "Online booking" ] }, "default": [] }, "roomAvailableFrom": { "title": "Available from", "type": "string", "description": "Move-in date (`2026-10-01`)." }, "roomAvailableTo": { "title": "Available until", "type": "string", "description": "Move-out date (`2027-06-30`)." }, "postedAfter": { "title": "Updated after", "type": "string", "description": "Only listings last updated on or after this date (`2026-09-01`, or `7 days`, `2 weeks`, `1 month`). idealista gives the update date (not the first publication date) on the listing page: needs **Open each listing page**: without it, this date is not applied (the log says so) — use **Published since** instead." }, "postedBefore": { "title": "Updated before", "type": "string", "description": "Only listings last updated on or before this date (the whole day is included), or older than a period such as `30 days`. Needs **Open each listing page**." }, "excludeKeywords": { "title": "Exclude keywords", "maxItems": 50, "uniqueItems": true, "type": "array", "description": "Drop the listings whose title or description contains one of these words (case and accents ignored).", "default": [], "items": { "type": "string" } }, "privateSellersOnly": { "title": "Private advertisers only", "type": "boolean", "description": "Drop the listings of agencies and developers. Rare on homes in Spain (about 3 in 1,000 listings): most searches there return few or none.", "default": false }, "requirePhone": { "title": "With phone only", "type": "boolean", "description": "Drop the listings without a phone number.", "default": false }, "onlyPriceDrops": { "title": "Price drops only", "type": "boolean", "description": "Only the listings whose price went down (idealista shows the former price).", "default": false }, "minPriceDropPercent": { "title": "Min price drop", "minimum": 0, "maximum": 100, "type": "integer", "description": "With **Price drops only**: only drops of at least this percentage." }, "onlyNew": { "title": "Only new listings", "type": "boolean", "description": "Skip the listings that a previous run (same **Memory key**) already delivered: they are not saved and not charged. First run = everything is new.", "default": false }, "stateKey": { "title": "Memory key", "pattern": "^[a-zA-Z0-9_-]{1,64}$", "maxLength": 64, "type": "string", "description": "Name of the memory used by **Only new listings**. Give each schedule / task its own key (e.g. `madrid-rentals`) so that they do not share their memory. Letters, digits, `-` and `_`.", "default": "default" }, "resetState": { "title": "Reset the memory", "type": "boolean", "description": "Forget everything remembered under this **Memory key** before the run: this run returns (and charges) every listing again. Untick it afterwards.", "default": false }, "proxyConfiguration": { "title": "Proxy configuration", "type": "object", "description": "Keep the default Apify Proxy: it is included in the price. The residential Apify proxy is not available in this Actor.", "default": { "useApifyProxy": true } }, "maxConcurrency": { "title": "Max concurrency", "minimum": 1, "maximum": 20, "type": "integer", "description": "Maximum number of requests processed in parallel.", "default": 4 }, "maxRequestRetries": { "title": "Max request retries", "minimum": 0, "maximum": 20, "type": "integer", "description": "Retries per request before it is marked as failed.", "default": 5 }, "debugLog": { "title": "Debug log", "type": "boolean", "description": "Include debug messages in the run log.", "default": false } } }, "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 } } } } } } } } } }