{ "openapi": "3.0.1", "info": { "title": "Idealista Property Scraper", "description": "Scrape normalized property listings from idealista.com (Spain), idealista.it (Italy), and idealista.pt (Portugal) in one run — unified EUR/m² schema, sale or rent, plus agency and lister contact enrichment neither incumbent ships together.", "version": "0.2", "x-build-id": "uj4fW4pQMnvvFusKl" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/devilscrapes~idealista-property-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-devilscrapes-idealista-property-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/devilscrapes~idealista-property-scraper/runs": { "post": { "operationId": "runs-sync-devilscrapes-idealista-property-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/devilscrapes~idealista-property-scraper/run-sync": { "post": { "operationId": "run-sync-devilscrapes-idealista-property-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": { "countries": { "title": "Countries", "type": "array", "description": "Countries to run (ES/IT/PT). Each country runs independently — one blocked country doesn't stop the others.", "items": { "type": "string", "enum": [ "ES", "IT", "PT" ], "enumTitles": [ "Spain (ES)", "Italy (IT)", "Portugal (PT)" ] }, "default": [ "ES" ] }, "searchUrls": { "title": "Search URLs", "type": "array", "description": "Direct idealista.com / idealista.it / idealista.pt search URLs to scrape as-is. Country is inferred from the TLD. Up to 50. One of Search URLs or (Countries + Location) is required.", "items": { "type": "string" } }, "location": { "title": "Location", "type": "string", "description": "idealista's own two-part search slug — municipality-province, e.g. 'madrid-madrid' (most municipalities do NOT share their province's name; find the exact slug by searching the location on idealista.com and copying it from the resulting URL). Required (together with Countries) if Search URLs is unset." }, "operation": { "title": "Operation", "enum": [ "sale", "rent" ], "type": "string", "description": "Sale vs. rent. Country-agnostic — mapped to the right per-TLD slug internally.", "default": "sale" }, "propertyType": { "title": "Property type", "enum": [ "homes", "offices", "premises", "garages", "land" ], "type": "string", "description": "Shared property-type taxonomy across all three TLDs.", "default": "homes" }, "maxResultsPerCountry": { "title": "Max results per country", "minimum": 1, "maximum": 2000, "type": "integer", "description": "Cap on rows per country; each country's cap is independent.", "default": 100 }, "enrichAgencyContact": { "title": "Enrich from detail page (bathrooms, energy rating, coordinates, agent reference, full gallery)", "type": "boolean", "description": "Fetch each listing's detail page and add bathrooms, a richer floor label, EU energy rating letter (when the listing's page exposes one), lat/lon coordinates, the agency's own reference code, and the full photo gallery/description. OFF by default: a measured 100-row run costs ~17x more residential-proxy transfer per row than leaving it off ($45.73 vs. $2.65 per 1,000 rows COGS). The default (OFF) path already returns rooms, area, floor, a description snippet, the agency name, city/neighborhood, and 1-3 photos straight from the search page at no extra cost — turn this on only if you specifically need bathrooms/energy rating/coordinates/full gallery. Agency phone and owner type (professional vs. private) are not exposed anywhere in idealista's page markup on any of the three sites and stay null even with this on.", "default": false }, "proxyCountryMap": { "title": "Proxy country map", "type": "object", "description": "Override the proxy exit country per target country. Keys are a subset of ES/IT/PT. Idealista hard-localizes by IP — a mismatched exit silently returns the wrong country's listings.", "default": { "ES": "ES", "IT": "IT", "PT": "PT" } }, "proxyConfiguration": { "title": "Proxy configuration", "type": "object", "description": "Mandatory-by-default RESIDENTIAL — country_code is resolved per-request from Proxy country map, not set directly here.", "default": { "useApifyProxy": true, "apifyProxyGroups": [ "RESIDENTIAL" ] } } } }, "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 } } } } } } } } } }