# Gathern Scraper β€” Saudi Vacation Rentals Data & API (`sian.agency/gathern-property-scraper`) Actor Gathern scraper & short-term-rental data API for Saudi Arabia's leading vacation-rental marketplace. Chalets, istraha, apartments, resorts & camps across Riyadh, Jeddah, Dammam & more: nightly price (SAR), capacity, beds, rating & reviews, amenities, GPS, photos β€” clean JSON/CSV. No API key needed. - **URL**: https://apify.com/sian.agency/gathern-property-scraper.md - **Developed by:** [SIÁN OÜ](https://apify.com/sian.agency) (community) - **Categories:** Real estate, Automation, Travel - **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks - **User rating**: No ratings yet ## Pricing from $2.90 / 1,000 rental units This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events. Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have. Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event ## What's an Apify Actor? Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases. In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours, and optionally produces a well-defined JSON output, datasets with results, or files in key-value store. In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server. Actors are written with capital "A". ## How to integrate an Actor? If asked about integration, you help developers integrate Actors into their projects. You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready. The best way to integrate Actors is as follows. In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js.md): ```bash npm install apify-client ``` In Python projects, use official [Python client library](https://docs.apify.com/api/client/python.md): ```bash pip install apify-client ``` In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md): ````bash # MacOS / Linux curl -fsSL https://apify.com/install-cli.sh | bash # Windows irm https://apify.com/install-cli.ps1 | iex ```bash In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/platform/integrations/mcp.md). If your project is in a different language, use the [REST API](https://docs.apify.com/api/v2.md). For usage examples, see the [API](#api) section below. For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt). # README ## Gathern Scraper πŸ‡ΈπŸ‡¦ β€” Saudi Vacation Rentals Data & API πŸ–οΈ [![SIÁN Agency Store](https://img.shields.io/badge/Store-SI%C3%81N%20Agency-1AE392)](https://apify.com/sian.agency?fpr=sian) [![Bayut Scraper](https://img.shields.io/badge/Store-Bayut%20Scraper-1AE392)](https://apify.com/sian.agency/bayut-property-scraper?fpr=sian) [![Dubizzle Scraper](https://img.shields.io/badge/Store-Dubizzle%20Scraper-1AE392)](https://apify.com/sian.agency/dubizzle-property-scraper?fpr=sian) [![MENA Property Gateway](https://img.shields.io/badge/Store-MENA%20Property%20Gateway-00A933)](https://apify.com/sian.agency/mena-property-gateway?fpr=sian) #### πŸŽ‰ Turn Gathern listings into clean structured data β€” Saudi vacation rentals, every city, no API key ##### Built for STR analysts, proptech teams, travel-tech startups and investors who need Saudi short-term-rental data at scale --- ### πŸ“‹ Overview **Scrape Gathern β€” Saudi Arabia's leading short-term & vacation-rental marketplace β€” into ready-to-use datasets.** Pull thousands of rental units with nightly price (SAR), guest capacity, beds, rating and reviews, amenities, district, GPS coordinates and the full photo gallery β€” as JSON, CSV or Excel. **Why STR analysts and travel-tech teams choose us:** - βœ… **Complete units**: up to 56 fields per rental β€” nightly + total price, service/VAT split, capacity, beds, area, rating, reviews, amenities, GPS, district, photos - ⚑ **Fast & affordable**: harvest whole-city inventory in seconds β€” the cheapest way to gather Saudi vacation-rental data at volume - 🏝️ **Every unit type**: chalets, istraha (rest houses), serviced apartments, resorts, camps, farms β€” filter to exactly what you need - πŸ‡ΈπŸ‡¦ **Bilingual by default**: city, district and unit-type names in both **Arabic and English** on every row - πŸ“… **Date-aware pricing**: set check-in / check-out and get nightly price and availability for those exact nights - πŸ’Έ **Pay-per-result**: only pay for units you actually extract β€” generous FREE tier, no credit card to start - ✨ **Investor KPIs built in**: automatic price-per-guest (SAR) and a thumbnail-first row for instant gallery views --- ### ✨ Features - πŸ–οΈ **Saudi short-term rentals**: chalets, istraha, serviced apartments, resorts and camps in one actor - πŸ™οΈ **Search by city or URL**: type a Saudi city name, or paste a gathern.co search URL - πŸ’΅ **Full nightly pricing**: nightly price, averaged price, pre-discount price, service + VAT, total with services (SAR) - πŸ‘₯ **Capacity & specs**: max guests, bedrooms, master & single beds, bathrooms, area (mΒ²) - ⭐ **Ratings & demand**: 0–10 guest rating, review count, booking count, view count - 🧭 **Geo data**: city, district and neighbourhood (Arabic + English), latitude & longitude - πŸ—“οΈ **Availability**: free-cancellation, insurance and instant-book flags; check-in / check-out for the searched dates - πŸ“Έ **Full photo gallery**: every unit image URL, plus a cover thumbnail - πŸ—οΈ **Amenities & features**: amenity titles and feature chips per unit - πŸ“Š **Computed KPIs**: price-per-guest in SAR, ready for yield and rate models - πŸ“€ **Clean exports**: JSON, CSV and Excel directly from the dataset --- ### 🎬 Quick Start Tell it where to look (a Saudi city name or a search URL), optionally pick a unit type and dates, and run. Results stream into your dataset as clean rows you can export to JSON, CSV or Excel. ```bash curl -X POST https://api.apify.com/v2/acts/sian.agency~gathern-property-scraper/runs?token=YOUR_TOKEN \ -H 'Content-Type: application/json' \ -d '{"searchMode":"byCity","cities":["Riyadh"],"maxResults":100}' ```` *** ### πŸš€ Getting Started (3 Simple Steps) #### Step 1: Choose how to search Search **by city** (type Saudi city names like `Riyadh`, `Jeddah`, `Dammam`) or **by search URL** (paste a gathern.co search-results link). #### Step 2: Narrow it down (optional) Pick a unit type (chalet, istraha, apartment, resort, camp…), set check-in / check-out dates, choose a language and sort order. #### Step 3: Run it Click **Start** (or call the API). Rental units stream into your dataset in real time. **That's it! In under a minute, you'll have:** - A clean table of Saudi rental units with nightly prices and specs - Capacity, rating, GPS, district and the full amenity & photo list - A JSON / CSV / Excel export ready for your model or app *** ### πŸ“₯ Input Configuration | Field | Type | Required | Description | |-------|------|----------|-------------| | searchMode | string | No | `byCity` or `bySearchUrl`. Default `byCity`. | | cities | array | No | Saudi city names (English or Arabic), e.g. `Riyadh`, `Jeddah`, `Ψ§Ω„Ψ±ΩŠΨ§ΨΆ`. | | unitType | string | No | `resort`, `chalet`, `istraha`, `apartment`, `camp`, `farm`, `hotel`, `serviced-apartment`. | | checkIn / checkOut | string | No | `YYYY-MM-DD` dates β€” nightly price & availability for those nights. | | lang | string | No | `en` or `ar`. Default `en`. | | sort | string | No | `points`, `price`, `rate`, `newest`. Default `points`. | | searchUrls | array | No | gathern.co search-results URLs. | | maxResults | integer | No | Cap units per run. FREE: 25. PAID: unlimited. | | maxPages | integer | No | Max search pages per city (10 units each). Default 20. | | proxyCountry | string | No | Empty = direct (default). `SA` routes through a Saudi residential proxy for very large runs. | **Example β€” by city:** ```json { "searchMode": "byCity", "cities": ["Riyadh", "Jeddah"], "unitType": "chalet", "checkIn": "2026-07-01", "checkOut": "2026-07-03", "sort": "rate", "maxResults": 200 } ``` **Example β€” by search URL:** ```json { "searchMode": "bySearchUrl", "searchUrls": ["https://gathern.co/search?city=3&chalet_cats[]=2"] } ``` *** ### πŸ“€ Output Results are saved to the Apify dataset with **56 fields** including: | Field | Type | Description | |-------|------|-------------| | listingId | integer | Gathern rental-unit identifier | | url | string | Canonical unit URL | | propertyTitle | string | Unit title | | unit\_type / unit\_type\_ar | string | Unit type (Apartment, Chalet, Istraha, Resort, Camp…) β€” English & Arabic | | nightly\_price | number | Nightly price (SAR) for the searched dates | | total\_price\_with\_services | number | Total nightly price incl. service + VAT | | price\_per\_guest\_sar | integer | Computed nightly price per max guest | | capacity / bedrooms / bathrooms | integer | Guest capacity & specs | | area\_sqm | integer | Unit area (mΒ²) | | rating / reviews\_count | number | Guest rating (0–10) & review count | | city / city\_ar / district / district\_ar | string | Location (English & Arabic) | | latitude / longitude | number | GPS coordinates | | amenities / features | array | Amenity titles & feature chips | | photos | array | Full-resolution image URLs | | thumbnail / cover\_photo | string | Cover image | **Example:** ```json { "listingId": 253489, "url": "https://gathern.co/view/181254/unit/253489", "propertyTitle": "Apartment with Living Room", "unit_type": "Apartment", "unit_type_ar": "Ψ΄Ω‚Ψ©", "currency": "SAR", "nightly_price": 449, "total_price_with_services": 565.74, "price_per_guest_sar": null, "bedrooms": 1, "bathrooms": 1, "area_sqm": 55, "rating": 10, "reviews_count": 2, "city": "Riyadh", "city_ar": "Ψ§Ω„Ψ±ΩŠΨ§ΨΆ", "district": "Al Aqeeq Dist.", "latitude": 24.77993, "longitude": 46.62418, "amenities": ["55", "1", "1"], "photo_count": 6, "thumbnail": "https://img.gathern.co/1400x0/1/v0KR43VcfAaQREyLXBzC9nuSLsj7d2M_.jpg" } ``` *** ### πŸ’Ό Use Cases & Examples #### 1. Short-Term-Rental Yield & Revenue Models **STR investors and analysts modelling Saudi vacation-rental returns.** **Input:** A list of city names and a unit type. **Output:** Nightly price, capacity, rating and computed SAR-per-guest per unit. **Use:** Build nightly-rate, occupancy-proxy and revenue models across Saudi cities. #### 2. Nightly-Rate Comparables **Hosts and revenue managers pricing their own units.** **Input:** A search URL for a city and unit type. **Output:** Comparable units with nightly price, rating and amenities. **Use:** Set competitive rates against live local supply. #### 3. Travel-Tech & Booking Apps **Travel startups building Saudi vacation-rental products.** **Input:** Programmatic API calls per city. **Output:** Structured JSON with prices, geo and media ready to ingest. **Use:** Back a search or comparison app with live Saudi rental data. #### 4. Market Research & Tourism Dashboards **Data teams tracking Saudi Arabia's Vision-2030 tourism boom.** **Input:** Scheduled daily runs across multiple cities. **Output:** A time series of nightly rates, inventory and ratings. **Use:** Power BI / Looker dashboards on supply, pricing and demand. #### 5. Amenity & Rating Analysis **Proptech and hospitality teams benchmarking quality.** **Input:** By-city searches with sort by rating. **Output:** Units with amenity lists, ratings and review counts. **Use:** Find what amenities correlate with higher rates and ratings. #### 6. Powering a Saudi Rental Data API **Companies needing a live feed of Saudi short-term-rental supply.** **Input:** Programmatic API calls per region. **Output:** Clean structured JSON ready to serve. **Use:** Back a valuation or availability API with current Gathern data. *** ### πŸ”— Integration Examples #### JavaScript/Node.js ```javascript import { ApifyClient } from 'apify-client'; const client = new ApifyClient({ token: 'YOUR_TOKEN' }); const run = await client.actor('sian.agency/gathern-property-scraper').call({ searchMode: 'byCity', cities: ['Riyadh'], maxResults: 100, }); const { items } = await client.dataset(run.defaultDatasetId).listItems(); console.log(items[0]); ``` #### Python ```python from apify_client import ApifyClient client = ApifyClient('YOUR_TOKEN') run = client.actor('sian.agency/gathern-property-scraper').call( run_input={ 'searchMode': 'byCity', 'cities': ['Riyadh'], 'maxResults': 100, } ) for item in client.dataset(run['defaultDatasetId']).iterate_items(): print(item) ``` #### cURL ```bash curl -X POST 'https://api.apify.com/v2/acts/sian.agency~gathern-property-scraper/runs?token=YOUR_TOKEN' \ -H 'Content-Type: application/json' \ -d '{"searchMode":"byCity","cities":["Riyadh"],"maxResults":100}' ``` #### Automation Workflows (N8N / Zapier / Make) 1. **Trigger**: Schedule (e.g. daily) or webhook 2. **HTTP Request**: Call the actor API 3. **Process**: Handle the JSON results 4. **Action**: Save to a sheet, push to a dashboard, or send an alert *** ### πŸ“Š Performance & Pricing #### FREE Tier (Try It Now) - **25 units** per run β€” full feature access, same data quality - No credit card required - Perfect for testing and small projects #### PAID Tier (Production Ready) - **Unlimited** units per run - Pay-per-result: only charged for units successfully extracted - Ideal for dashboards, comparables and data APIs πŸ’° **Transparent pay-per-result pricing** β€” harvest Saudi vacation-rental data at volume and only pay for the units you actually extract. πŸ”— [View current pricing](https://apify.com/sian.agency/gathern-property-scraper?fpr=sian) *** ### ❓ Frequently Asked Questions **Q: How many units can I extract?** A: FREE tier: 25 per run. PAID tier: unlimited. **Q: What unit types are covered?** A: Chalets, istraha (rest houses), serviced apartments, resorts, camps, farms, hotels β€” filter with `unitType`, or leave it empty for all. **Q: Can I get prices for specific dates?** A: Yes β€” set `checkIn` and `checkOut` (YYYY-MM-DD) and nightly price and availability reflect those nights. **Q: Does it support Arabic?** A: Yes β€” set `lang` to `ar` for Arabic geo/type names. Both Arabic and English location fields are always populated. **Q: What output formats are available?** A: JSON, CSV and Excel β€” export directly from the Apify dataset. **Q: Do I need a Gathern account or API key?** A: No. The actor works straight out of the box. **Q: What currency are prices in?** A: Saudi Riyal (SAR), as published on Gathern. **Q: Is this legal?** A: We only extract publicly available listing data. See the legal note below. *** ### πŸ› Troubleshooting **No results returned** - Check your city name β€” try the common English spelling (`Riyadh`, `Jeddah`, `Dammam`) or the Arabic name. - If you set check-in / check-out, make sure units are actually available for those dates. **Fewer rows than expected** - Each search page returns 10 units. Add more cities or raise Max pages to gather more units. - A single city query is capped by the marketplace at a few thousand units β€” add a unit-type filter or date band to slice deeper. **Large runs slowing down** - Set `proxyCountry` to `SA` to route through a Saudi residential proxy and avoid IP rate-limits at scale. *** ### βš–οΈ Is it legal to scrape data? Our actors are ethical and do not extract any private user data, such as email addresses, gender, or location. They only extract what the user has chosen to share publicly. We therefore believe that our actors, when used for ethical purposes by Apify users, are safe. However, you should be aware that your results could contain personal data. Personal data is protected by the **GDPR** in the European Union and by other regulations around the world. You should not scrape personal data unless you have a legitimate reason to do so. If you're unsure whether your reason is legitimate, consult your lawyers. You can also read Apify's blog post on the [legality of web scraping](https://blog.apify.com/is-web-scraping-legal/). > **Disclaimer:** This actor is an independent tool and is not affiliated with, endorsed by, or sponsored by Gathern. "Gathern" and related marks are trademarks of their respective owners. Use this actor in compliance with Gathern's terms and all applicable laws. *** ### 🀝 Support [![Telegram Support](https://img.shields.io/badge/Telegram-Support%20Group-0088cc?logo=telegram)](https://t.me/+vyh1sRE08sAxMGRi) **Join our active support community** - For issues or questions, open an issue in the actor's repository - Check the [SIÁN Agency Store](https://apify.com/sian.agency?fpr=sian) for more automation tools - πŸ“§ *** **Built by [SIÁN Agency](https://www.sian-agency.online)** | **[More Tools](https://apify.com/sian.agency?fpr=sian)** # Actor input Schema ## `searchMode` (type: `string`): 🧭 How to tell the scraper what to fetch: - **By city** β€” type one or more Saudi city names (e.g. "Riyadh", "Jeddah", "Dammam"). Combine with the unit type, dates, language and sort below. - **By search URL** β€” paste a gathern.co search-results URL; its city, unit type, dates and ordering are honored. ## `cities` (type: `array`): πŸ™οΈ Saudi city names (English or Arabic), e.g. "Riyadh", "Jeddah", "Dammam", "AlUla", "Ψ§Ω„Ψ±ΩŠΨ§ΨΆ". Used when **Search by = By city**. **TIP:** Add several β€” each city is searched in turn until **Max results** is reached. City names are resolved automatically. ## `unitType` (type: `string`): 🏠 Filter by rental unit type. Leave empty for all types. Applies to By city searches. ## `checkIn` (type: `string`): πŸ“… Check-in date (YYYY-MM-DD). When set with Check-out, prices and availability reflect those nights. Applies to By city searches. ## `checkOut` (type: `string`): πŸ“… Check-out date (YYYY-MM-DD). Applies to By city searches. ## `lang` (type: `string`): 🌐 Response language. English returns Latin-script city/district/type names; Arabic returns the native names (both Arabic and English geo fields are always populated). ## `sort` (type: `string`): ↕️ Order the search results. Applies to By city searches. ## `searchUrls` (type: `array`): πŸ”— gathern.co search-results URLs to scrape. Used when **Search by = By search URL**. **TIP:** Build any search on gathern.co (pick the city, unit type, dates, ordering), then copy the URL from the address bar. **BULK EDIT:** Click "Bulk edit" to paste many URLs, one per line. ## `maxResults` (type: `integer`): πŸ”’ Maximum rental units to extract this run. - **FREE tier:** capped at 25 units per run. - **PAID tier:** unlimited β€” set as high as you need. ## `maxPages` (type: `integer`): πŸ“„ Maximum search pages to fetch per city (10 units each). Caps very large By city runs. ## `proxyCountry` (type: `string`): 🌐 Leave empty to run **direct** (no proxy β€” the default, fastest & cheapest). Set to "SA" to route through a Saudi residential proxy, only needed to dodge an IP rate-limit on very large runs. ## Actor input object example ```json { "searchMode": "byCity", "cities": [ "Riyadh", "Jeddah" ], "unitType": "", "checkIn": "2026-07-01", "checkOut": "2026-07-03", "lang": "en", "sort": "points", "searchUrls": [ "https://gathern.co/search?city=3&chalet_cats[]=2" ], "maxResults": 100, "maxPages": 20, "proxyCountry": "" } ``` # Actor output Schema ## `results` (type: `string`): Clean structured Gathern rental units (JSON/CSV/Excel). # API You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup. ## JavaScript example ```javascript import { ApifyClient } from 'apify-client'; // Initialize the ApifyClient with your Apify API token // Replace the '' with your token const client = new ApifyClient({ token: '', }); // Prepare Actor input const input = { "cities": [ "Riyadh" ] }; // Run the Actor and wait for it to finish const run = await client.actor("sian.agency/gathern-property-scraper").call(input); // Fetch and print Actor results from the run's dataset (if any) console.log('Results from dataset'); console.log(`πŸ’Ύ Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`); const { items } = await client.dataset(run.defaultDatasetId).listItems(); items.forEach((item) => { console.dir(item); }); // πŸ“š Want to learn more πŸ“–? Go to β†’ https://docs.apify.com/api/client/js/docs ``` ## Python example ```python from apify_client import ApifyClient # Initialize the ApifyClient with your Apify API token # Replace '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = { "cities": ["Riyadh"] } # Run the Actor and wait for it to finish run = client.actor("sian.agency/gathern-property-scraper").call(run_input=run_input) # Fetch and print Actor results from the run's dataset (if there are any) print("πŸ’Ύ Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"]) for item in client.dataset(run["defaultDatasetId"]).iterate_items(): print(item) # πŸ“š Want to learn more πŸ“–? Go to β†’ https://docs.apify.com/api/client/python/docs/quick-start ``` ## CLI example ```bash echo '{ "cities": [ "Riyadh" ] }' | apify call sian.agency/gathern-property-scraper --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=sian.agency/gathern-property-scraper", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "Gathern Scraper β€” Saudi Vacation Rentals Data & API", "description": "Gathern scraper & short-term-rental data API for Saudi Arabia's leading vacation-rental marketplace. Chalets, istraha, apartments, resorts & camps across Riyadh, Jeddah, Dammam & more: nightly price (SAR), capacity, beds, rating & reviews, amenities, GPS, photos β€” clean JSON/CSV. No API key needed.", "version": "1.0", "x-build-id": "jfZixqO4QUgJ7u1d5" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/sian.agency~gathern-property-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-sian.agency-gathern-property-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/sian.agency~gathern-property-scraper/runs": { "post": { "operationId": "runs-sync-sian.agency-gathern-property-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/sian.agency~gathern-property-scraper/run-sync": { "post": { "operationId": "run-sync-sian.agency-gathern-property-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": { "searchMode": { "title": "🧭 Search by", "enum": [ "byCity", "bySearchUrl" ], "type": "string", "description": "🧭 How to tell the scraper what to fetch:\n\n- **By city** β€” type one or more Saudi city names (e.g. \"Riyadh\", \"Jeddah\", \"Dammam\"). Combine with the unit type, dates, language and sort below.\n- **By search URL** β€” paste a gathern.co search-results URL; its city, unit type, dates and ordering are honored.", "default": "byCity" }, "cities": { "title": "πŸ™οΈ Cities", "type": "array", "description": "πŸ™οΈ Saudi city names (English or Arabic), e.g. \"Riyadh\", \"Jeddah\", \"Dammam\", \"AlUla\", \"Ψ§Ω„Ψ±ΩŠΨ§ΨΆ\". Used when **Search by = By city**.\n\n**TIP:** Add several β€” each city is searched in turn until **Max results** is reached. City names are resolved automatically.", "items": { "type": "string" } }, "unitType": { "title": "🏠 Unit type (optional)", "enum": [ "", "resort", "chalet", "istraha", "apartment", "camp", "farm", "hotel", "serviced-apartment" ], "type": "string", "description": "🏠 Filter by rental unit type. Leave empty for all types. Applies to By city searches.", "default": "" }, "checkIn": { "title": "πŸ“… Check-in (optional)", "type": "string", "description": "πŸ“… Check-in date (YYYY-MM-DD). When set with Check-out, prices and availability reflect those nights. Applies to By city searches." }, "checkOut": { "title": "πŸ“… Check-out (optional)", "type": "string", "description": "πŸ“… Check-out date (YYYY-MM-DD). Applies to By city searches." }, "lang": { "title": "🌐 Language", "enum": [ "en", "ar" ], "type": "string", "description": "🌐 Response language. English returns Latin-script city/district/type names; Arabic returns the native names (both Arabic and English geo fields are always populated).", "default": "en" }, "sort": { "title": "↕️ Sort order (optional)", "enum": [ "points", "price", "rate", "newest" ], "type": "string", "description": "↕️ Order the search results. Applies to By city searches.", "default": "points" }, "searchUrls": { "title": "πŸ”— Search URLs", "type": "array", "description": "πŸ”— gathern.co search-results URLs to scrape. Used when **Search by = By search URL**.\n\n**TIP:** Build any search on gathern.co (pick the city, unit type, dates, ordering), then copy the URL from the address bar.\n\n**BULK EDIT:** Click \"Bulk edit\" to paste many URLs, one per line.", "items": { "type": "string" } }, "maxResults": { "title": "πŸ”’ Max results", "minimum": 1, "type": "integer", "description": "πŸ”’ Maximum rental units to extract this run.\n\n- **FREE tier:** capped at 25 units per run.\n- **PAID tier:** unlimited β€” set as high as you need.", "default": 100 }, "maxPages": { "title": "πŸ“„ Max pages per city", "minimum": 1, "type": "integer", "description": "πŸ“„ Maximum search pages to fetch per city (10 units each). Caps very large By city runs.", "default": 20 }, "proxyCountry": { "title": "🌐 Proxy country (optional)", "enum": [ "", "SA" ], "type": "string", "description": "🌐 Leave empty to run **direct** (no proxy β€” the default, fastest & cheapest). Set to \"SA\" to route through a Saudi residential proxy, only needed to dodge an IP rate-limit on very large runs.", "default": "" } } }, "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 } } } } } } } } } } ```