{ "openapi": "3.0.1", "info": { "title": "Idealista Scraper - Property Data, Phones & Emails", "description": "Extract Idealista listings across Spain, Italy and Portugal: prices, advertiser phones, public agency emails, photos, coordinates and property details. Compare price per mΒ², identify published price reductions and export property and agency datasets with source links.", "version": "0.1", "x-build-id": "5iGOrLiCEwokK2n2s" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/trakk~idealista-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-trakk-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/trakk~idealista-scraper/runs": { "post": { "operationId": "runs-sync-trakk-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/trakk~idealista-scraper/run-sync": { "post": { "operationId": "run-sync-trakk-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": { "workflow": { "title": "What do you want to collect?", "enum": [ "FAST", "FULL_DETAILS", "LEADS" ], "type": "string", "description": "⚑ Fast is best for bulk market scans. Full details follows every search result to its property page. Agency leads also checks each unique professional advertiser for explicitly published public contacts.", "default": "FAST" }, "searchUrls": { "title": "Search URLs", "type": "array", "description": "πŸ”Ž Idealista search / result URLs from idealista.com, idealista.it or idealista.pt. Any filters already in the URL (location, rooms, price…) are respected.", "items": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "title": "URL of a web page", "format": "uri" } } } }, "detailUrls": { "title": "Detail URLs", "type": "array", "description": "πŸ“„ Individual property page URLs (e.g. …/inmueble/106387165/). A direct listing always returns its available full property record.", "default": [], "items": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "title": "URL of a web page", "format": "uri" } } } }, "startUrls": { "title": "Start URLs (mixed)", "type": "array", "description": "🧩 Mixed Idealista URLs. The Actor recognizes search pages and individual listings automatically, so you do not need to sort them.", "default": [], "items": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "title": "URL of a web page", "format": "uri" } } } }, "listingIds": { "title": "Listing IDs", "type": "array", "description": "πŸ†” Raw Idealista listing IDs (the number in the URL). They are turned into detail URLs using the Country + Language settings below.", "items": { "type": "string", "pattern": "^\\d{5,20}$" }, "default": [] }, "datasetId": { "title": "Input dataset", "type": "string", "description": "πŸ—‚οΈ Re-scrape a previous run: pick a dataset and the Actor pulls propertyId / adId / url / detailUrl from every item." }, "country": { "title": "Country", "enum": [ "ES", "IT", "PT" ], "type": "string", "description": "🌍 Country used when building URLs from a location slug or listing IDs.", "default": "ES" }, "operation": { "title": "Operation", "enum": [ "SALE", "RENT", "NEW_DEVELOPMENT" ], "type": "string", "description": "🏷️ Buy, rent or new-development β€” used only when building search URLs from a location slug.", "default": "SALE" }, "locationSlug": { "title": "Location slug", "pattern": "^[A-Za-z0-9][A-Za-z0-9-]{0,199}$", "type": "string", "description": "πŸ“ A single Idealista location slug, e.g. madrid-madrid, milano-milano, lisboa. For exact filters prefer pasting a Search URL instead." }, "locationSlugs": { "title": "Location slugs (many)", "type": "array", "description": "πŸ“ Several location slugs at once β€” one search URL is generated per slug.", "items": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9-]{0,199}$" }, "default": [] }, "language": { "title": "Language path", "pattern": "^[A-Za-z]{2}(?:-[A-Za-z]{2})?$", "type": "string", "description": "πŸ—£οΈ Language segment for generated URLs. Use en for English output where Idealista offers it (e.g. …/en/…).", "default": "en" }, "minPrice": { "title": "Minimum price", "minimum": 0, "type": "integer", "description": "πŸ’Ά Only listings at or above this price. Replaces any price filter already present in the search URL." }, "maxPrice": { "title": "Maximum price", "minimum": 0, "type": "integer", "description": "πŸ’Ά Only listings at or below this price. Replaces any price filter already present in the search URL." }, "maxItems": { "title": "Max items", "minimum": 0, "maximum": 100000, "type": "integer", "description": "πŸ”’ Hard cap on how many property rows are saved. Set 0 for unlimited.", "default": 100 }, "maxPagesPerSearch": { "title": "Max pages per search", "minimum": 1, "maximum": 100, "type": "integer", "description": "πŸ“„ How many result pages to walk for each search URL (or price range). Idealista shows ~30 listings per page.", "default": 3 }, "maxDetailUrls": { "title": "Max detail URLs", "minimum": 0, "maximum": 100000, "type": "integer", "description": "πŸ”’ Optional extra cap for DETAIL mode. Max items also caps DETAIL results; when both are set, the lower value wins.", "default": 0 }, "enablePriceSplitting": { "title": "Split by price range for full coverage", "type": "boolean", "description": "πŸͺ“ Idealista caps big searches at a limited number of pages. Turn this on to slice a broad search into price bands, grab far more listings, and get a coverage report per band.", "default": false }, "maxSplitDepth": { "title": "Max split depth", "minimum": 0, "maximum": 4, "type": "integer", "description": "πŸͺ“ How aggressively to keep splitting a price band that still has more pages than the page cap. Higher = more coverage, more requests.", "default": 1 }, "maxAgencySitePages": { "title": "Agency website pages", "minimum": 1, "maximum": 3, "type": "integer", "description": "🌐 Maximum public website pages checked per unique agency when email enrichment is enabled. Two normally covers the home and contact pages.", "default": 2 }, "rawOutput": { "title": "Include raw config snippets", "type": "boolean", "description": "πŸ§ͺ Add the parsed raw JS config objects (_rawConfig, _rawMapConfig) to detail records. For debugging / power users.", "default": false }, "proxy": { "title": "Proxy configuration", "type": "object", "description": "🌐 Idealista is behind DataDome, so residential proxies are strongly recommended. Defaults to Apify Residential; datacenter / no-proxy runs are almost always challenged.", "default": { "useApifyProxy": true, "apifyProxyGroups": [ "RESIDENTIAL" ] } }, "maxConcurrency": { "title": "Max concurrency", "minimum": 1, "maximum": 12, "type": "integer", "description": "⚑ How many detail requests run in parallel (DETAIL mode and Full details / Leads packages). Lower it if you see blocking.", "default": 5 }, "maxRetries": { "title": "Max retries", "minimum": 0, "maximum": 6, "type": "integer", "description": "πŸ” General retry budget per request (network hiccups, unexpected statuses).", "default": 3 }, "maxProxyRetries": { "title": "Max proxy retries", "minimum": 1, "maximum": 6, "type": "integer", "description": "πŸ” Retry budget dedicated to proxy / transport failures, with a fresh proxy each time.", "default": 3 }, "maxBlockRetries": { "title": "Max DataDome retries", "minimum": 1, "maximum": 6, "type": "integer", "description": "πŸ›‘οΈ Retry budget dedicated to DataDome challenge pages β€” each retry rotates the session/IP.", "default": 3 }, "requestTimeoutSecs": { "title": "Request timeout (seconds)", "minimum": 5, "maximum": 120, "type": "integer", "description": "⏱️ Per-request timeout in seconds.", "default": 30 }, "failOnSearchError": { "title": "Stop after the first search error", "type": "boolean", "description": "🚨 Off by default: a failing search URL is written to OUTPUT diagnostics and remaining URLs continue. Turn on to stop the remaining search URLs safely after the first error; the run still finishes successfully.", "default": false }, "impersonateProfile": { "title": "TLS impersonation profile", "type": "string", "description": "🎭 curl_cffi browser fingerprint for HTML pages. Safari currently passes Idealista best β€” change only if you know what you're doing.", "default": "safari" }, "acceptLanguage": { "title": "Accept-Language header", "type": "string", "description": "πŸ—£οΈ HTTP Accept-Language header sent with each request.", "default": "en-US,en;q=0.9" }, "outputFormat": { "title": "Export field format", "enum": [ "extended", "idealista" ], "type": "string", "description": "Extended preserves existing field types. Idealista-compatible uses numeric price and the source feature object.", "default": "extended" } } }, "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 } } } } } } } } } }