{ "openapi": "3.0.1", "info": { "title": "Smart Idealista Scraper - Spain, Italy, Portugal Properties", "description": "Idealista scraper and property data API for Spain, Italy and Portugal. Search sale and rental homes, new builds, rooms, garages, offices, land and commercial units by city, search URL, map polygon or CSV; return price, size, rooms, energy rating, year built and price history.", "version": "2.0", "x-build-id": "e2uc92ahqd21k1EZm" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/sian.agency~smart-idealista-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-sian.agency-smart-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/sian.agency~smart-idealista-scraper/runs": { "post": { "operationId": "runs-sync-sian.agency-smart-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/sian.agency~smart-idealista-scraper/run-sync": { "post": { "operationId": "run-sync-sian.agency-smart-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" ], "properties": { "country": { "title": "Country", "enum": [ "es", "it", "pt" ], "type": "string", "description": "🌍 Select the Idealista country domain", "default": "es" }, "operation": { "title": "Operation", "enum": [ "sale", "rent" ], "type": "string", "description": "🏠 What type of listing?", "default": "rent" }, "endpoint": { "title": "Property Category", "enum": [ "listhomes", "listnewhomes", "liststoragerooms", "listbuildings", "listlands", "listgarages", "listcommercialproperties", "listoffices", "listrooms" ], "type": "string", "description": "🏘️ Select the type of property category to search", "default": "listhomes" }, "searchUrl": { "title": "πŸ”— Paste a Search URL", "type": "string", "description": "Paste any Idealista search-results URL and we'll auto-detect the location + filters from the page.\n\n**Example:** `https://www.idealista.com/en/venta-terrenos/jaen/la-loma-y-las-villas/`\n\nπŸ’Έ **Pricing:** $0.005 per URL + $0.003 per property delivered (PAID tier only)." }, "polygonUrl": { "title": "πŸ—ΊοΈ Paste a Polygon (Areas) URL", "type": "string", "description": "Paste an Idealista Areas URL with a drawn-polygon shape parameter.\n\n**Example:** `https://www.idealista.com/en/areas/venta-viviendas/?shape=((...))`\n\nπŸ’Έ **Pricing:** $0.01 per search + $0.003 per property (PAID tier only)." }, "deepSingleUrl": { "title": "πŸ”Ž Deep-Scrape a Single Listing URL", "type": "string", "description": "Paste one Idealista detail URL and get the full extended-field set (energy certificate, year built, community fees, price-change history, floor-plan / 3D-tour URLs).\n\n**Example:** `https://www.idealista.com/en/inmueble/111577630/`\n\nπŸ’Έ **Pricing:** $0.05 per URL (PAID tier only β€” replaces the per-property charge)." }, "deepFieldSet": { "title": "πŸ“‹ Deep Mode β€” Field Set", "enum": [ "standard", "extended" ], "type": "string", "description": "Controls how many fields the deep-scrape returns.\n\n- **standard**: only fields the existing search API already exposes\n- **extended**: adds energy certificate, year built, community fees, IBI, price history, floor-plan + 3D-tour URLs", "default": "extended" }, "agencySlugs": { "title": "🏒 Agency Slugs or Agency URLs", "type": "array", "description": "Turn agency identifiers into agency profiles: commercial name, phone, office address with GPS, active-since year, languages, total listings and a listings-by-location breakdown.\n\nOne entry per agency β€” the slug (`walterhauschamberi`) or the full agency URL (`https://www.idealista.com/pro/walterhauschamberi/`).\n\nEvery property row includes an `agencyUrl`, so run a property search first, then enrich the agencies behind those listings. Uses the Country and Operation fields above. PAID tier only.", "items": { "type": "string" } }, "locationId": { "title": "πŸ“ Location ID (Single Location)", "type": "string", "description": "πŸ“ Single Idealista location ID, e.g. `0-EU-ES-28-07-001-079` (Madrid). For several locations use 'Multiple Locations' below.\n\n**Formats:** Spain `0-EU-ES-XX-YYY`, Italy `0-EU-IT-XX-YYY` (Rome `0-EU-IT-RM-01-001-097`), Portugal `0-EU-PT-XX` (Lisbon `0-EU-PT-11`).\n\n**Find it:** search your location on idealista.com, open DevTools (F12) β†’ Network, run a search, then copy the `locationId=` parameter.", "default": "0-EU-ES-28-07-001-079" }, "locationName": { "title": "πŸ“ Location Name (Single Location)", "type": "string", "description": "πŸ“ Single location name (e.g., Madrid, Barcelona, Rome)\n\nRequired when using Location ID field above.\n\nπŸ’‘ **FREE tier:** Single location only\nπŸ’Ž **PAID tier:** Use CSV upload below for bulk locations", "default": "Madrid" }, "locationsCsv": { "title": "πŸ“ Upload CSV File - Excel/Google Sheets Friendly (PAID Tier)", "type": "array", "description": "πŸ“ CSV upload (PAID tier only) β€” scan many locations in one run.\n\n**Columns:** `locationId` (e.g. `0-EU-ES-28-07-001-079`) and `locationName` (e.g. `Madrid`). Header row optional; `location_id` / `id` also accepted. Duplicates are removed automatically.\n\n```\nlocationId,locationName\n0-EU-ES-28-07-001-079,Madrid\n0-EU-IT-RM-01-001-097,Rome\n```\n\nMutually exclusive with the JSON field above.", "items": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "title": "URL of a web page", "format": "uri" } } } }, "numPages": { "title": "Number of Pages to Scrape", "minimum": 1, "maximum": 250, "type": "integer", "description": "πŸ“„ How many pages to scrape\n\nβ€’ Each page contains ~30 properties (charged for 30)\nβ€’ 🎁 **Launch Bonus:** Get 40 properties per page - 10 extra FREE!\nβ€’ Duplicates are automatically removed (pagination overlap)\nβ€’ Example: 5 pages = ~145-150 unique properties (up to 200 with bonus!)\n\nπŸ’‘ **Tip:** Start with 1-2 pages to test your filters, then scale up as needed.", "default": 1 }, "order": { "title": "Sort Results By", "enum": [ "relevance", "lowestprice", "highestprice", "mostrecent", "leastrecent", "highestpricereduction", "lowestpricem2", "highestpricem2", "biggest", "smallest", "highestfloors", "lowestfloors" ], "type": "string", "description": "πŸ“Š How to order the search results", "default": "mostrecent" }, "language": { "title": "Result Language", "enum": [ "en", "es", "it", "pt", "de", "fr", "ca", "nl", "nb" ], "type": "string", "description": "🌐 Language for property descriptions", "default": "en" }, "minPrice": { "title": "Minimum Price (EUR)", "minimum": 0, "type": "integer", "description": "Minimum property price in EUR" }, "maxPrice": { "title": "Maximum Price (EUR)", "minimum": 0, "type": "integer", "description": "Maximum property price in EUR" }, "minSize": { "title": "Minimum Size (mΒ²)", "minimum": 0, "type": "integer", "description": "Minimum property size in square meters" }, "maxSize": { "title": "Maximum Size (mΒ²)", "minimum": 0, "type": "integer", "description": "Maximum property size in square meters" }, "bedrooms0": { "title": "Studio (0 bedrooms)", "type": "boolean", "description": "Include studio apartments" }, "bedrooms1": { "title": "1 Bedroom", "type": "boolean", "description": "Include properties with 1 bedroom" }, "bedrooms2": { "title": "2 Bedrooms", "type": "boolean", "description": "Include properties with 2 bedrooms" }, "bedrooms3": { "title": "3 Bedrooms", "type": "boolean", "description": "Include properties with 3 bedrooms" }, "bedrooms4": { "title": "4+ Bedrooms", "type": "boolean", "description": "Include properties with 4 or more bedrooms" }, "bathrooms1": { "title": "1 Bathroom", "type": "boolean", "description": "Include properties with 1 bathroom" }, "bathrooms2": { "title": "2 Bathrooms", "type": "boolean", "description": "Include properties with 2 bathrooms" }, "bathrooms3": { "title": "3+ Bathrooms", "type": "boolean", "description": "Include properties with 3 or more bathrooms" }, "flat": { "title": "All Apartment Types", "type": "boolean", "description": "Include flats, penthouses, and duplexes (all apartment types)" }, "onlyFlats": { "title": "Only Flats", "type": "boolean", "description": "Only standard flats/apartments" }, "penthouse": { "title": "Penthouses", "type": "boolean", "description": "Include penthouse apartments" }, "duplex": { "title": "Duplex", "type": "boolean", "description": "Include duplex apartments" }, "chalet": { "title": "All House Types", "type": "boolean", "description": "Include all house types (independent, semi-detached, terraced, country)" }, "independantHouse": { "title": "Independent Houses", "type": "boolean", "description": "Include independent/detached houses" }, "semidetachedHouse": { "title": "Semi-Detached Houses", "type": "boolean", "description": "Include semi-detached houses" }, "terracedHouse": { "title": "Terraced Houses", "type": "boolean", "description": "Include terraced/row houses" }, "countryHouse": { "title": "Country Houses", "type": "boolean", "description": "Include country houses" }, "apartamentoType": { "title": "Apartamento Type", "type": "boolean", "description": "Specific apartment classification" }, "villaType": { "title": "Villas", "type": "boolean", "description": "Include villas" }, "loftType": { "title": "Lofts", "type": "boolean", "description": "Include loft spaces" }, "cortijoType": { "title": "Cortijos", "type": "boolean", "description": "Include cortijos (traditional Spanish farmhouses)" }, "atticStudioType": { "title": "Attic Studios", "type": "boolean", "description": "Include attic studio apartments" }, "casaBajaType": { "title": "Casa Baja", "type": "boolean", "description": "Include ground floor houses (casa baja)" }, "newDevelopment": { "title": "New Development", "type": "boolean", "description": "Only new development properties" }, "good": { "title": "Good Condition", "type": "boolean", "description": "Properties in good condition" }, "renew": { "title": "To Renew", "type": "boolean", "description": "Properties that need renovation" }, "furnished": { "title": "Furnished", "enum": [ "", "furnished", "furnishedKitchen" ], "type": "string", "description": "Furnishing status (only for rent operation)", "default": "" }, "isBareOwnership": { "title": "Bare Ownership", "type": "boolean", "description": "Properties sold as bare ownership" }, "isTenanted": { "title": "Tenanted", "type": "boolean", "description": "Properties currently tenanted" }, "isIllegallyOccupied": { "title": "Illegally Occupied", "type": "boolean", "description": "Properties illegally occupied" }, "isFree": { "title": "Free/Vacant", "type": "boolean", "description": "Properties that are free without restrictions" }, "airConditioning": { "title": "Air Conditioning", "type": "boolean", "description": "Has air conditioning" }, "builtinWardrobes": { "title": "Built-in Wardrobes", "type": "boolean", "description": "Has built-in wardrobes" }, "elevator": { "title": "Elevator", "type": "boolean", "description": "Building has elevator" }, "exterior": { "title": "Exterior", "type": "boolean", "description": "Exterior-facing property" }, "garage": { "title": "Garage", "type": "boolean", "description": "Has garage/parking" }, "garden": { "title": "Garden", "type": "boolean", "description": "Has garden" }, "swimmingPool": { "title": "Swimming Pool", "type": "boolean", "description": "Has swimming pool" }, "terrance": { "title": "Terrace", "type": "boolean", "description": "Has terrace" }, "storeRoom": { "title": "Store Room", "type": "boolean", "description": "Has storage room" }, "accessible": { "title": "Accessible", "type": "boolean", "description": "Wheelchair accessible" }, "luxury": { "title": "Luxury", "type": "boolean", "description": "Luxury property" }, "petsAllowed": { "title": "Pets Allowed", "type": "boolean", "description": "Pets allowed (rent only)" }, "hasPlan": { "title": "Has Floor Plan", "type": "boolean", "description": "Property has floor plan available" }, "virtualTour": { "title": "Virtual Tour", "type": "boolean", "description": "Has virtual tour available" }, "bankOffer": { "title": "Bank Offer", "type": "boolean", "description": "Bank-owned property" }, "topFloor": { "title": "Top Floor", "type": "boolean", "description": "Top floor only" }, "intermediateFloor": { "title": "Intermediate Floor", "type": "boolean", "description": "Intermediate floor only" }, "sinceDate": { "title": "Published Since", "enum": [ "", "T", "Y", "W", "M" ], "type": "string", "description": "πŸ“… Filter by publication date\n\n**Options:**\nβ€’ Any Time: (default) - All listings\nβ€’ Last 24h: T - **Rent operation only**\nβ€’ Last 48h: Y - **Buy/Sale operation only**\nβ€’ Last Week: W - Available for both operations\nβ€’ Last Month: M - Available for both operations\n\n⚠️ Note: T (24h) only works with rent, Y (48h) only works with sale", "default": "" }, "longTermResidential": { "title": "Long-Term Residential", "type": "boolean", "description": "Long-term residential rental" }, "shortTerm": { "title": "Short-Term/Seasonal", "type": "boolean", "description": "Short-term or seasonal rental (rent only)" }, "micrositeShortName": { "title": "Real Estate Agency", "type": "string", "description": "πŸ“ Filter by specific real estate agency\n\nGet ads from a specific agency. Extract from agency URL:\nhttps://www.idealista.com/pro/cajal-gestion-inmobiliaria/\nβ†’ use: cajal-gestion-inmobiliaria" }, "center": { "title": "GPS Coordinates", "type": "string", "description": "Latitude,longitude for radius search (e.g., '40.416,-3.703')" }, "distance": { "title": "Search Radius (meters)", "minimum": 100, "maximum": 100000, "type": "integer", "description": "Radius around GPS coordinates (100-100,000 meters). Only used when GPS coordinates are provided." } } }, "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 } } } } } } } } } }