# Haraj Scraper & Monitor (`crawlstone/haraj-scraper-monitor`) Actor Search public Haraj ads, collect detailed ad and seller information, and monitor selected listings for changes. - **URL**: https://apify.com/crawlstone/haraj-scraper-monitor.md - **Developed by:** [Crawl Stone](https://apify.com/crawlstone) (community) - **Categories:** E-commerce, Lead generation - **Stats:** 2 total users, 1 monthly users, 91.7% runs succeeded, 0 bookmarks - **User rating**: No ratings yet ## Pricing from $7.50 / 1,000 monitor runs 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 web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows. 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/docs.md): ```bash npm install apify-client ``` In Python projects, use official [Python client library](https://docs.apify.com/api/client/python/docs.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/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 ## Haraj Scraper & Monitor We built Haraj Scraper & Monitor to provide a straightforward way to search classified listings, retrieve seller and ad profiles, and track price or availability changes on Haraj. Instead of writing custom browser automation or coordinating proxies, you can use our pre-built modes to collect structured data on-demand. > **Unofficial Actor:** This is an independent tool and is not affiliated with, authorized, or endorsed by Haraj. --- ### From Discovery to Automated Monitoring The Actor is designed around a three-stage workflow that matches how you explore a marketplace: discover listings, inspect targeted records, and monitor specific items for changes over time. #### 1. Discover listings (`discover`) Search by keyword to capture an initial set of listings. This mode acts as your entry point, preserving Haraj's source order and duplicate occurrences. * **Inputs:** `keyword` (required), optional `tag` refinement, and `city` refinement. * **Result limit:** `maxResults` controls your target size (defaults to `50`, range `50–1000`). #### 2. Inspect a listing (`adDetail`) or seller (`sellerDetail`) Examine the exact entities discovered during search. * **Inspect an ad (`adDetail`):** Fetches a detailed record of a single listing. In addition to core listing info, it retrieves category-specific attributes (including structured properties for `car`, `realEstate`, and `job` listings), images, geographic locations, notes, purchase actions, and comment metadata (such as comment enablement status and counts). * *Inputs:* `adUrl` (required). * **Inspect a seller (`sellerDetail`):** Fetches a public seller profile and gathers up to 1,000 of their nested ads in source order with duplicate occurrences preserved. Reviews are not collected, and no truncation metadata is exposed. * *Inputs:* `sellerUsername` (required). #### 3. Monitor specific ads (`monitor`) Track changes to price, availability, and attributes on selected listings over time. * **Creation:** Initialize the monitor with 1–10 unique ad URLs to generate a `monitorId` and save a baseline snapshot as revision `0`. * **Continuation:** Run subsequent checks using only the saved `monitorId`. The Actor retrieves new snapshots and compares each listing against its last successfully saved snapshot to emit change lists. * **Deterministic change categories:** Detected differences are flagged in a `changes` array under: `availability`, `status`, `title`, `description`, `price`, `media`, `location`, `seller`, `tags`, or `attributes`. * **Per-ad execution:** Each listing is processed separately. If a single target check encounters a technical failure, the Actor outputs an `error` row, preserves that ad's last successful snapshot in state, and continues checking the other URLs. When monitoring, an ad can have three distinct states: 1. **Active Observation:** The ad is available, returning standard details. 2. **Unavailable Observation:** The ad is reported as unavailable. The snapshot contains only `adId` and `available: false`. 3. **Technical Failure:** The source check fails due to network or timeout issues. The Actor outputs an `error` row and preserves the ad's last successfully stored snapshot in state. --- ### Quick Start 1. Click **Try for free** on the Actor page. 2. Under **Mode**, the dropdown defaults to **Discover ads** (`discover`) with the prefilled keyword `سيارة` (car). 3. Under **Discover ads**, choose an optional city or region from the pre-defined dropdown to refine your search. 4. Click **Start**. 5. View your results in the **Dataset** tab once the run finishes. For your first run, you can use the prefilled configuration: ```json { "mode": "discover", "keyword": "سيارة" } ```` *** ### Input & URL Requirements To ensure successful runs, please keep the following input rules in mind: - **Keyword Search:** Every discovery run requires a search `keyword`. You can optionally refine the keyword with a free-text `tag` or select a supported location from the pre-defined `city` dropdown (which includes Saudi cities as well as regional entries like Kuwait, UAE, and Bahrain). - **Ad URL Formatting:** Ad inspection (`adDetail`) and monitor creation (`adUrls`) require canonical HTTPS links starting with `https://haraj.com.sa/` followed by a numeric public ID beginning with `11` (e.g., `https://haraj.com.sa/11184299879`). Remove any language prefixes (like `/en`), query parameters, or trailing hash fragments. Raw ad numbers without a full URL are rejected. *** ### Data Structure & Examples Dataset outputs are saved in the run's default Dataset and categorized under five specific row types: `ad`, `adDetail`, `seller`, `monitorObservation`, and `error`. - **Language Preservation:** Arabic and mixed-language titles, descriptions, and tag values are preserved exactly as returned. - **Pricing Values:** Formatted prices are returned as source display text (e.g., `100 ريال`). The Actor does not perform lossy numeric or currency conversions. - **Optional Fields:** Highly unstructured listings mean metadata fields vary. Optional properties are omitted from rows when missing, while confirmed `0`, `false`, and empty arrays are explicitly serialized. #### Monitor Observation Example (`monitorObservation`) The monitoring dataset view includes the `monitorId`, `revision`, `changes` categories, and compares the `current` snapshot with the `previous` snapshot. *This is an abridged preview of selected fields, not a complete schema-valid Dataset row.* ```json { "type": "monitorObservation", "monitorId": "8b23cb41-3da6-46c0-9a25-cb1e6a4b1234", "revision": 2, "adUrl": "https://haraj.com.sa/11184299879", "changes": ["price"], "previous": { "adId": "11184299879", "available": true, "title": "حراج السيارات | سيارة نظيفة جدا", "formattedPrice": "120000 ريال", "updatedAt": "2026-03-01T14:30:00Z" }, "current": { "adId": "11184299879", "available": true, "title": "حراج السيارات | سيارة نظيفة جدا", "formattedPrice": "115000 ريال", "updatedAt": "2026-03-02T09:15:00Z" } } ``` - **Unavailable Snapshots:** If Haraj reports an ad as unavailable, the snapshot contains only `"adId": "..."` and `"available": false` (with no title, price, or description fields). - **Technical Failures:** If a temporary connection issue prevents an ad from being checked, the Actor emits an `error` row with `type: "error"`, a diagnostic `message`, and the target `url`. *** ### Pricing & Proxies #### Saudi Residential Proxies Included Haraj requests are automatically routed through Saudi Arabian residential proxies. Users pay strictly for the Actor’s custom Pay-Per-Event (PPE) operations; platform compute and Saudi managed-proxy expenses are fully included in the Actor's pricing. There is no customer proxy configuration or separate platform/proxy expense to manage. #### Custom Pay-Per-Event (PPE) Billing Charges are applied based on successful operations using these custom events. Refer to the Actor's **Pricing** tab for current rates. 1. **`discover-ad`** (Charged per saved ad during discovery): - Successful discovery runs are charged the greater of 50 units or the exact number of ads saved. - If a search returns 0 to 50 results, you are billed for exactly `50` events. - If a search returns 80 results, you are billed for exactly `80` events. 2. **`ad-detail`** (Charged once per successful detail inspection): - Billed for exactly one `ad-detail` event when a complete `adDetail` row is saved. 3. **`seller-detail`** (Charged once per successful seller profile retrieved): - Billed for exactly one `seller-detail` event. This includes nesting up to 1,000 of the seller's ads at no extra charge. 4. **`monitor-run`** (Charged once per monitored run): - Charged as a flat event when at least one monitored ad check produces a successful observation (whether it is an active snapshot or a billable unavailable status snapshot). #### Error and Partial-Check Semantics - **All-Error Checks:** Both monitor workflows fail and do not charge `monitor-run` if all targets fail. An all-error creation run creates no monitor state, while an all-error continuation run leaves the existing state and revision unchanged. - **Partial Checks:** If some checked ads succeed and others experience technical failures, the run continues successfully and charges one `monitor-run` event. Failed targets output `error` rows, and their last successfully stored snapshots remain in state. - **Complete Inspection Failures:** If an inspect (`adDetail` or `sellerDetail`) operation fails due to network or source downtime, it outputs a diagnostic `error` row and the run is not charged. *** ### Use with Apify MCP If you integrate market data into AI assistant workflows, you can connect this Actor directly to compatible clients (such as Claude Desktop) using Apify's hosted Model Context Protocol (MCP) server: ```text https://mcp.apify.com?tools=crawlstone/haraj-scraper-monitor ``` Once connected, you can run natural language queries to discover listings, inspect sellers, or trigger monitor checks directly from your AI chat interface. *** ### Frequently Asked Questions #### Can I modify the URLs in an existing monitor? No. A monitor supports a fixed, immutable set of 1–10 ad URLs defined when it is created. To track a different list or add more listings, run the Actor with your new URLs to generate a new `monitorId`. #### How do I schedule recurring monitor runs? Configure an [Apify Schedule](https://docs.apify.com/platform/schedules) with your `monitorId` to run hourly, daily, or at another interval. Ensure your schedule is configured for exclusive execution; concurrent or overlapping runs of the exact same `monitorId` are unsupported. #### Why does my first monitor run show no changes? The initial run (revision `0`) acts as a baseline, capturing the current status of each ad. The `changes` array is empty, and there is no `previous` snapshot. Subsequent continuation runs will compare new snapshots against each listing's last successfully saved state. *** ### Support If you need assistance, please open a ticket on this Actor's **Discussion** tab and include: - Your Apify **Run ID**. - The selected **Mode** and the **Input** parameters you provided. - A description of what you expected versus what occurred. *Please do not share your Apify API Token or other private credentials in public support tickets.* # Actor input Schema ## `mode` (type: `string`): Choose one direct operation. Discover is preselected with a sample keyword for a ready-to-run search. ## `adUrls` (type: `array`): Used only to create a monitor. Enter 1–10 unique canonical public Haraj ad URLs and omit monitorId. ## `monitorId` (type: `string`): Used only to continue a monitor. Enter the canonical lowercase UUID returned by monitor creation and omit adUrls. ## `keyword` (type: `string`): Required for discover. Search text is trimmed and may be refined with tag and city. ## `tag` (type: `string`): Optional discover refinement used with the required keyword. Tags are trimmed free text. ## `city` (type: `string`): Optional discover refinement used with the required keyword, selected from the maintained city snapshot. ## `sellerUsername` (type: `string`): Required only for sellerDetail. The value is trimmed and identifies the seller profile and ads to collect. ## `maxResults` (type: `integer`): Used only by discover. Accepts 50–1,000 root ad results. ## `adUrl` (type: `string`): Required for adDetail. Use an exact HTTPS haraj.com.sa public ad URL without query parameters or a fragment. ## Actor input object example ```json { "mode": "discover", "monitorId": "123e4567-e89b-42d3-a456-426614174000", "keyword": "سيارة", "tag": "حراج السيارات", "sellerUsername": "الرحلة الملكية", "maxResults": 50, "adUrl": "https://haraj.com.sa/11184299879" } ``` # Actor output Schema ## `results` (type: `string`): Open the default Dataset. Monitor snapshots are also retained as compact latest state in the named harajmon-state Key-value store, but that KVS is not a primary Actor output. # 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 = { "mode": "discover", "keyword": "سيارة" }; // Run the Actor and wait for it to finish const run = await client.actor("crawlstone/haraj-scraper-monitor").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 = { "mode": "discover", "keyword": "سيارة", } # Run the Actor and wait for it to finish run = client.actor("crawlstone/haraj-scraper-monitor").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 '{ "mode": "discover", "keyword": "سيارة" }' | apify call crawlstone/haraj-scraper-monitor --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=crawlstone/haraj-scraper-monitor", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "Haraj Scraper & Monitor", "description": "Search public Haraj ads, collect detailed ad and seller information, and monitor selected listings for changes.", "version": "1.0", "x-build-id": "SC1zzHxKahyJpr820" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/crawlstone~haraj-scraper-monitor/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-crawlstone-haraj-scraper-monitor", "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/crawlstone~haraj-scraper-monitor/runs": { "post": { "operationId": "runs-sync-crawlstone-haraj-scraper-monitor", "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/crawlstone~haraj-scraper-monitor/run-sync": { "post": { "operationId": "run-sync-crawlstone-haraj-scraper-monitor", "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": [ "mode" ], "properties": { "mode": { "title": "Mode", "enum": [ "monitor", "discover", "adDetail", "sellerDetail" ], "type": "string", "description": "Choose one direct operation. Discover is preselected with a sample keyword for a ready-to-run search." }, "adUrls": { "title": "Ads to monitor", "minItems": 1, "maxItems": 10, "uniqueItems": true, "type": "array", "description": "Used only to create a monitor. Enter 1–10 unique canonical public Haraj ad URLs and omit monitorId.", "items": { "type": "string", "pattern": "^https://haraj\\.com\\.sa/11[1-9][0-9]*(?:/[^/?#]+)?/?$" } }, "monitorId": { "title": "Monitor ID", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "type": "string", "description": "Used only to continue a monitor. Enter the canonical lowercase UUID returned by monitor creation and omit adUrls." }, "keyword": { "title": "Keyword", "minLength": 1, "type": "string", "description": "Required for discover. Search text is trimmed and may be refined with tag and city." }, "tag": { "title": "Tag", "minLength": 1, "type": "string", "description": "Optional discover refinement used with the required keyword. Tags are trimmed free text." }, "city": { "title": "City or region", "enum": [ "الرياض", "الخرج", "الدرعية", "الدلم", "الدوادمي", "الحريق", "الزلفي", "السليل", "الغاط", "القويعية", "المجمعة", "المزاحمية", "الهياثم", "ثادق", "حوطة بني تميم", "رماح", "شقراء", "عفيف", "الشرقيه", "الدمام", "الخبر", "الظهران", "الجبيل", "حفر الباطن", "الهفوف", "تاروت", "المبرز", "العيون", "النعيرية", "بقيق", "راس تنورة", "الخفجي", "القطيف", "سيهات", "صفوى", "عنك", "جده", "مكه", "الطايف", "القنفذة", "الكامل", "الليث", "تربة مكة", "ثول", "الجموم", "رابغ", "رنية", "مدينة الملك عبدالله الاقتصادية", "الخرمة", "ينبع", "المدينة", "العلا", "الحناكية", "بدر", "خيبر", "مهد الذهب", "تبوك", "املج", "الوجه", "تيماء", "ضبا", "القصيم", "بريدة", "عنيزة", "الرس", "الشماسية", "المذنب", "النبهانية", "البدائع", "رياض الخبراء", "البكيرية", "حائل", "الغزالة", "بقعاء", "الشنان", "تربة حائل", "أبها", "عسير", "خميس مشيط", "المجاردة", "بللسمر", "بيشة", "تثليث", "احد رفيده", "محايل عسير", "الباحة", "جيزان", "نجران", "شرورة", "الوديعة", "الجوف", "القريات", "دومة الجندل", "سكاكا", "عرعر", "رفحاء", "طريف", "الكويت", "الإمارات", "البحرين" ], "type": "string", "description": "Optional discover refinement used with the required keyword, selected from the maintained city snapshot." }, "sellerUsername": { "title": "Seller username", "minLength": 1, "type": "string", "description": "Required only for sellerDetail. The value is trimmed and identifies the seller profile and ads to collect." }, "maxResults": { "title": "Maximum discovery results", "minimum": 50, "maximum": 1000, "type": "integer", "description": "Used only by discover. Accepts 50–1,000 root ad results.", "default": 50 }, "adUrl": { "title": "Ad URL", "pattern": "^https://haraj\\.com\\.sa/11[1-9][0-9]*(?:/[^/?#]+)?/?$", "type": "string", "description": "Required for adDetail. Use an exact HTTPS haraj.com.sa public ad URL without query parameters or a fragment." } } }, "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 } } } } } } } } } } ```