{ "openapi": "3.0.1", "info": { "title": "Idealista Scraper API - Properties & Agency Leads", "description": "124 fields per listing across Spain, Italy and Portugal. Advertiser phones on 93% of cards, agency emails with the public page they came from, GPS, floor plans and price per m2. Reads past Idealista's 1,500-result ceiling, and every run reports what Idealista claimed against what you got.", "version": "0.1", "x-build-id": "gHRmL0i5xAHamGrss" }, "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" } } } }, "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 }, "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" } } } }, "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" } } } }, "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." }, "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 }, "agencyLookupTimeoutSecs": { "title": "⏱️ Agency contact lookup budget (seconds)", "minimum": 5, "maximum": 600, "type": "integer", "description": "How long one agency may take to yield a public contact. A lookup reads the agency's Idealista profile and up to a couple of pages of its own website, so it needs more room than a single request. Leave empty and the Actor works it out from the request timeout and the page budget. The result is cached, so each agency costs this once no matter how many of its listings you collect." }, "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 }, "centreLatitude": { "title": "πŸ“ Centre latitude", "type": "string", "description": "Centre of a circular search area. Fill this in together with the longitude and a radius, and only listings inside the circle are saved β€” the rest are never charged for. Listings whose coordinates Idealista withholds are kept." }, "centreLongitude": { "title": "πŸ“ Centre longitude", "type": "string", "description": "Longitude of the circle's centre, paired with the latitude above." }, "radiusKm": { "title": "β­• Radius (km)", "type": "string", "description": "How far from the centre to keep listings, in kilometres. Each saved row gains a distanceFromCentreKm field so you can sort by how close it is." }, "areaPolygon": { "title": "πŸ”· Polygon corners", "type": "string", "description": "A shape instead of a circle: corners as [[lat, lng], [lat, lng], …] JSON, or as plain \"lat,lng lat,lng …\" pairs separated by spaces. Three corners or more. Takes precedence over the circle when both are given." }, "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 }, "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 } } } } } } } } } }