{ "openapi": "3.0.1", "info": { "title": "Idealista Scraper: Spain, Italy, Portugal Homes", "description": "Scrape Idealista ads for sale and rent in Spain, Italy and Portugal by search link, place, map area, ad id or agency, past the 1,800 result cap, no login. Rows: price, price drop, m², rooms, floor, lift, photos, agency, energy rating, coordinates, phones. JSON, CSV, Excel or API; pay per listing.", "version": "0.1", "x-build-id": "3GINT6ZKLpi2Zk6pB" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/automation_craft~idealista-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-automation_craft-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/automation_craft~idealista-scraper/runs": { "post": { "operationId": "runs-sync-automation_craft-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/automation_craft~idealista-scraper/run-sync": { "post": { "operationId": "run-sync-automation_craft-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 links", "type": "array", "description": "Links from idealista.com (Spain), idealista.it (Italy) or idealista.pt (Portugal): a search results page (with its own filters, order and page), an ad page (/inmueble//, /immobile//, /imovel//), an agency page (/pro//), a drawn area (/areas/...?shape=) or a multi area link (/multi/...). Up to 1,000 links.", "items": { "type": "string" } }, "locations": { "title": "Places", "type": "array", "description": "Place names as Idealista writes them (\"Chamberí, Madrid\", \"Milano\", \"Lisboa\"), postal codes (\"28004\", \"20121\") or the place part of an Idealista link (\"madrid-madrid\", \"madrid/chamberi\"). A name that matches several places, or none, gets a free row listing the site's own candidates. Uses the market, operation, property type, filters and order below.", "items": { "type": "string" } }, "wholeCountry": { "title": "Whole country", "type": "boolean", "description": "Off by default. On, the run searches every province of the chosen country (Spain 52, Italy 107, Portugal 29 districts and islands) with the property type, operation and filters below, each province past the 1,800 ad limit by price bands. Set \"maxItems\" to what you want to pay for." }, "mapAreas": { "title": "Map areas", "type": "array", "description": "A drawn area as \"lat,lng; lat,lng; lat,lng\" (3 to 50 points) or a circle as \"lat,lng,radiusKm\" (0.1 to 50 km). Uses the market, operation, property type, filters and order below.", "items": { "type": "string" } }, "adIds": { "title": "Ad ids or ad links", "type": "array", "description": "Idealista ad ids (in the market below) or ad links of any market. Each ad is read from its own page and delivered with its full details (billed as Listing details). Gone ads get a free row. Up to 10,000.", "items": { "type": "string" } }, "agencies": { "title": "Agencies", "type": "array", "description": "Agency names as they appear in their Idealista link (/pro//) or the links themselves. Each gives one Agency row and the agency's own ads (homes for sale) as Listing rows.", "items": { "type": "string" } }, "datasetId": { "title": "Ads of an earlier dataset", "type": "string", "description": "The id of a dataset of an earlier run of this Actor (or any dataset whose rows carry an Idealista ad link in \"url\"): its ads are read again with their full details. Up to 10,000 rows." }, "market": { "title": "Market", "enum": [ "es", "it", "pt" ], "type": "string", "description": "The Idealista site of the places, map areas, bare ad ids and agency names. Links carry their own market. Default: Spain." }, "operation": { "title": "Sale or rent", "enum": [ "sale", "rent" ], "type": "string", "description": "Default: for sale." }, "propertyType": { "title": "Property type", "enum": [ "homes", "newDevelopments", "rooms", "offices", "premises", "garages", "land", "storageRooms", "buildings", "businessTransfers", "holidayRentals" ], "type": "string", "description": "Default: homes. Not every type exists in every market and operation; a combination Idealista does not offer refuses the run, free but for the start fee." }, "sortBy": { "title": "Order", "enum": [ "relevance", "priceAsc", "priceDesc", "newest", "oldest", "biggestPriceDrop", "pricePerM2Asc", "pricePerM2Desc", "sizeDesc", "sizeAsc", "highestFloor", "lowestFloor", "privateFirst", "agenciesFirst", "mostBedrooms" ], "type": "string", "description": "Idealista's own orders. Spain does not serve its date order to automated reads: for the newest Spanish ads use \"Published within\". A search split into price bands to go past the site's 1,800 ad cap is read cheapest first." }, "minPrice": { "title": "Minimum price (EUR)", "minimum": 0, "type": "integer", "description": "For rent: per month." }, "maxPrice": { "title": "Maximum price (EUR)", "minimum": 0, "type": "integer", "description": "For rent: per month." }, "minSize": { "title": "Minimum size (m²)", "minimum": 0, "type": "integer", "description": "Built size in square metres." }, "maxSize": { "title": "Maximum size (m²)", "minimum": 0, "type": "integer", "description": "Built size in square metres." }, "rooms": { "title": "Bedrooms (Spain, Portugal) or rooms (Italy)", "type": "array", "description": "Any of the listed counts. Spain and Portugal count bedrooms; Italy counts rooms (locali).", "items": { "type": "string", "enum": [ "0", "1", "2", "3", "4", "4+", "5+" ], "enumTitles": [ "0 (studio)", "1", "2", "3", "4 (Italy)", "4 or more (Spain, Portugal)", "5 or more (Italy)" ] } }, "bathrooms": { "title": "Bathrooms", "type": "array", "description": "Any of the listed counts.", "items": { "type": "string", "enum": [ "1", "2", "3+" ], "enumTitles": [ "1", "2", "3 or more" ] } }, "homeTypes": { "title": "Home types", "type": "array", "description": "For homes searches.", "items": { "type": "string", "enum": [ "flatsPenthousesDuplexes", "flats", "penthouses", "duplexes", "houses", "detachedHouses", "semiDetachedHouses", "terracedHouses", "countryHouses", "apartments", "villas", "villasItaly", "lofts", "singleStoreyHouses", "atticStudios", "farmhouses" ], "enumTitles": [ "Flats, penthouses and duplexes", "Flats only", "Penthouses", "Duplexes", "Houses and chalets", "Detached houses", "Semi-detached houses", "Terraced houses", "Country houses", "Apartments (Spain)", "Villas (Spain)", "Villas (Italy)", "Lofts", "Single storey houses (Spain)", "Attic studios (Italy)", "Farmhouses (Italy)" ] } }, "condition": { "title": "Condition", "type": "array", "description": "Any of the listed states.", "items": { "type": "string", "enum": [ "newBuild", "good", "toRenovate" ], "enumTitles": [ "New build", "Good condition", "To renovate" ] } }, "floor": { "title": "Floor", "type": "array", "description": "Any of the listed floors.", "items": { "type": "string", "enum": [ "top", "intermediate", "ground" ], "enumTitles": [ "Top floor", "Intermediate floors", "Ground floor" ] } }, "features": { "title": "Features", "type": "array", "description": "Every listed feature must be present (Idealista applies them together).", "items": { "type": "string", "enum": [ "airConditioning", "wardrobes", "lift", "balcony", "terrace", "balconyAndTerrace", "exterior", "parking", "garden", "pool", "storageRoom", "accessible", "luxury", "heating", "security", "singleGarage", "doubleGarage", "coveredParking", "uncoveredParking", "privateGarden", "sharedGarden", "petsAllowed", "stateSubsidised", "seaViews" ], "enumTitles": [ "Air conditioning", "Fitted wardrobes", "Lift", "Balcony", "Terrace", "Balcony and terrace", "Exterior", "Parking or garage", "Garden", "Swimming pool", "Storage room", "Accessible home", "Luxury", "Heating", "Security", "Single garage (Italy)", "Double garage (Italy)", "Covered parking (Italy)", "Uncovered parking (Italy)", "Private garden (Italy)", "Shared garden (Italy)", "Pets allowed (rent)", "State subsidised (Spain)", "Sea views (Portugal)" ] } }, "energyEfficiency": { "title": "Energy efficiency", "type": "array", "description": "Idealista's energy certificate bands.", "items": { "type": "string", "enum": [ "high", "medium", "low" ], "enumTitles": [ "High", "Medium", "Low" ] } }, "occupancy": { "title": "Occupancy", "type": "array", "description": "For homes for sale.", "items": { "type": "string", "enum": [ "free", "tenanted", "bareOwnership", "illegallyOccupied" ], "enumTitles": [ "Available", "Rented with tenants", "Bare ownership", "Illegally occupied (Spain)" ] } }, "publishedWithin": { "title": "Published within", "enum": [ "24h", "48h", "week", "month", "any" ], "type": "string", "description": "Idealista's own publication date filter." }, "rentalType": { "title": "Rental type", "type": "array", "description": "For homes for rent.", "items": { "type": "string", "enum": [ "longTerm", "seasonal" ], "enumTitles": [ "Long term", "Seasonal" ] } }, "furnishing": { "title": "Furnishing", "enum": [ "furnished", "kitchenOnly", "any" ], "type": "string", "description": "For homes for rent." }, "auctions": { "title": "Auctions", "enum": [ "only", "exclude", "any" ], "type": "string", "description": "Where Idealista offers it (Italy)." }, "advertiserType": { "title": "Advertiser", "enum": [ "private", "professional", "any" ], "type": "string", "description": "Private advertisers only, or professionals only. Professionals: every property type (each card's own mark is checked; private ads are left out, free). Private: rooms in Spain and Italy (Idealista's own filter) and every Italian search (read in Idealista's private first order, so leave Order empty or set Private first); for other searches in Spain and Portugal Idealista offers no way to find private ads, so private is refused there with a free reason." }, "withFloorPlan": { "title": "With floor plan", "type": "boolean", "description": "Only ads with a floor plan." }, "withVirtualTour": { "title": "With virtual tour", "type": "boolean", "description": "Only ads with a virtual tour." }, "bankOwned": { "title": "Bank owned", "type": "boolean", "description": "Only properties sold by banks (Spain and Portugal; Italy has no such filter)." }, "siteFilters": { "title": "Other Idealista filters", "type": "array", "description": "Any other filter of Idealista's own search form, written as its form field and value, for example \"adfilter_hasheating=1\" or \"adfilter_onlineBooking=1\". The README lists them per property type.", "items": { "type": "string" } }, "includeDetails": { "title": "Listing details", "type": "boolean", "description": "Read every delivered ad's own page: full description, every feature line, energy certificate, approximate map position, update date, advertiser, photos with room tags, floor plans and videos. Billed as Listing details per ad." }, "includeAgencies": { "title": "Agencies", "type": "boolean", "description": "One Agency row for every agency met in the run (name, address, ads count, client since, publication quality, website, the areas it covers), once per agency. Billed as Agency." }, "includePhones": { "title": "Phone numbers", "type": "boolean", "description": "The advertiser's phone numbers of every delivered ad, from the ad page's own phone button. Agencies' and other professionals' numbers; Idealista does not serve a private advertiser's numbers to the Actor, so private ads get none (not read, not billed). Billed as Phone number per ad that has one." }, "includeCoordinates": { "title": "Map position", "type": "boolean", "description": "The ad's position on Idealista's own map (latitude, longitude) for search rows, from the site's map door (Listing details already carries it). Private advertisers' positions only with personal data on. Billed as Map position per ad." }, "includePersonalData": { "title": "Include personal data", "type": "boolean", "description": "Off by default. On, ads of private advertisers also carry the advertiser's first name, the street line, the exact map position and the advertiser's own link as Idealista shows them. You are responsible for a lawful use of personal data (GDPR included)." }, "maxItems": { "title": "Maximum listings", "minimum": 1, "maximum": 1000000, "type": "integer", "description": "The most Listing rows the run delivers in all." }, "maxItemsPerSearch": { "title": "Maximum listings per search", "minimum": 1, "maximum": 100000, "type": "integer", "description": "The most Listing rows one search delivers." }, "maxPagesPerSearch": { "title": "Maximum pages per search", "minimum": 1, "maximum": 60, "type": "integer", "description": "Idealista shows at most 60 pages of 30 ads per search. Default 60." }, "splitPastCap": { "title": "Go past the 1,800 ad cap", "type": "boolean", "description": "On by default: a search holding more than 1,800 ads is read in price bands, cheapest first, until every ad was met. Off: the first 1,800 only." }, "language": { "title": "Language", "enum": [ "es", "ca", "en", "it", "pt", "fr", "de", "nl", "no" ], "type": "string", "description": "Idealista's own page language for titles, labels and the advertiser's description where Idealista translates it. Default: the market's own language." }, "outputFormat": { "title": "Row format", "enum": [ "full", "compact", "idealistaApi" ], "type": "string", "description": "Default: full. \"Idealista API field names\" writes each listing with the field names of Idealista's own partner API (propertyCode, priceByArea, hasLift and so on), for tools built on that shape." }, "descriptionFormat": { "title": "Description format", "enum": [ "text", "html", "markdown" ], "type": "string", "description": "Default: text with line breaks." }, "descriptionTranslations": { "title": "Description translations", "type": "array", "description": "With Listing details: the advertiser's description in these languages too, as Idealista's own translation offers it (up to 5). No extra charge.", "items": { "type": "string", "enum": [ "es", "ca", "en", "it", "pt", "fr", "de", "da", "fi", "nl", "no", "pl", "ro", "ru", "sv", "el", "zh", "uk" ] } }, "descriptionMaxLength": { "title": "Description length limit", "minimum": 20, "maximum": 100000, "type": "integer", "description": "Optional: cut each description to this many characters (the full text otherwise)." }, "omitEmptyFields": { "title": "Leave out empty fields", "type": "boolean", "description": "Off by default. On, fields with no value are left out of each row instead of written as null." }, "maxConcurrency": { "title": "Parallel reads", "minimum": 1, "maximum": 4, "type": "integer", "description": "Reads in parallel (1 to 4). Default 3." }, "proxyUrls": { "title": "Your own proxies", "type": "array", "description": "Optional: your own proxy links (http://user:password@host:port), used instead of Apify residential proxies.", "items": { "type": "string" } } } }, "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 } } } } } } } } } }