{
  "openapi": "3.0.1",
  "info": {
    "title": "Idealista Scrape- LowCost | HiQuality (ES/PT/IT)",
    "description": "▎ Reliable Idealista data, at a fair price.\n  ▎ We built the most efficient scraper for Idealista because we believe quality data shouldn't cost a fortune. No captchas, no browser overhead — just \n  ▎ clean, structured data that works.\n  ▎ Questions or ideas? → info@inmocalc.com",
    "version": "0.0",
    "x-build-id": "GqhOk6ilMHVeRTWR0"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/scraper_gump~idealista-scraper/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-scraper_gump-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/scraper_gump~idealista-scraper/runs": {
      "post": {
        "operationId": "runs-sync-scraper_gump-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/scraper_gump~idealista-scraper/run-sync": {
      "post": {
        "operationId": "run-sync-scraper_gump-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",
        "required": [
          "country"
        ],
        "properties": {
          "location_prefix": {
            "title": "Search term",
            "type": "string",
            "description": "Type a city, neighbourhood or area name (e.g. \"madrid\", \"seville\", \"eixample\"). The scraper will return all matching Location IDs — copy the one you need into the Search section.\n\n⚠️ When this field is filled in, all other sections (Search, Fetch by Property ID) are ignored."
          },
          "operation": {
            "title": "Operation",
            "enum": [
              "sale",
              "rent"
            ],
            "type": "string",
            "description": "Are you looking to buy/sell or to rent?",
            "default": "rent"
          },
          "property_type": {
            "title": "Property Type",
            "enum": [
              "homes",
              "offices",
              "premises",
              "garages",
              "bedrooms",
              "lands",
              "storage-rooms",
              "buildings",
              "new-developments"
            ],
            "type": "string",
            "description": "The kind of property you want to search.",
            "default": "homes"
          },
          "country": {
            "title": "Country",
            "enum": [
              "es",
              "pt",
              "it"
            ],
            "type": "string",
            "description": "Idealista operates in Spain, Portugal and Italy. Make sure the Location ID matches the country you pick.",
            "default": "es"
          },
          "location_id": {
            "title": "Location ID",
            "type": "string",
            "description": "The internal Idealista code for the area you want to scrape. It always starts with 0-EU-.\n\n📍 Common Spanish locations:\n• Madrid city → 0-EU-ES-28-07-001-079\n• Madrid province → 0-EU-ES-28\n• Barcelona city → 0-EU-ES-08-13-001-019\n• Soria province → 0-EU-ES-42\n\n💡 To find any other ID: search your area on idealista.com and copy the code from the URL. It follows the 0-EU-XX-... pattern."
          },
          "enrich_details": {
            "title": "Fetch full details (photos, contact, energy)",
            "type": "boolean",
            "description": "When enabled, the scraper fetches the full property detail for each result — adding photos, contact info (phone, agent name), energy certification and remote visit availability.\n\n⚠️ This makes each run significantly slower and uses more proxy bandwidth (one extra request per listing). Disable if you only need basic listing data.",
            "default": true
          },
          "max_pages": {
            "title": "Max Pages",
            "minimum": 1,
            "maximum": 60,
            "type": "integer",
            "description": "Idealista caps results at 60 pages per search — that's up to 1,800 listings. Each page takes a few seconds, so a full 60-page run takes about 5 minutes.\n\n💡 To get more than 1,800 listings from a large city, run separate searches per district.",
            "default": 60
          },
          "max_items_per_page": {
            "title": "Items Per Page",
            "minimum": 1,
            "maximum": 40,
            "type": "integer",
            "description": "How many listings to request per page. Leave at 30 — changing this only makes the scraper less efficient without adding any benefit.",
            "default": 30
          },
          "order": {
            "title": "Sort By",
            "enum": [
              "publicationDate",
              "price",
              "size",
              "rooms",
              "weigh"
            ],
            "type": "string",
            "description": "Which field to sort results by.",
            "default": "publicationDate"
          },
          "sort": {
            "title": "Sort Direction",
            "enum": [
              "desc",
              "asc"
            ],
            "type": "string",
            "description": "Ascending or descending order.",
            "default": "desc"
          },
          "min_price": {
            "title": "Min Price (€)",
            "minimum": 0,
            "type": "integer",
            "description": "Only show properties at or above this price. Leave empty for no lower bound."
          },
          "max_price": {
            "title": "Max Price (€)",
            "minimum": 0,
            "type": "integer",
            "description": "Only show properties at or below this price. Leave empty for no upper bound."
          },
          "min_size": {
            "title": "Min Size (m²)",
            "minimum": 0,
            "type": "integer",
            "description": "Only show properties with at least this many square metres. Leave empty for no lower bound."
          },
          "max_size": {
            "title": "Max Size (m²)",
            "minimum": 0,
            "type": "integer",
            "description": "Only show properties up to this size. Leave empty for no upper bound."
          },
          "bedrooms": {
            "title": "Bedrooms",
            "minimum": 0,
            "type": "integer",
            "description": "Filter by exact number of bedrooms. Leave empty to include all."
          },
          "bathrooms": {
            "title": "Bathrooms",
            "minimum": 0,
            "type": "integer",
            "description": "Filter by exact number of bathrooms. Leave empty to include all."
          },
          "air_conditioning": {
            "title": "Air Conditioning",
            "type": "boolean",
            "description": "Only return properties that have air conditioning.",
            "default": false
          },
          "elevator": {
            "title": "Elevator",
            "type": "boolean",
            "description": "Only return properties in buildings with a lift.",
            "default": false
          },
          "terrace": {
            "title": "Terrace",
            "type": "boolean",
            "description": "Only return properties with a terrace.",
            "default": false
          },
          "pool": {
            "title": "Swimming Pool",
            "type": "boolean",
            "description": "Only return properties with a pool.",
            "default": false
          },
          "garage": {
            "title": "Garage",
            "type": "boolean",
            "description": "Only return properties with a garage.",
            "default": false
          },
          "garden": {
            "title": "Garden",
            "type": "boolean",
            "description": "Only return properties with a garden.",
            "default": false
          },
          "property_ids": {
            "title": "Property IDs",
            "type": "array",
            "description": "List of Idealista property IDs to fetch directly. When set, the Search section above is ignored — each ID is looked up individually via the detail endpoint.\n\nUseful for monitoring specific listings or fetching full details (including contact info and photos) after a search run.\n\nClosed listings return their deactivation reason and closing price.",
            "items": {
              "type": "string"
            }
          },
          "fetch_stats": {
            "title": "Include Run Stats",
            "type": "boolean",
            "description": "When enabled, a summary record is added at the end of the dataset with the total number of properties fetched, how many were active vs. closed, any errors, and total run time.",
            "default": true
          },
          "bearer_token": {
            "title": "Bearer Token (optional override)",
            "type": "string",
            "description": "The actor generates a fresh OAuth token automatically on each run. If token generation fails (Idealista occasionally tightens TLS requirements), paste a manually captured token here.\n\nTo capture one: run `./scraper_gump.sh --debug` on the local machine — it launches the Android emulator, opens the Idealista app, and saves the token to `.token`. Copy its contents here. Tokens expire after ~12 hours."
          }
        }
      },
      "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
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}