{
  "openapi": "3.0.1",
  "info": {
    "title": "Idealista Scraper for Spain, Italy and Portugal",
    "description": "Scrape Idealista sale and rental listings in Spain, Italy and Portugal. Filter searches, export JSON or CSV, and add property details. Run summaries show where collection stopped.",
    "version": "0.1",
    "x-build-id": "pnK6jwzi9y4lx3lEx"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/fagenorn~idealista-scraper/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-fagenorn-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/fagenorn~idealista-scraper/runs": {
      "post": {
        "operationId": "runs-sync-fagenorn-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/fagenorn~idealista-scraper/run-sync": {
      "post": {
        "operationId": "run-sync-fagenorn-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": {
          "startUrls": {
            "title": "Start URLs",
            "type": "array",
            "description": "Paste an Idealista location search URL from Spain, Italy or Portugal. The domain, operation and property type are detected; pagination is automatic. Spanish precio-desde/precio-hasta URL filters are supported. Other URL filters are rejected with instructions to use the fields below, so your search is never broadened silently. The default run returns up to 100 listings.",
            "items": {
              "type": "object",
              "required": [
                "url"
              ],
              "properties": {
                "url": {
                  "type": "string",
                  "title": "URL of a web page",
                  "format": "uri"
                }
              }
            }
          },
          "searchQueries": {
            "title": "Locations by name",
            "type": "array",
            "description": "Alternative to URLs: enter location names such as Madrid, Lisboa or Milano and select the correct country. Leave empty when using only URLs. Multiple input sources combine.",
            "items": {
              "type": "string"
            }
          },
          "locationIds": {
            "title": "Location IDs (advanced)",
            "type": "array",
            "description": "Alternative for exact targeting: Idealista location IDs, such as 0-EU-ES-28-07-001-079. Copy location.locationId from a listing in a previous run. The country is detected from the ID.",
            "items": {
              "type": "string"
            }
          },
          "country": {
            "title": "Country",
            "enum": [
              "es",
              "it",
              "pt"
            ],
            "type": "string",
            "description": "idealista market (derived automatically from Start URL domains).",
            "default": "es"
          },
          "operation": {
            "title": "Operation",
            "enum": [
              "sale",
              "rent"
            ],
            "type": "string",
            "description": "Buy (sale) or rent. Ignored for Start URLs that already encode the operation.",
            "default": "sale"
          },
          "propertyType": {
            "title": "Property type",
            "enum": [
              "homes",
              "offices",
              "premises",
              "garages",
              "bedrooms"
            ],
            "type": "string",
            "description": "homes = flats/houses, premises = commercial spaces, bedrooms = shared rooms (flatshare — rent only; sale queries are switched to rent automatically). Ignored for Start URLs that already encode the type.",
            "default": "homes"
          },
          "locale": {
            "title": "Language",
            "enum": [
              "en",
              "es",
              "it",
              "pt"
            ],
            "type": "string",
            "description": "Language for descriptions and texts returned by idealista.",
            "default": "en"
          },
          "priceFrom": {
            "title": "Price from (€)",
            "minimum": 0,
            "type": "integer",
            "description": "Minimum price. For rent queries this is per month. 0 = no lower bound.",
            "default": 0
          },
          "priceTo": {
            "title": "Price to (€)",
            "minimum": 0,
            "type": "integer",
            "description": "Maximum price. For rent queries this is per month. 0 = no upper bound.",
            "default": 0
          },
          "bedrooms": {
            "title": "Bedrooms",
            "type": "array",
            "description": "Exact bedroom counts to include — list several for any-of (e.g. 2 and 3 matches both 2- and 3-bedroom homes). 0 = studio. Leave empty for any number of bedrooms.",
            "items": {
              "type": "string"
            }
          },
          "publishedWithin": {
            "title": "Published within",
            "enum": [
              "any",
              "yesterday",
              "week",
              "month"
            ],
            "type": "string",
            "description": "Only listings idealista published in this window (yesterday / last week / last month). Pair with Order by = publicationDate for monitoring runs on a schedule.",
            "default": "any"
          },
          "includeDetails": {
            "title": "Enrich with full property details",
            "type": "boolean",
            "description": "Adds descriptions, contact information, energy information and media when Idealista supplies them. Successful enrichment has an additional event charge; check the Pricing tab for current rates. Failed detail requests keep the base listing without an enrichment charge.",
            "default": false
          },
          "maxItems": {
            "title": "Maximum listings",
            "minimum": 0,
            "type": "integer",
            "description": "Maximum listings saved across all queries. Start with 100 to check your search. Set 0 for no global listing cap. Use Apify Max cost per run to limit monetary charges; proxy and other platform costs follow the pricing settings.",
            "default": 100
          },
          "maxItemsPerQuery": {
            "title": "Max listings per query",
            "minimum": 1,
            "type": "integer",
            "description": "Maximum saved listings for each location query (default 1,000). Idealista also has an upstream result window around 2,500–3,000 per query. Check coverage and split large markets by district or price range.",
            "default": 1000
          },
          "maxPages": {
            "title": "Max pages per query (advanced)",
            "minimum": 0,
            "type": "integer",
            "description": "Hard cap on pages per query (0 = derive from max listings per query). 1 = first page only.",
            "default": 0
          },
          "filters": {
            "title": "Filters (JSON, advanced)",
            "type": "object",
            "description": "Extra Idealista filters, for example {\"minSize\":80,\"bathrooms\":\"2,3\",\"terrace\":true}. Explicit non-zero price fields, a non-empty Bedrooms list, and a specific Published within value override matching JSON keys. They also override imported URL price filters. Default 0/any/empty values do not erase JSON filters. Unsupported upstream filter names may be ignored by Idealista.",
            "default": {}
          },
          "sort": {
            "title": "Sort direction (advanced)",
            "enum": [
              "desc",
              "asc"
            ],
            "type": "string",
            "description": "Direction of the selected order: descending gives newest first with Publication date; ascending gives oldest first. Relevance is Idealista’s own ranking.",
            "default": "desc"
          },
          "order": {
            "title": "Order by (advanced)",
            "enum": [
              "weigh",
              "publicationDate"
            ],
            "type": "string",
            "description": "weigh = idealista's relevance order, publicationDate = newest first (use for monitoring).",
            "default": "weigh"
          },
          "maxConcurrency": {
            "title": "Max concurrency (advanced)",
            "minimum": 1,
            "maximum": 200,
            "type": "integer",
            "description": "Maximum parallel requests, each with a device and proxy session. Start with the default of 30; actual speed depends on proxies, upstream responses and retries. Without a proxy this is capped at 8.",
            "default": 8
          },
          "minRequestIntervalMs": {
            "title": "Min interval per device, ms (advanced)",
            "minimum": 0,
            "type": "integer",
            "description": "Politeness gap between two requests from the same simulated device. Lower = faster.",
            "default": 750
          },
          "proxyConfiguration": {
            "title": "Proxy configuration",
            "type": "object",
            "description": "Residential proxy recommended for Apify cloud runs. For a single-country run, the proxy country is derived automatically unless explicitly supplied. Mixed-country runs leave the proxy country unset. Without a proxy, Idealista may block the cloud IP. The configured Apify proxy is included in the launch event prices."
          }
        }
      },
      "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
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}