{
  "openapi": "3.0.1",
  "info": {
    "title": "Idealista Scraper Ppr",
    "description": "Scrape Idealista.com properties across Spain, Portugal & Italy. 70+ data fields per listing: prices, GPS coordinates, agent contacts, amenities, price drops. Rentals & sales. $2/1K results. The richest output for real estate market research & lead generation.",
    "version": "1.0",
    "x-build-id": "A0XOZi3guqyfAMqwW"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/silentflow~idealista-scraper-ppr/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-silentflow-idealista-scraper-ppr",
        "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/silentflow~idealista-scraper-ppr/runs": {
      "post": {
        "operationId": "runs-sync-silentflow-idealista-scraper-ppr",
        "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/silentflow~idealista-scraper-ppr/run-sync": {
      "post": {
        "operationId": "run-sync-silentflow-idealista-scraper-ppr",
        "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": {
          "mode": {
            "title": "🔀 What to scrape",
            "enum": [
              "properties",
              "agencies"
            ],
            "type": "string",
            "description": "<b>Properties</b> returns one row per listing: price, price drops, size, rooms, floor, features, photos and the listing agency.<br><br><b>Agencies</b> scans the same search and returns one row per real estate agency instead: name, commercial name, phones, office address, postal code, city and profile URL, deduplicated across the whole run.",
            "default": "properties"
          },
          "searchUrl": {
            "title": "🔗 Idealista search URL",
            "type": "string",
            "description": "Paste the full URL of a search you already built on Idealista. Apply your filters on the site (location, price, rooms, rent or sale), then copy the address bar.<br><br><b>When this is set, every filter below is ignored</b> and the search is read exactly as written.<br><br><b>Heads up:</b> a pasted URL is capped by Idealista's own 60-page limit, about 1,800 properties. To pull a whole market past that ceiling, clear this field and use <code>City or region</code> instead."
          },
          "location": {
            "title": "📍 City or region",
            "type": "string",
            "description": "A city or region name: <code>madrid</code>, <code>barcelona</code>, <code>valencia</code>, <code>lisboa</code>, <code>porto</code>, <code>roma</code>, <code>bologna</code>.<br><br><b>This is the field that unlocks full market coverage.</b> Combined with a <code>Maximum properties</code> above 1800, the search is covered in slices instead of stopping at Idealista's 60-page ceiling. Measured: a Lisbon search delivered 2,000 properties and a Bologna search 2,500, with zero duplicates in either.<br><br>Only used when the Search URL above is empty."
          },
          "country": {
            "title": "🌍 Marketplace",
            "enum": [
              "es",
              "pt",
              "it"
            ],
            "type": "string",
            "description": "Which Idealista marketplace to read. Price, size, rooms and bathrooms filters work the same way on all three, and they combine freely in one search.",
            "default": "es"
          },
          "propertyType": {
            "title": "🏠 Property type",
            "enum": [
              "viviendas",
              "pisos",
              "casas",
              "aticos",
              "chalets",
              "habitacion",
              "oficinas",
              "locales",
              "garajes",
              "terrenos",
              "trasteros"
            ],
            "type": "string",
            "description": "Narrow the search to one kind of property. Leave on <b>All Homes</b> to include every residential type.<br><br>Applies to Spain searches. For Portugal and Italy, encode the property type in a Search URL copied from the site instead.",
            "default": "viviendas"
          },
          "priceMax": {
            "title": "💶 Maximum price (EUR)",
            "type": "integer",
            "description": "Keep only properties priced at or below this amount. On a rental search this is the monthly rent.<br><br>Works on Spain, Portugal and Italy, and stacks with Minimum size, Maximum size, Rooms and Bathrooms in the same search. Filtering here rather than after the run means fewer rows to pay for and nothing to clean up."
          },
          "sizeMin": {
            "title": "📐 Minimum size (m²)",
            "type": "integer",
            "description": "Keep only properties at or above this built size.<br><br>Works on Spain, Portugal and Italy, and stacks with Maximum price, Maximum size, Rooms and Bathrooms in the same search."
          },
          "sizeMax": {
            "title": "📏 Maximum size (m²)",
            "type": "integer",
            "description": "Keep only properties at or below this built size. Useful for isolating studios and entry level stock.<br><br>Works on Spain, Portugal and Italy, and stacks with Maximum price, Minimum size, Rooms and Bathrooms in the same search."
          },
          "rooms": {
            "title": "🛏️ Minimum rooms",
            "minimum": 0,
            "maximum": 4,
            "type": "integer",
            "description": "Keep only properties with at least this many rooms. <code>0</code> means no room filter.<br><br>Works on Spain, Portugal and Italy, and stacks with Maximum price, Minimum size, Maximum size and Bathrooms in the same search.<br><br><b>Italy quirk:</b> \"4 or more rooms\" matches properties with 5 or more, because Italy's own filters have no exact match for that value. The run log says so when it happens. Use 3 if you want four-room properties included.",
            "default": 0
          },
          "bathrooms": {
            "title": "🛁 Minimum bathrooms",
            "minimum": 0,
            "maximum": 3,
            "type": "integer",
            "description": "Keep only properties with at least this many bathrooms. <code>0</code> means no bathroom filter.<br><br>Works on Spain, Portugal and Italy, and stacks with Maximum price, Minimum size, Maximum size and Rooms in the same search.<br><br>Note: Idealista's search results almost never print a bathroom count on the listing itself, so the <code>bathrooms</code> output field is usually only filled when Enrich is on.",
            "default": 0
          },
          "sortBy": {
            "title": "↕️ Sort results by",
            "enum": [
              "",
              "precio-asc",
              "precio-desc",
              "metros-cuadrados-asc",
              "metros-cuadrados-desc",
              "fecha-publicacion-desc"
            ],
            "type": "string",
            "description": "Order the search before reading it. Works on Spain, Portugal and Italy.<br><br><b>Newest First</b> plus a small <code>Maximum properties</code> is the cheapest way to run a daily monitor: you get the new listings without re-reading the whole market. Deduplicate against yesterday's export on <code>propertyCode</code>.",
            "default": ""
          },
          "maxItems": {
            "title": "🎯 Maximum properties",
            "minimum": 0,
            "type": "integer",
            "description": "Hard cap on the rows this run delivers. <code>0</code> means no cap.<br><br>The cap is <b>exact</b>: ask for 2,000 and you get 2,000, not 1,974 and not 2,061.<br><br><b>Set this above 1800 to unlock full market coverage</b>, together with <code>City or region</code> (not a Search URL). Below that, a single Idealista search tops out at roughly 1,800 properties. In agencies mode this caps the number of distinct agencies instead.",
            "default": 0
          },
          "pages": {
            "title": "📄 Pages to read",
            "minimum": 1,
            "maximum": 60,
            "type": "integer",
            "description": "How many search result pages to read, about <b>30 properties per page</b>. Idealista serves at most 60 pages for a single search, so 60 is the practical maximum here.<br><br>Set it to 60 for a full sweep and let <code>Maximum properties</code> decide where the run actually stops.",
            "default": 1
          },
          "enrichDetails": {
            "title": "🏢 Enrich with agency contacts and details",
            "type": "boolean",
            "description": "<b>Off by default.</b> Turn it on to open each property's own page and add the data the search results never show:<ul><li>Agency phone in international format, plus a second line where one exists</li><li>The individual agent's name, and the agency's own real estate license number (for example Portugal's AMI number)</li><li>Agency office address and postal code, and how many listings that agency runs</li><li>Exact coordinates, street address and neighborhood</li><li>The 4-tier location hierarchy, the same shape in all three countries, so you can group Madrid, Lisbon and Rome in one dashboard</li><li>Bathroom count, usable area, community costs, condition, energy rating, property type</li><li>Floor and layout descriptions, the agency's own headline for the listing</li><li>Per-image room tags and dimensions, plus video and virtual tour links</li></ul>On a real Lisbon listing this took the row from 45 keys to 75.<br><br><b>Trade-off:</b> it reads one extra page per property, so the run takes noticeably longer. A good pattern is to sweep the market with this off, then re-run the shortlist with it on.<br><br>Idealista does not publish agent or agency email addresses anywhere, so no run returns one. Phone, office address, profile page and license number are what the platform makes public.",
            "default": false
          }
        }
      },
      "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
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}