Haraj Scraper

Scrape Haraj (haraj.com.sa) — Saudi Arabia's largest online classifieds marketplace, covering cars, real estate, electronics, furniture, jobs, services, and everything in between. Search by keyword, browse by category or city, look up specific listings by ID/URL, or pull every active listing from a seller. HTTP-only via Haraj's own public GraphQL API. No auth, no cookies, no proxy.

What this actor does

• Five modes: search (keyword), browse (category / city / latest feed), byId (lookup by listing ID or URL), byAuthor (all listings from a seller), trending (site-wide trending search keywords — not listings)
• 20 categories and 21 cities/regions (Saudi Arabia, Kuwait, UAE, Bahrain) — filter by one or several at once, plus free-text subTag, carBodyType, and neighborhood for finer brand/model, car body style, and town-level narrowing
• Rich filters: price range (SAR), only-with-image, only-with-video, exclude a category, hide dealer/store showroom listings (mode=search), sort order
• Category-specific enrichment: car specs (model year, mileage, fuel, transmission, condition), real estate REGA registration numbers, job details, general spec attributes, and an optional similarListings[] lookup (mode=byId)
• Empty fields are omitted

Output per listing

• id — Haraj numeric listing ID
• title, description
• priceSAR — price in Saudi Riyal (omitted when the seller didn't state a price)
• category — the listing's most specific category tag
• categories[] — full list of category/brand/model tags Haraj assigned to the listing
• city, geoCity, geoNeighborhood, geoHash — region, city/town, neighborhood, and a geohash for the listing's approximate coordinates
• images[], thumbnailUrl
• url — canonical listing URL
• authorUsername, authorId — seller / store name and Haraj's numeric account ID (useful for disambiguating sellers who share a display name)
• postedDate, updatedDate — ISO 8601 UTC (updatedDate only present when different from postedDate — e.g. the seller renewed/bumped the ad)
• hasImage, hasVideo, isPromoted, commentCount
• upvotes, downvotes — Haraj's community "helpful / not helpful" feedback counts on the listing (0 is a real "no votes yet" value, not a missing one)
• car — for vehicle listings: listingType, is4WheelDrive, modelYear, mileageKm, fuelType, transmission, condition, vehicleType, bank
• realEstate — for property listings: regaAdvertiserRegistrationNumber, regaAuthorizationNumber
• job — for job listings (when reachable via search/byId/byAuthor): offerType, experienceLevel, contractType, qualification, commercialRegisterNumber
• specs — key/value attributes Haraj extracted for the item (e.g. laptop brand, RAM size, screen size)
• similarListings[] — only when mode=byId and includeSimilarListings=true: related listings (id, title, url, priceSAR, thumbnailUrl, city)
• recordType — listing / carListing / realEstateListing / jobListing, scrapedAt

Output for mode=trending

Each record is a trending search keyword, not a listing:

• keyword — the trending search term
• score — Haraj's relevance/popularity score for the keyword over the requested window (0-1 range observed)
• rangeInDays — the window that was requested
• recordType — trendingKeyword, scrapedAt

Input

Field	Type	Default	Description
mode	string	search	search / browse / byId / byAuthor / trending
searchQuery	string	–	Free-text keyword (mode=search, required for this mode)
category	string	–	One of 20 top-level categories (mode=search, browse)
subTag	string	–	A specific brand/model tag, narrower than category (mode=search, browse). Takes priority over category for upstream narrowing when both are set.
carBodyType	string	–	One of 12 car body styles (mode=search, browse). Takes priority over subTag/category for upstream narrowing when both are set.
city	string	–	One of 21 cities/regions (mode=search, browse)
cities	array	[]	Multiple cities/regions at once, OR-combined with city if both set (mode=search, browse)
neighborhood	string	–	A specific town/district, narrower than city/cities — ANDed with them (mode=search, browse, byAuthor)
excludeCategory	string	–	Drop results from this category
postIds	array	–	Listing IDs or full URLs (mode=byId, required for this mode)
authorUsername	string	–	Exact seller/store username (mode=byAuthor, required for this mode)
includeSimilarListings	bool	false	Attach similarListings[] per record (mode=byId only)
trendingRangeDays	int	1	Trending window in days, 1–14 (mode=trending)
priceMin	int	–	Drop listings priced below this (SAR)
priceMax	int	–	Drop listings priced above this (SAR)
onlyWithImage	bool	false	Only listings with photos
onlyWithVideo	bool	false	Only listings with video
hideShowRooms	bool	false	Exclude dealer/store-seller listings (mode=search only)
sortBy	string	recentlyActive	recentlyActive (bumped/renewed first) / newestPosted (by original post date)
maxItems	int	30	Hard cap (1–1000)

Example: search with price range

{
  "mode": "search",
  "searchQuery": "ايفون",
  "priceMin": 1000,
  "priceMax": 3000,
  "maxItems": 50
}

Example: browse cars for sale in Jeddah

{
  "mode": "browse",
  "category": "حراج السيارات",
  "city": "جده",
  "onlyWithImage": true,
  "maxItems": 50
}

Example: lookup specific listings by ID or URL

{
  "mode": "byId",
  "postIds": ["186610241", "https://haraj.com.sa/11186610633/ايفون_17_برو/"]
}

Example: every active listing from a seller

{
  "mode": "byAuthor",
  "authorUsername": "معرض رائد علي القحطاني",
  "maxItems": 100
}

Use cases

• Price intelligence — track asking prices for cars, phones, or real estate across Saudi cities
• Lead generation — monitor new listings in a specific category or city as they're posted
• Market research — analyze categories, brands, and specs trending on Saudi Arabia's largest classifieds site
• Seller monitoring — track everything a specific store/seller has listed
• Real estate analytics — pull REGA-licensed property listings with registration details
• Automotive analytics — collect model year, mileage, fuel type, and condition across car listings

FAQ

What is Haraj? Haraj (حراج) is Saudi Arabia's largest classifieds marketplace, used for buying and selling cars, real estate, electronics, and general goods across Saudi Arabia, Kuwait, UAE, and Bahrain. This actor is an independent, third-party tool using Haraj's own public API — it is not affiliated with or endorsed by Haraj.

Why is priceSAR missing on some listings? Haraj lets sellers post without stating a price (common for "message me" listings). The actor omits the field entirely rather than showing a fake 0.

What's the difference between search and browse? search matches a free-text keyword against listing titles/descriptions (optionally narrowed by category/city/price). browse returns listings for a category and/or city (or the site-wide latest feed if neither is set) without requiring a keyword.

Is Jobs a supported category? Haraj's Jobs section (وظائف) is powered by a separate service that isn't reachable through the same public search/browse API used for the rest of the site, so it isn't included in the category dropdown. Individual job posts that also surface through keyword search or a specific seller's listings are still returned (with a populated job object) when found that way.

Will maxItems always be fully delivered? Not always, and this is expected. Haraj's own pagination only exposes a finite window of unique listings for a given search/browse request before it starts repeating already-seen listings. The unfiltered site-wide "latest" feed (browse with no category/city) has the smallest window, typically a few hundred listings; a specific keyword search or a category/city-scoped browse typically goes deeper. When a run hits this plateau it stops rather than looping forever, and reports the actual delivered count vs. the requested maxItems in the run's status message.

What's the difference between city and cities? city restricts results to exactly one city/region. cities (mode=search, browse) restricts to ANY of several cities/regions at once — useful for e.g. "show me listings in the three largest cities" in a single run instead of three separate runs. If both are set, a record needs to match only one of the two to be included (OR), not both.

What's neighborhood and how is it different from city? city/cities match Haraj's 21 top-level regions (e.g. "الرياض" Riyadh, the whole metro area). neighborhood matches Haraj's finer per-listing town/district tag (the geoCity output field — e.g. "الدرعية" Diriyah, a specific district within Riyadh). It's free-text (not a dropdown) because that value set runs into the hundreds and isn't stable enough to curate — enter the value exactly as it appears in a listing's own geoCity field. When combined with city/cities, a listing must satisfy both (AND).

What's carBodyType and how does it relate to category/subTag? carBodyType is a curated 12-value dropdown for a car's body style (sedan, SUV, hatchback, pickup, etc.). When more than one of carBodyType/subTag/category is set, carBodyType takes priority for upstream narrowing — the others still apply afterward as extra checks (e.g. carBodyType="سيدان" + subTag="تويوتا" correctly returns only Toyota sedans). It's most useful set alone or combined with city/category, since most body types already imply a brand-agnostic style search.

What's subTag and how is it different from category? category is one of Haraj's 20 top-level sections (e.g. "حراج السيارات" Cars). subTag is any finer node in Haraj's own tag tree attached to a listing — a specific brand ("تويوتا" Toyota) or model ("كامري" Camry). It's free-text because that tree runs into the thousands and isn't a stable curated set. When both category and subTag are set, subTag takes priority for upstream narrowing — category still applies afterward as an extra check (harmless when the two are consistent, e.g. Cars + Toyota; returns 0 results if they contradict, e.g. Real Estate + Toyota).

What does mode=trending return? Not listings — it's Haraj's own site-wide trending-search-keywords feed (what people are searching for over the last trendingRangeDays days), useful for spotting a hot keyword before running a search. Haraj's endpoint only has data for 1-14 day windows; values outside that range are clamped.