{ "openapi": "3.0.1", "info": { "title": "Idealista Scraper - Spain, Italy, Portugal, France Listings", "description": "Scrape Idealista property listings in Spain, Italy, Portugal and France. Get prices, sizes, locations and agencies, then track new listings and price changes. No account needed.", "version": "0.1", "x-build-id": "F64Q0itaRiL905C1g" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/cliqtomedia~idealista-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-cliqtomedia-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/cliqtomedia~idealista-scraper/runs": { "post": { "operationId": "runs-sync-cliqtomedia-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/cliqtomedia~idealista-scraper/run-sync": { "post": { "operationId": "run-sync-cliqtomedia-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": [ "country", "operation", "propertyType" ], "properties": { "country": { "title": "Country", "enum": [ "es", "it", "pt", "fr" ], "type": "string", "description": "Idealista site to search: Spain, Italy, Portugal or France. Default: Spain. URLs must belong to this country, or the run stops with an input error.", "default": "es" }, "operation": { "title": "Sale or rent", "enum": [ "sale", "rent" ], "type": "string", "description": "Choose listings for sale or for rent. Default: For sale. Rent prices are per month. Holiday rental prices are per night.", "default": "sale" }, "propertyType": { "title": "Property type", "enum": [ "newDevelopments", "homes", "bedrooms", "vacationRentals", "garages", "storageRooms", "offices", "premises", "transfers", "lands", "buildings" ], "type": "string", "description": "Kind of property to search. Default: Homes. Rooms means rooms for rent. Business transfers means businesses offered for transfer.", "default": "homes" }, "location": { "title": "Location", "type": "string", "description": "City, district or postal area name, the place part of an Idealista URL, or a search URL. Example: Madrid or madrid-madrid. Leave blank to search all provinces of the country. Locations, Postal codes, coordinates, a polygon and URLs replace this field.", "default": "Madrid" }, "maxItems": { "title": "Maximum results", "minimum": 0, "type": "integer", "description": "Maximum dataset rows across all areas. Default: 50. Example: 10 for a first test. Use 0 to continue until the search ends, the run times out or the charge limit is reached. Report removed listings needs 0. Up to 1800 rows per search are possible without splitting; above that the Actor splits the search for you.", "default": 50 }, "locations": { "title": "Locations", "type": "array", "description": "One city, area name or search URL per line. Example: Madrid, Barcelona. Areas run in this order. Replaces Location.", "items": { "type": "string" } }, "postalCodes": { "title": "Postal codes", "type": "array", "description": "One postal code per line, in the selected country. Example: 28001. Replaces Location, Locations, coordinates and polygon.", "items": { "type": "string" } }, "latitude": { "title": "Latitude", "minimum": -90, "maximum": 90, "type": "number", "description": "Center latitude of a circle search, from -90 to 90. Example: 40.4168. Also fill in Longitude. Replaces Location, Locations and polygon." }, "longitude": { "title": "Longitude", "minimum": -180, "maximum": 180, "type": "number", "description": "Center longitude of a circle search, from -180 to 180. Example: -3.7038. Also fill in Latitude." }, "distanceKm": { "title": "Radius in km", "minimum": 1, "type": "integer", "description": "Circle radius in whole kilometers, used only with Latitude and Longitude. Default: 20. Minimum: 1.", "default": 20 }, "polygon": { "title": "Map polygon", "type": "array", "description": "Search inside a shape. Add at least three [latitude, longitude] points. Example: [[40.45,-3.72],[40.45,-3.66],[40.40,-3.69]]. Replaces Location and Locations.", "items": { "type": "array", "items": { "type": "number" } } }, "propertyCodes": { "title": "Property codes or URLs", "type": "array", "description": "Listing IDs or listing URLs for direct lookup. Example: 112993138. Location and search filters are not used. Full details are included. A listing that no longer exists is reported in RUN_SUMMARY notFound.", "items": { "type": "string" } }, "startUrls": { "title": "Listing or search URLs", "type": "array", "description": "Idealista listing or search URLs from the selected country. A search URL brings its own area, sort and filters. Listing URLs work like Property codes. A URL filter this Actor cannot read stops the run with an error, so no filter is lost.", "items": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "title": "URL of a web page", "format": "uri" } } } }, "sortBy": { "title": "Sort order", "enum": [ "relevance", "lowestPrice", "highestPrice", "mostRecent", "leastRecent", "highestPriceReduction", "lowestPriceM2", "highestPriceM2", "biggest", "smallest", "highestFloors", "lowestFloors" ], "type": "string", "description": "Order of listings within each area. Default: Most recent. Holiday homes and new developments can only be ordered by price, so other choices use the source default for them.", "default": "mostRecent" }, "fetchDetails": { "title": "Include full details", "type": "boolean", "description": "Default: off. On: add full descriptions, the full photo gallery, energy ratings, coordinates and property characteristics. Each listing needs one more source request, so the run is slower and each listing has an extra Listing detail charge.", "default": false }, "minPrice": { "title": "Minimum price in EUR", "minimum": 0, "type": "number", "description": "Lowest price in EUR. Use the same basis as the listing: total for sale, per month for rent. Default: 0, no limit. Example: 200000.", "default": 0 }, "maxPrice": { "title": "Maximum price in EUR", "minimum": 0, "type": "number", "description": "Highest price in EUR. Must not be below Minimum price. Default: 0, no limit. Example: 500000.", "default": 0 }, "minSize": { "title": "Minimum area in m²", "minimum": 0, "type": "number", "description": "Smallest size in square meters. Default: 0, no limit. Example: 60.", "default": 0 }, "maxSize": { "title": "Maximum area in m²", "minimum": 0, "type": "number", "description": "Largest size in square meters. Must not be below Minimum size. Default: 0, no limit. Example: 120.", "default": 0 }, "publicationDate": { "title": "Published since", "enum": [ "", "Y", "T", "W", "M" ], "type": "string", "description": "Only listings published in this period. Default: Any time. Sale supports 48 hours, rent supports 24 hours, and both support week and month. Another choice for the operation stops the run with a clear error.", "default": "" }, "rentalTypes": { "title": "Rental types", "type": "array", "description": "Rental length. Empty: all rental types. Use with operation For rent.", "items": { "type": "string", "enum": [ "longTerm", "seasonal" ], "enumTitles": [ "Long term", "Seasonal" ] } }, "bedrooms": { "title": "Bedrooms", "type": "array", "description": "Number of bedrooms. Choose several to include each. Empty: any number.", "items": { "type": "string", "enum": [ "studio", "1", "2", "3", "4" ], "enumTitles": [ "Studio", "1", "2", "3", "4 or more" ] } }, "bathrooms": { "title": "Bathrooms", "type": "array", "description": "Number of bathrooms. Choose several to include each. Empty: any number.", "items": { "type": "string", "enum": [ "1", "2", "3" ], "enumTitles": [ "1", "2", "3 or more" ] } }, "homeType": { "title": "Home types", "type": "array", "description": "Kind of home, used with property type Homes. Choose several to include each. Empty: all kinds.", "items": { "type": "string", "enum": [ "flat", "penthouse", "duplex", "detachedHouse", "semiDetachedHouse", "terracedHouse", "countryHouse", "apartment", "villa", "loft" ], "enumTitles": [ "Flat", "Penthouse", "Duplex", "Detached house", "Semi-detached house", "Terraced house", "Country house", "Apartment", "Villa", "Loft" ] } }, "condition": { "title": "Condition", "type": "array", "description": "Property condition. Choose several to include each. Empty: any condition.", "items": { "type": "string", "enum": [ "newDevelopment", "good", "renew" ], "enumTitles": [ "New development", "Good condition", "Needs renovation" ] } }, "propertyStatus": { "title": "Occupancy status", "type": "array", "description": "Who occupies the property. Choose several to include each. Empty: any status.", "items": { "type": "string", "enum": [ "bareOwnership", "tenanted", "illegallyOccupied" ], "enumTitles": [ "Bare ownership", "Tenanted", "Illegally occupied" ] } }, "floor": { "title": "Floor", "type": "array", "description": "Floor position. Choose several to include each. Empty: any floor.", "items": { "type": "string", "enum": [ "topFloor", "intermediateFloor", "groundFloor" ], "enumTitles": [ "Top floor", "Middle floors", "Ground floor" ] } }, "agency": { "title": "Agency slug", "type": "string", "description": "Agency name from its Idealista URL, or that /pro/ URL. Example: clikalia. In listings mode, only listings of this agency are returned. In agency mode, its profile is returned." }, "bankOffer": { "title": "Bank listings", "type": "boolean", "description": "Off: no filter. On: keep only listings with bank-owned offers. Idealista applies this filter, and not every property type supports it.", "default": false }, "airConditioning": { "title": "Air conditioning", "type": "boolean", "description": "Off: no filter. On: keep only listings with air conditioning. Idealista applies this filter, and not every property type supports it.", "default": false }, "fittedWardrobes": { "title": "Fitted wardrobes", "type": "boolean", "description": "Off: no filter. On: keep only listings with fitted wardrobes. Idealista applies this filter, and not every property type supports it.", "default": false }, "lift": { "title": "Lift", "type": "boolean", "description": "Off: no filter. On: keep only listings with a lift. Idealista applies this filter, and not every property type supports it.", "default": false }, "balcony": { "title": "Balcony", "type": "boolean", "description": "Off: no filter. On: keep only listings with a balcony. Idealista applies this filter, and not every property type supports it.", "default": false }, "terrace": { "title": "Terrace", "type": "boolean", "description": "Off: no filter. On: keep only listings with a terrace. Idealista applies this filter, and not every property type supports it.", "default": false }, "exterior": { "title": "Exterior", "type": "boolean", "description": "Off: no filter. On: keep only listings with an exterior position. Idealista applies this filter, and not every property type supports it.", "default": false }, "garage": { "title": "Garage or parking", "type": "boolean", "description": "Off: no filter. On: keep only listings with a garage. Idealista applies this filter, and not every property type supports it.", "default": false }, "garden": { "title": "Garden", "type": "boolean", "description": "Off: no filter. On: keep only listings with a garden. Idealista applies this filter, and not every property type supports it.", "default": false }, "swimmingPool": { "title": "Swimming pool", "type": "boolean", "description": "Off: no filter. On: keep only listings with a swimming pool. Idealista applies this filter, and not every property type supports it.", "default": false }, "storageRoom": { "title": "Storage room", "type": "boolean", "description": "Off: no filter. On: keep only listings with a storage room. Idealista applies this filter, and not every property type supports it.", "default": false }, "accessible": { "title": "Accessible", "type": "boolean", "description": "Off: no filter. On: keep only listings with accessible access. Idealista applies this filter, and not every property type supports it.", "default": false }, "seaViews": { "title": "Sea views", "type": "boolean", "description": "Off: no filter. On: keep only listings with sea views. Idealista applies this filter, and not every property type supports it.", "default": false }, "luxury": { "title": "Luxury homes", "type": "boolean", "description": "Off: no filter. On: keep only listings with the luxury label. Idealista applies this filter, and not every property type supports it.", "default": false }, "plan": { "title": "Floor plan", "type": "boolean", "description": "Off: no filter. On: keep only listings with a floor plan. Idealista applies this filter, and not every property type supports it.", "default": false }, "virtualTour": { "title": "Virtual tour", "type": "boolean", "description": "Off: no filter. On: keep only listings with a virtual tour. Idealista applies this filter, and not every property type supports it.", "default": false }, "onlyPriceDrops": { "title": "Only price drops", "type": "boolean", "description": "Default: off. On: save only listings with a price reduction that Idealista shows now. Pages are checked until enough matches are found, and each checked page is charged.", "default": false }, "minPriceDropPercentage": { "title": "Minimum price reduction (%)", "minimum": 0, "maximum": 100, "type": "number", "description": "Keep only listings reduced by at least this percent, from 0 to 100. Default: 0, no minimum. Any value above 0 also limits results to reduced listings. Example: 10.", "default": 0 }, "onlyNew": { "title": "Only new listings", "type": "boolean", "description": "Default: off. On: save only listings not in the saved history of this search. The first run saves all results it finds. Checked pages are charged even if nothing new is found.", "default": false }, "monitoringMode": { "title": "Monitor listings", "type": "boolean", "description": "Default: off. On: keep listing history between runs of the same search. Turn on the two change options below to get price changes or removals.", "default": false }, "detectPriceChanges": { "title": "Report price changes", "type": "boolean", "description": "Needs Monitor listings. Save a price_change row when the price of a known listing changes. Default: off.", "default": false }, "detectRemovedListings": { "title": "Report removed listings", "type": "boolean", "description": "Needs Monitor listings and Maximum results set to 0. Save a removed row when a known listing is missing from a complete scan of the same search. A price or feature change can also move a listing out of a search, so a removed row does not prove a sale. Default: off.", "default": false }, "stateName": { "title": "History store name", "type": "string", "description": "Optional name of your private history store. Use letters, numbers and hyphens, up to 63 characters. Example: madrid-flats. Leave empty to get a separate store for each search. Run one search with the same history at a time." }, "mode": { "title": "Result type", "enum": [ "listings", "agencies" ], "type": "string", "description": "Listings: collect properties. Agency profiles: collect public business profiles from Agency or Agency profiles, and ignore area and listing filters. Default: Listings.", "default": "listings" }, "agencySlugs": { "title": "Agency profiles", "type": "array", "description": "Agency names or Idealista /pro/ URLs, used in agency mode. Example: clikalia. Each profile gives one row with public business data. Private contact fields are not collected.", "items": { "type": "string" } }, "deliveryConnector": { "title": "Send results to (optional)", "type": "string", "description": "Your Slack, Notion or other MCP connector. After the run the Actor posts a short summary there. Connect services once in Apify Console → MCP connectors. Default: nothing is sent." }, "deliveryTarget": { "title": "Notion page or channel (optional)", "type": "string", "description": "Where to post the summary: a Notion page link (each run is added on top of that page) or a Slack channel ID. Leave empty to let the connector decide." } } }, "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 } } } } } } } } } }