# Aqar Scraper — Saudi Arabia Property Data & API (`sian.agency/aqar-property-scraper`) Actor Aqar scraper & real estate data API for Saudi Arabia's #1 property portal (sa.aqar.fm). Sale & rent listings across every Saudi city: price, price/m², beds, baths, area, GPS, photos, advertiser, FAL license & deed number — clean JSON/CSV. - **URL**: https://apify.com/sian.agency/aqar-property-scraper.md - **Developed by:** [SIÁN OÜ](https://apify.com/sian.agency) (community) - **Categories:** Real estate, Automation, Lead generation - **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks - **User rating**: No ratings yet ## Pricing from $2.00 / 1,000 overview listings 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 ## Aqar Scraper — Saudi Arabia Real Estate 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 Property Scraper](https://img.shields.io/badge/Store-Bayut%20Property%20Scraper-93D500)](https://apify.com/sian.agency/bayut-property-scraper?fpr=sian) [![Property Finder Scraper](https://img.shields.io/badge/Store-Property%20Finder%20Scraper-1AE392)](https://apify.com/sian.agency/propertyfinder-property-scraper?fpr=sian) [![Zillow Property Scraper](https://img.shields.io/badge/Store-Zillow%20Property%20Scraper-1F4E79)](https://apify.com/sian.agency/zillow-property-scraper?fpr=sian) #### 🎉 The fast, no-code Aqar data API — Saudi property data with FAL license & REGA deed compliance fields, no Aqar account or API key required ##### Built for property investors, agencies, proptech teams, and market researchers who need clean Saudi real-estate data — for sale and for rent — across Riyadh, Jeddah, Dammam, Mecca, Medina and every Saudi city. ### 📋 Overview **Pull listings from Aqar — Saudi Arabia's leading real-estate portal — as clean JSON, CSV or Excel.** For sale and for rent, apartments, villas, land, houses, offices, farms and more, across Riyadh, Jeddah, Dammam, Khobar, Mecca, Medina and every market Aqar covers. Pick the depth that fits the job: a fast, low-cost Overview scan to size a market, or the full per-listing Detail record. **Why investors and agencies choose us:** - ⚡ **Two depths, one actor**: a fast Overview scan for whole-market sweeps, or full Detail records by listing ID - 🌍 **Every Saudi city**: search by city name (Arabic or English) or city ID — Riyadh, Jeddah, Dammam, Mecca, Medina and beyond - 📐 **Analysis-ready**: price, area (m²), beds, baths, **price-per-m²** and **GPS coordinates** on every row for instant investment math - 🛡️ **Saudi compliance data built in**: FAL advertising license, REGA title-deed number, off-plan license and REGA verification flags for due diligence - 📞 **Advertiser on every row**: advertiser name, agency, type (owner / agency) and REGA ID for instant lead lists - 💎 **No API key, no code**: no Aqar account or API access needed — point, click, export a real-estate data feed - 🆓 **Free to try**: scrape listings with no credit card ### ✨ Features - 🧭 **Overview mode**: bulk listings — price, area, rooms, location, advertiser, photos, FAL license, deed — ideal for fast market sweeps - 🔍 **Detail mode**: fetch full records for specific listings by Aqar listing ID - 🏷️ **All property types & deals**: apartment, villa, land, house, building, office, store, farm, chalet, room, floor — for sale or for rent - 🎚️ **Rich filters**: city, district, price range, area range, bedrooms, living rooms, bathrooms, furnishing, sort field & direction - 📐 **Price-per-m² + thumbnail** computed on every row for instant comparison - 📍 **GPS + full location** on every listing for mapping and territory analysis - 🪪 **FAL & deed compliance**: FAL advertising-license number, REGA deed number, off-plan license and verification flags - 📤 **Clean exports**: JSON, CSV, Excel, or the full REST API ### 🎬 Quick Start Pick a scrape depth, choose a category and city, set filters, and run. Results stream to the Apify dataset as clean JSON/CSV. ```bash curl -X POST "https://api.apify.com/v2/acts/sian.agency~aqar-property-scraper/runs?token=[YOUR_TOKEN]" \ -H 'Content-Type: application/json' \ -d '{"scrapeMode":"overview","category":"6","city":"Riyadh","maxResults":50}' ```` ### 🚀 Getting Started (3 Simple Steps) #### Step 1: Pick your scrape depth **Overview** for a fast price + spec scan, or **Detail** for the full per-listing record by listing ID. #### Step 2: Choose your category & city Set the **category** (e.g. `6` = Apartment for sale, `1` = Apartment for rent, `3` = Villa for sale) — or leave it blank and use **propertyType** + **deal**. Add a **city** (`Riyadh`, `Jeddah`, …). For Detail, you can also drop specific **listingIds**. #### Step 3: Set filters & run Price range, area range, bedrooms, bathrooms, furnishing, sort, Max results — then hit **Start**. **That's it! In under a minute, you'll have:** - A clean dataset of Saudi property listings (JSON / CSV / Excel) - Price, area, beds, baths, GPS, advertiser, FAL license and price-per-m² on every row - A repeatable, no-code real-estate data feed across Saudi Arabia ### 📥 Input Configuration | Field | Type | Required | Description | |-------|------|----------|-------------| | scrapeMode | string | No | `overview` (fast & cheap) or `detail` (full record by ID). Default `overview`. | | category | string | No | Aqar combined category ID (e.g. `6`=Apartment sale, `1`=Apartment rent, `3`=Villa sale). | | propertyType | string | No | Alias used when `category` is blank (e.g. `apartment`, `villa`, `land`). | | deal | string | No | Alias used when `category` is blank: `sale` or `rent`. | | city | string | No | City name (Arabic or English), e.g. `Riyadh`. | | cityId | integer | No | Aqar numeric city ID (overrides `city`). | | listingIds | array | No | Specific Aqar listing IDs (Detail mode). | | minPrice / maxPrice | integer | No | Price range filter (SAR). | | minArea / maxArea | integer | No | Area range filter (m²). | | minBeds / minLivings / minBaths | integer | No | Minimum room counts. | | furnished | string | No | `1` furnished, `0` unfurnished. | | sort / sortDir | string | No | Sort field (e.g. `create_time`, `price`) and direction (`asc`/`desc`). | | maxResults | integer | No | Max listings this run. Default 100. | **Example — by category & city:** ```json { "scrapeMode": "overview", "category": "6", "city": "Riyadh", "minPrice": 500000, "maxPrice": 2000000, "minBeds": 3, "sort": "create_time", "sortDir": "desc", "maxResults": 200 } ``` **Example — by property type + deal:** ```json { "scrapeMode": "overview", "propertyType": "villa", "deal": "sale", "city": "Jeddah", "maxResults": 100 } ``` **Example — full Detail by listing ID:** ```json { "scrapeMode": "detail", "listingIds": ["6651360", "6650000"] } ``` ### 📤 Output Results are saved to the Apify dataset with **60+ fields** including: | Field | Type | Description | |-------|------|-------------| | id | number | Aqar listing ID | | propertyTitle | string | Listing title | | url | string | Listing URL | | deal\_type | string | `sale` or `rent` | | property\_type | string | Apartment, Villa, Land, … | | price | number | Asking / rent price (SAR) | | currency | string | Always SAR | | meter\_price / price\_per\_sqm | number | Per-m² price (reported + computed) | | price\_2\_payments / price\_4\_payments / price\_12\_payments | number | Installment rent prices | | area\_sqm | number | Area in m² | | beds / livings / rooms / baths | number | Room counts | | age / furnished / ac / pool / elevator | mixed | Property attributes | | city / district / region / street / address | string | Location rollup | | latitude / longitude | number | GPS coordinates | | advertiser\_name / advertiser\_company / advertiser\_type | string | Advertiser (owner / agency) | | advertiser\_phone / advertiser\_rega\_id | string | Advertiser contact + REGA ID | | ad\_license\_number | string | FAL advertising-license number | | deed\_number / deed\_area / off\_plan\_license\_number | mixed | REGA deed + off-plan license | | rega\_licensed / rega\_license\_url | mixed | REGA license status + link | | images / images\_count / thumbnail | array / number / string | Photo gallery | | description / description\_en | string | Listing description | **Example:** ```json { "id": 6651360, "propertyTitle": "شقة للإيجار في حي الياسمين", "url": "https://sa.aqar.fm/listing/6651360", "deal_type": "rent", "property_type": "apartment", "price": 27000, "currency": "SAR", "meter_price": 300, "price_per_sqm": 300, "area_sqm": 90, "beds": 3, "baths": 2, "city_id": 21, "latitude": 24.902418, "longitude": 46.383651, "advertiser_name": "محمد خالد", "advertiser_type": "owner", "ad_license_number": "7200932465", "deed_number": "813101000703", "images": ["https://images.aqar.fm/webp/800x0/props/..."], "images_count": 12 } ``` ### 💼 Use Cases & Examples #### 1. Market research & price benchmarking **Analysts sizing a city market.** **Input:** `overview` Riyadh apartments for sale. **Output:** thousands of listings with price-per-m². **Use:** build a live price index per district. #### 2. Investment sourcing **Investors hunting high-yield stock.** **Input:** `overview` + price/area/bedroom filters. **Output:** filtered listings with price-per-m² and GPS. **Use:** rank deals by price-per-m² vs district median. #### 3. Agency & advertiser lead generation **Recruiters and agencies building contact lists.** **Input:** Overview scan of a target city. **Output:** `advertiser_name`, `advertiser_company`, `advertiser_type` and REGA ID on every row. **Use:** prospecting and competitive coverage. #### 4. Compliance & due diligence **Compliance teams verifying listing legitimacy.** **Input:** Overview or Detail. **Output:** FAL advertising license, REGA deed number and verification flags. **Use:** screen licenses and flag unverified stock. #### 5. Proptech & valuation data feeds **Proptech teams powering AVMs and dashboards.** **Input:** scheduled runs per category + city. **Output:** a clean, repeatable Saudi real-estate data feed. **Use:** feed models without an Aqar API. #### 6. Rental-yield research **Investors comparing rent vs sale.** **Input:** `overview` rentals + sales in the same district. **Output:** rent and sale prices with area. **Use:** compute gross yields across neighborhoods. #### 7. Relocation & buyer search **Relocation services shortlisting homes.** **Input:** `overview` + filters + Detail mode. **Output:** full records with photos and attributes. **Use:** curated client shortlists across Saudi Arabia. ### 🔗 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/aqar-property-scraper').call({ scrapeMode: 'overview', category: '6', city: 'Riyadh', maxResults: 50, }); 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/aqar-property-scraper').call( run_input={'scrapeMode': 'overview', 'category': '6', 'city': 'Riyadh', 'maxResults': 50} ) for item in client.dataset(run['defaultDatasetId']).iterate_items(): print(item) ``` #### cURL ```bash curl -X POST 'https://api.apify.com/v2/acts/sian.agency~aqar-property-scraper/runs?token=YOUR_TOKEN' \ -H 'Content-Type: application/json' \ -d '{"scrapeMode":"overview","category":"6","city":"Riyadh","maxResults":50}' ``` #### 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/DB, notify, or transform ### 📊 Performance & Pricing #### FREE Tier (Try It Now) - Scrape listings per run — full feature access, same quality - No credit card required - Perfect for testing and small projects #### PAID Tier (Production Ready) - **Unlimited** listings per run - Pay-per-result: only charged for listings actually extracted - Overview and Detail priced separately so you only pay for the depth you use 💰 **Pay only for what you extract** — Overview for cheap whole-market sweeps, Detail for the full per-listing record. 🔗 [View current pricing](https://apify.com/sian.agency/aqar-property-scraper?fpr=sian) ### ❓ Frequently Asked Questions **Q: Which markets are covered?** A: All of Saudi Arabia — search any Saudi city by name (Arabic or English) or city ID. **Q: Do I need an Aqar API key?** A: No. There's no setup and no Aqar account or API key required. **Q: What's the difference between Overview and Detail?** A: Overview is a fast, low-cost scan that pulls bulk listings (already ~95% of useful fields). Detail fetches the full record for specific listings by ID. **Q: Can I filter by city, price and rooms?** A: Yes — set `city` (or `cityId`), `minPrice`/`maxPrice`, `minArea`/`maxArea`, `minBeds`, `minBaths`, `furnished`, and `sort`. **Q: Does it include FAL / deed compliance data?** A: Yes — rows carry the FAL advertising-license number, REGA title-deed number, off-plan license and REGA verification flags. **Q: Does it work for both sale and rent?** A: Yes — pick a sale or rent category (or set `deal` to `sale` / `rent`). **Q: What output formats are available?** A: JSON, CSV, Excel — export directly from the Apify dataset. ### 🐛 Troubleshooting **No results returned** - Check the `category` / `city` combination, or loosen filters — an overly tight price/area/bedroom combination can return zero listings. - Try searching without a city to scan all of Saudi Arabia. **Detail mode returns nothing** - Make sure `listingIds` contain valid Aqar listing IDs, or run `overview` first to discover them. **Fewer results than expected** - The FREE tier caps listings per run. Upgrade to PAID for unlimited, or raise `maxResults`. ### ⚖️ 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/). *This is an independent tool and is not affiliated with, endorsed by, or sponsored by Aqar or its parent company. "Aqar" is a trademark of its respective owner. You are responsible for complying with Aqar's terms of service and all applicable laws when using this tool.* ### 🤝 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 from the actor page - 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 ## `scrapeMode` (type: `string`): ⚡ **OVERVIEW** — fast, cheap, ungated. Pulls every core field straight from Aqar's search (price, price/m², beds, baths, area, GPS, photos, advertiser, FAL license, deed). 🔍 **DETAIL** — full record per listing by listing ID. Priced higher per result. **TIP:** Start with Overview — the search record already carries ~95% of useful fields. ## `searchMode` (type: `string`): 🧭 How to tell the scraper what to fetch. **Usually leave this blank — it is auto-inferred** from your inputs: - **By search** — search a property category + city + filters. The default. - **By listing ID** — Detail mode only: fetch specific listings by their Aqar listing ID. **NOTE:** *By listing ID* is valid only when Scrape mode = Detail. ## `category` (type: `string`): 🏷️ Aqar's combined category — it bundles the **property type and the deal (sale/rent)** into one ID. Either set this directly, OR leave it blank and use **Property type** + **Deal** below. Common IDs: **1** = Apartment for rent · **6** = Apartment for sale · **3** = Villa for sale · **5** = Villa for rent · **2** = Land for sale · **9** = House for sale · **14** = Office for rent. ## `propertyType` (type: `string`): 🏠 Optional alias — used only when **Category** is blank. Combined with **Deal** to resolve the right category. ## `deal` (type: `string`): 🤝 Optional alias — used only when **Category** is blank. Combined with **Property type** to resolve the right category. ## `city` (type: `string`): 🏙️ City to search — Arabic or English (e.g. `Riyadh`, `الرياض`, `Jeddah`, `Dammam`). Resolved to the highest-inventory match automatically. Leave blank to search all of Saudi Arabia. ## `cityId` (type: `integer`): 🆔 Optional. Aqar numeric city ID (overrides **City** when set). E.g. 21 = Riyadh, 66 = Jeddah. ## `listingIds` (type: `array`): 🆔 **Detail mode only.** Specific Aqar listing IDs (or full `https://sa.aqar.fm/listing/` URLs) to fetch as full records. **BULK EDIT:** Click "Bulk edit" to paste many IDs, one per line. ## `maxResults` (type: `integer`): 🔢 Maximum listings to extract this run. - **FREE tier:** capped at 25 listings per run. - **PAID tier:** unlimited — set as high as you need. ## `sort` (type: `string`): ↕️ How Aqar orders the results before they are scraped. ## `sortDir` (type: `string`): ↕️ Ascending or descending order for the sort field above. ## `minPrice` (type: `integer`): 💸 Optional. Minimum price filter in Saudi Riyal. ## `maxPrice` (type: `integer`): 💰 Optional. Maximum price filter in Saudi Riyal. ## `minArea` (type: `integer`): 📐 Optional. Minimum area in square meters. ## `maxArea` (type: `integer`): 📐 Optional. Maximum area in square meters. ## `minBeds` (type: `integer`): 🛏️ Optional. Minimum number of bedrooms. ## `minLivings` (type: `integer`): 🛋️ Optional. Minimum number of living rooms. ## `minBaths` (type: `integer`): 🛁 Optional. Minimum number of bathrooms. ## `furnished` (type: `string`): 🛋️ Optional. Filter by furnishing status. ## `districtId` (type: `integer`): 📍 Optional. Restrict to a specific Aqar district ID within the city. ## `directionId` (type: `integer`): 🧭 Optional. Restrict to a specific Aqar street-direction ID (facing). ## `provinceId` (type: `integer`): 🗺️ Optional. Restrict to a specific Aqar province ID. ## Actor input object example ```json { "scrapeMode": "overview", "searchMode": "bySearch", "category": "6", "propertyType": "", "deal": "", "city": "Riyadh", "listingIds": [ "6651360" ], "maxResults": 100, "sort": "create_time", "sortDir": "desc", "furnished": "" } ``` # Actor output Schema ## `results` (type: `string`): Scraped Aqar listings (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 = {}; // Run the Actor and wait for it to finish const run = await client.actor("sian.agency/aqar-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 = {} # Run the Actor and wait for it to finish run = client.actor("sian.agency/aqar-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 '{}' | apify call sian.agency/aqar-property-scraper --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=sian.agency/aqar-property-scraper", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "Aqar Scraper — Saudi Arabia Property Data & API", "description": "Aqar scraper & real estate data API for Saudi Arabia's #1 property portal (sa.aqar.fm). Sale & rent listings across every Saudi city: price, price/m², beds, baths, area, GPS, photos, advertiser, FAL license & deed number — clean JSON/CSV.", "version": "1.0", "x-build-id": "DufgYKuG4ADcOwn47" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/sian.agency~aqar-property-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-sian.agency-aqar-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~aqar-property-scraper/runs": { "post": { "operationId": "runs-sync-sian.agency-aqar-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~aqar-property-scraper/run-sync": { "post": { "operationId": "run-sync-sian.agency-aqar-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": { "scrapeMode": { "title": "⚡ Scrape mode", "enum": [ "overview", "detail" ], "type": "string", "description": "⚡ **OVERVIEW** — fast, cheap, ungated. Pulls every core field straight from Aqar's search (price, price/m², beds, baths, area, GPS, photos, advertiser, FAL license, deed).\n\n🔍 **DETAIL** — full record per listing by listing ID. Priced higher per result.\n\n**TIP:** Start with Overview — the search record already carries ~95% of useful fields.", "default": "overview" }, "searchMode": { "title": "🧭 Search by (auto-detected)", "enum": [ "bySearch", "byListingId" ], "type": "string", "description": "🧭 How to tell the scraper what to fetch. **Usually leave this blank — it is auto-inferred** from your inputs:\n\n- **By search** — search a property category + city + filters. The default.\n- **By listing ID** — Detail mode only: fetch specific listings by their Aqar listing ID.\n\n**NOTE:** *By listing ID* is valid only when Scrape mode = Detail.", "default": "bySearch" }, "category": { "title": "🏷️ Category (property type + deal)", "enum": [ "", "1", "6", "3", "5", "2", "15", "9", "11", "7", "16", "14", "47", "8", "20", "12", "56", "23", "19", "4", "22" ], "type": "string", "description": "🏷️ Aqar's combined category — it bundles the **property type and the deal (sale/rent)** into one ID. Either set this directly, OR leave it blank and use **Property type** + **Deal** below.\n\nCommon IDs: **1** = Apartment for rent · **6** = Apartment for sale · **3** = Villa for sale · **5** = Villa for rent · **2** = Land for sale · **9** = House for sale · **14** = Office for rent.", "default": "6" }, "propertyType": { "title": "🏠 Property type", "enum": [ "", "apartment", "villa", "land", "house", "building", "office", "store", "farm", "chalet", "room", "floor", "warehouse", "rest_house", "camp" ], "type": "string", "description": "🏠 Optional alias — used only when **Category** is blank. Combined with **Deal** to resolve the right category.", "default": "" }, "deal": { "title": "🤝 Deal", "enum": [ "", "sale", "rent" ], "type": "string", "description": "🤝 Optional alias — used only when **Category** is blank. Combined with **Property type** to resolve the right category.", "default": "" }, "city": { "title": "🏙️ City", "type": "string", "description": "🏙️ City to search — Arabic or English (e.g. `Riyadh`, `الرياض`, `Jeddah`, `Dammam`). Resolved to the highest-inventory match automatically. Leave blank to search all of Saudi Arabia." }, "cityId": { "title": "🆔 City ID", "minimum": 1, "type": "integer", "description": "🆔 Optional. Aqar numeric city ID (overrides **City** when set). E.g. 21 = Riyadh, 66 = Jeddah." }, "listingIds": { "title": "🆔 Listing IDs", "type": "array", "description": "🆔 **Detail mode only.** Specific Aqar listing IDs (or full `https://sa.aqar.fm/listing/` URLs) to fetch as full records.\n\n**BULK EDIT:** Click \"Bulk edit\" to paste many IDs, one per line.", "items": { "type": "string" } }, "maxResults": { "title": "🔢 Max results", "minimum": 1, "type": "integer", "description": "🔢 Maximum listings to extract this run.\n\n- **FREE tier:** capped at 25 listings per run.\n- **PAID tier:** unlimited — set as high as you need.", "default": 100 }, "sort": { "title": "↕️ Sort by", "enum": [ "create_time", "last_update", "price", "area", "meter_price", "refresh" ], "type": "string", "description": "↕️ How Aqar orders the results before they are scraped.", "default": "create_time" }, "sortDir": { "title": "↕️ Sort direction", "enum": [ "desc", "asc" ], "type": "string", "description": "↕️ Ascending or descending order for the sort field above.", "default": "desc" }, "minPrice": { "title": "💸 Min price (SAR)", "minimum": 0, "type": "integer", "description": "💸 Optional. Minimum price filter in Saudi Riyal." }, "maxPrice": { "title": "💰 Max price (SAR)", "minimum": 0, "type": "integer", "description": "💰 Optional. Maximum price filter in Saudi Riyal." }, "minArea": { "title": "📐 Min area (m²)", "minimum": 0, "type": "integer", "description": "📐 Optional. Minimum area in square meters." }, "maxArea": { "title": "📐 Max area (m²)", "minimum": 0, "type": "integer", "description": "📐 Optional. Maximum area in square meters." }, "minBeds": { "title": "🛏️ Min bedrooms", "minimum": 0, "type": "integer", "description": "🛏️ Optional. Minimum number of bedrooms." }, "minLivings": { "title": "🛋️ Min living rooms", "minimum": 0, "type": "integer", "description": "🛋️ Optional. Minimum number of living rooms." }, "minBaths": { "title": "🛁 Min bathrooms", "minimum": 0, "type": "integer", "description": "🛁 Optional. Minimum number of bathrooms." }, "furnished": { "title": "🛋️ Furnishing", "enum": [ "", "1", "0" ], "type": "string", "description": "🛋️ Optional. Filter by furnishing status.", "default": "" }, "districtId": { "title": "📍 District ID", "minimum": 1, "type": "integer", "description": "📍 Optional. Restrict to a specific Aqar district ID within the city." }, "directionId": { "title": "🧭 Direction ID", "minimum": 1, "type": "integer", "description": "🧭 Optional. Restrict to a specific Aqar street-direction ID (facing)." }, "provinceId": { "title": "🗺️ Province ID", "minimum": 1, "type": "integer", "description": "🗺️ Optional. Restrict to a specific Aqar province ID." } } }, "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 } } } } } } } } } } ```