{
  "openapi": "3.0.1",
  "info": {
    "title": "PropertyFinder Scraper (UAE, Saudi, Qatar, Bahrain, Egypt)",
    "description": "Scrapes property listings from PropertyFinder across five Gulf and Egyptian markets. Each row carries price, area, bedrooms, address with GPS coordinates, property type, completion status, agent and agency, RERA permit data and photos. Search plus optional full listing details.",
    "version": "0.1",
    "x-build-id": "PQ7hP6Up00mqNAv8G"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/scrapyx~propertyfinder-properties-scraper/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-scrapyx-propertyfinder-properties-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/scrapyx~propertyfinder-properties-scraper/runs": {
      "post": {
        "operationId": "runs-sync-scrapyx-propertyfinder-properties-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/scrapyx~propertyfinder-properties-scraper/run-sync": {
      "post": {
        "operationId": "run-sync-scrapyx-propertyfinder-properties-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": {
          "country": {
            "title": "Market",
            "enum": [
              "ae",
              "sa",
              "qa",
              "bh",
              "eg"
            ],
            "type": "string",
            "description": "Which PropertyFinder market to scrape. All five run the same front end, so every option returns the same fields.\n\nTurkey (propertyfinder.com.tr) is **not** offered: it serves a different front end with no embedded data, so it cannot be read the same way.",
            "default": "ae"
          },
          "locations": {
            "title": "Locations",
            "type": "array",
            "description": "One city/region per entry, each producing its own SEARCH_SUMMARY row — e.g. `Dubai`, `Abu Dhabi`, `Cairo`, `Riyadh`. **Leave empty to scrape the whole market in one query.**\n\nNames are matched against the city breakdown PropertyFinder itself publishes for the chosen market, so only real ones are accepted. If a name is not found, the run reports the available cities rather than guessing.\n\nFor a smaller area than a city — a community like Business Bay, or a single tower — pass its **numeric location id** instead. Those ids are on every result row under `location.id` and `location_tree`, so one broad run tells you the ids for narrower follow-up runs.\n\nWhy this is strict: an id PropertyFinder cannot resolve is **not** an error upstream — it silently returns the entire country as though no filter were set.",
            "default": [],
            "items": {
              "type": "string"
            }
          },
          "category": {
            "title": "Listing category",
            "enum": [
              "buy",
              "rent",
              "commercial-buy",
              "commercial-rent"
            ],
            "type": "string",
            "description": "Which side of the market to scrape. Residential and commercial have **different property-type lists**, so choose this first.\n\n`New Projects` is deliberately absent — that surface returns developer project cards rather than individual listings, which is a different data shape.",
            "default": "buy"
          },
          "propertyType": {
            "title": "Property type",
            "type": "string",
            "description": "Restrict to one property type, e.g. `apartment`, `villa`, `townhouse`, `penthouse`, `compound`, `duplex`, `land`, `whole-building`. For commercial categories use `office-space`, `retail`, `warehouse`, `shop`, `show-room`, `factory`. Leave empty for all types.\n\nAccepts the slug, the display label, or the raw numeric id. The value is checked against the type list **that market and category publishes for itself** — the same numeric id means different things in different markets (id 22 is Townhouse in the UAE but Farm in Saudi Arabia), so nothing is hardcoded.\n\nAn unrecognised type is refused before the crawl starts, and the error lists what that market actually offers. This matters: PropertyFinder answers an unknown numeric type with HTTP 200 and a page containing zero real listings.",
            "default": ""
          },
          "bedrooms": {
            "title": "Bedrooms",
            "type": "array",
            "description": "Match any of the selected bedroom counts. `0` means studio. Leave empty for any.",
            "items": {
              "type": "string",
              "enum": [
                "0",
                "1",
                "2",
                "3",
                "4",
                "5",
                "6",
                "7",
                "8"
              ],
              "enumTitles": [
                "Studio",
                "1 bedroom",
                "2 bedrooms",
                "3 bedrooms",
                "4 bedrooms",
                "5 bedrooms",
                "6 bedrooms",
                "7 bedrooms",
                "8+ bedrooms"
              ]
            },
            "default": []
          },
          "minPrice": {
            "title": "Minimum price",
            "minimum": 0,
            "type": "integer",
            "description": "In the market's own currency (AED, SAR, QAR, BHD, EGP). Verified real: `5000000` narrowed the UAE apartment baseline from 123,441 to 10,416. Leave at 0 to skip.",
            "default": 0
          },
          "maxPrice": {
            "title": "Maximum price",
            "minimum": 0,
            "type": "integer",
            "description": "In the market's own currency. Verified real: `500000` narrowed the UAE apartment baseline from 123,441 to 5,766. Leave at 0 to skip.",
            "default": 0
          },
          "minArea": {
            "title": "Minimum area (sqft)",
            "minimum": 0,
            "type": "integer",
            "description": "Verified real: `2000` narrowed the UAE apartment baseline from 123,441 to 11,382. Leave at 0 to skip.",
            "default": 0
          },
          "maxArea": {
            "title": "Maximum area (sqft)",
            "minimum": 0,
            "type": "integer",
            "description": "Verified real: `800` narrowed the UAE apartment baseline from 123,441 to 44,955. Leave at 0 to skip.",
            "default": 0
          },
          "keywords": {
            "title": "Keywords",
            "type": "string",
            "description": "Free-text search across listing titles and descriptions, e.g. `marina`, `sea view`, `maid room`. Verified real, and honest about misses — nonsense text returns a genuine 0 rather than the unfiltered baseline.",
            "default": ""
          },
          "furnished": {
            "title": "Furnishing",
            "enum": [
              "",
              "furnished",
              "unfurnished",
              "partly-furnished"
            ],
            "type": "string",
            "description": "Leave empty for any. Note there is no separate 'any' value to send — omitting the filter is what 'any' means.",
            "default": ""
          },
          "completionStatus": {
            "title": "Completion status",
            "enum": [
              "",
              "completed",
              "off_plan"
            ],
            "type": "string",
            "description": "Ready (completed) or off-plan. Verified real: on the UAE apartment baseline of 123,441 these split 68,325 / 68,664.\n\nOnly these two are accepted. A plausible-looking third value such as `under_construction` is **silently ignored** by PropertyFinder — it returns the unfiltered total while echoing the value back — so it is refused here rather than reported as applied.",
            "default": ""
          },
          "listedWithin": {
            "title": "Listed within",
            "enum": [
              "0",
              "86400",
              "604800",
              "1296000",
              "2592000",
              "7776000"
            ],
            "type": "string",
            "description": "Only listings published inside this window. Verified real: 7 days narrowed the UAE apartment baseline from 123,441 to 17,815.\n\n(Carried as a string because the platform does not allow a dropdown on an integer field; the value is a number of seconds either way.)",
            "default": "0"
          },
          "sort": {
            "title": "Sort order",
            "enum": [
              "featured",
              "newest",
              "price-asc",
              "price-desc",
              "beds-asc",
              "beds-desc"
            ],
            "type": "string",
            "description": "All six were verified to genuinely reorder results (each returns a different first listing), not silently ignored.\n\nUse `Newest` when scraping repeatedly to track new stock — it puts fresh listings on page 1.",
            "default": "featured"
          },
          "includePropertyDetails": {
            "title": "Fetch full listing details",
            "type": "boolean",
            "description": "Fetch each listing's own page for fields the results list does not carry: the RERA/permit and property-detail tables, agent licence numbers, service fee per sqft, the untruncated description, project delivery date and payment plan, and rental availability date.\n\nCosts **one extra request per listing**, so leave it off for broad market sweeps and turn it on for a shortlist. Listings de-listed mid-run answer 404 — those rows are still returned, with `detailFetched: false`.",
            "default": false
          },
          "maxItems": {
            "title": "Max listings per location",
            "minimum": 0,
            "type": "integer",
            "description": "Stop after this many listings per location. Set to 0 for everything PropertyFinder will serve — which can be six thousand pages for a whole market, so prefer narrowing by city, type or price.",
            "default": 100
          },
          "maxConcurrency": {
            "title": "Max concurrent requests",
            "minimum": 1,
            "maximum": 12,
            "type": "integer",
            "description": "Upper bound on requests in flight at once, across all locations and detail fetches.",
            "default": 4
          },
          "minRequestInterval": {
            "title": "Minimum seconds between requests",
            "minimum": 0,
            "maximum": 30,
            "type": "integer",
            "description": "Paces how often requests START, without tying up a concurrency slot. PropertyFinder showed no rate limiting in testing, so this defaults to 0; raise it if you run long unattended crawls.",
            "default": 0
          },
          "proxyConfiguration": {
            "title": "Proxy configuration",
            "type": "object",
            "description": "Residential by default. PropertyFinder showed no bot challenge on any of the 8 TLS fingerprints tested across search and detail pages, but datacentre egress from a cloud platform is fingerprinted differently from a local test — an earlier actor in this portfolio lost every request that way — so residential is the safe default.",
            "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
                  }
                }
              },
              "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
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}