{
  "openapi": "3.0.1",
  "info": {
    "title": "Fotocasa Scraper $0.95/1K — Spain Real Estate Data & Agencies",
    "description": "Scrape Fotocasa.es property listings for sale and rent across Spain: price, surface, GPS, the full 8-level location hierarchy with IDs, photos tagged by room, and the listing agency with its phone. Median 45 of 78 fields filled. Energy certificates and street via detail pages. No login.",
    "version": "0.1",
    "x-build-id": "BBgfU0wHrhXLGfVJV"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/oswaldocarabano~fotocasa-scraper/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-oswaldocarabano-fotocasa-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/oswaldocarabano~fotocasa-scraper/runs": {
      "post": {
        "operationId": "runs-sync-oswaldocarabano-fotocasa-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/oswaldocarabano~fotocasa-scraper/run-sync": {
      "post": {
        "operationId": "run-sync-oswaldocarabano-fotocasa-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": [
          "location",
          "maxItems"
        ],
        "properties": {
          "location": {
            "title": "Location",
            "type": "string",
            "description": "fotocasa location ID (combinedLocationIds). Defaults to all of Spain. Every response carries the child locations of whatever you ask for, so the actor walks the tree for you: country → province → comarca → municipality → district → neighbourhood. Examples: Spain 724,0,0,0,0,0,0,0,0 · Madrid city 724,14,28,173,0,28079,0,0,0 · Barcelona province 724,9,8,0,0,0,0,0,0 · Malaga province 724,1,29,0,0,0,0,0,0.",
            "default": "724,0,0,0,0,0,0,0,0"
          },
          "transactionType": {
            "title": "Operation",
            "enum": [
              "sale",
              "rent"
            ],
            "type": "string",
            "description": "Buy or rent. New-build (transactionTypeId 4) is not offered because it returns zero results against the live API.",
            "default": "sale"
          },
          "propertyType": {
            "title": "Property type",
            "enum": [
              "home",
              "commercial",
              "land",
              "garage",
              "storage"
            ],
            "type": "string",
            "description": "Counts measured against the live API on 18 Sep 2026.",
            "default": "home"
          },
          "sortBy": {
            "title": "Sort by",
            "enum": [
              "relevance",
              "price",
              "newest",
              "surface",
              "rooms"
            ],
            "type": "string",
            "description": "Only the sort values that were verified to change the result against the live API. fotocasa silently ignores sort values it does not know and returns the default order, so unverified options are not offered here.",
            "default": "relevance"
          },
          "sortDescending": {
            "title": "Sort descending",
            "type": "boolean",
            "description": "Descending by default. With sortBy = price, turn this off for cheapest first — verified to actually reverse the order against the live API.",
            "default": true
          },
          "minPrice": {
            "title": "Minimum price (EUR)",
            "minimum": 0,
            "type": "integer",
            "description": "Only listings priced at or above this. Verified against the live API: it moves the count from 470,340 to 302,763 nationwide."
          },
          "maxPrice": {
            "title": "Maximum price (EUR)",
            "minimum": 0,
            "type": "integer",
            "description": "Only listings priced at or below this. Verified against the live API."
          },
          "minRooms": {
            "title": "Minimum rooms",
            "minimum": 0,
            "type": "integer",
            "description": "Only listings with at least this many rooms. Verified against the live API."
          },
          "minSurface": {
            "title": "Minimum surface (m²)",
            "minimum": 0,
            "type": "integer",
            "description": "Only listings of at least this many square metres. Verified against the live API."
          },
          "maxSurface": {
            "title": "Maximum surface (m²)",
            "minimum": 0,
            "type": "integer",
            "description": "Only listings of at most this many square metres. Verified against the live API."
          },
          "maxItems": {
            "title": "Maximum listings",
            "minimum": 1,
            "maximum": 50000,
            "type": "integer",
            "description": "Hard cap for this run. There is no download-everything mode: the Spanish sale inventory alone is roughly 470,000 listings, and extracting a substantial part of a database is what the EU sui generis database right protects against.",
            "default": 1000
          },
          "scrapeDetails": {
            "title": "Also scrape the detail page",
            "type": "boolean",
            "description": "Adds street name and number, energy certificate, creation date, construction type, plot surface and quality score — 78 fields that only exist on the listing page. Costs 65x more bandwidth per listing than the search API, so it is billed as a separate event and is off by default.",
            "default": false
          },
          "includeAgencies": {
            "title": "Also build an agency dataset",
            "type": "boolean",
            "description": "Writes a separate `agencies` dataset with name, phone, logo and profile URL of every professional agency found. Costs zero extra requests: the data is already in the search response. Private advertisers are never included.",
            "default": false
          },
          "respectRobotsTxt": {
            "title": "Respect robots.txt on the website",
            "type": "boolean",
            "description": "Off by default, so detail pages are fetched for every listing. Turn it on to have the actor honour fotocasa's robots.txt on the website host, which skips detail pages for some locations. This has no effect on listings: the search API is a different host that publishes no robots.txt.",
            "default": false
          },
          "maxCacheAgeDays": {
            "title": "Maximum cache age (days)",
            "minimum": 0,
            "maximum": 30,
            "type": "integer",
            "description": "Serve from cache when the stored copy is younger than this. 0 always fetches fresh. Every row declares from_cache, fetched_at and data_age_hours so you always know how old the data is.",
            "default": 7
          },
          "maxConcurrency": {
            "title": "Maximum concurrency",
            "minimum": 1,
            "maximum": 10,
            "type": "integer",
            "description": "Kept low on purpose. The API answered 24 parallel requests without a single non-200, but starting below a known ceiling rather than at it is what keeps a scraper working next month.",
            "default": 5
          },
          "proxyConfiguration": {
            "title": "Proxy",
            "type": "object",
            "description": "Optional. The actor reaches fotocasa fine without a proxy and falls back to a Spanish residential IP automatically if it ever starts getting blocked.",
            "default": {
              "useApifyProxy": 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
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}