Looking for the overview — what this API returns, what it costs, and a call you can run without a key? See the Haraj API page →

docs / haraj

Haraj

base /haraj/v15 endpoints

post/haraj/v1/search1 credit

Search Haraj listings by Arabic keyword and/or tag, up to 60 per page: listing id, title, URL, price in riyal with the source's own formatted string beside it, the ad body, city / neighbourhood / geohash, tags, photos, comment counts, posting and update times, the public seller handle, and the category blocks Haraj publishes (car details, REGA real-estate licence numbers, job offer details, free-form attributes). Filter by city, tag, excluded tag, photos-only, video-only and private-sellers-only, and order strictly by newest listing id. Give at least `query` or `tag`. Listings are written in Arabic — an Arabic keyword matches far more than its Latin spelling.

Parameter		Allowed / range	Description
query	optional	—	Keyword to search for, in the ad's own language. Haraj listings are written in Arabic, so an Arabic keyword (كامري, شقة للايجار, ايفون) matches far more than its Latin spelling. Either query or tag is required.
tag	optional	—	Haraj section/tag to restrict to, spelled as the site spells it (it is the value returned in each listing's `tags`). Either query or tag is required; both together narrow the search.
tags	optional	—	Several tags at once; a listing matching any of them is served.
not_tag	optional	—	Exclude every listing carrying this tag. Measured to really remove them (zero overlap with the unfiltered control).
city	optional	—	Restrict to one city, spelled as the site spells it in a listing's `city` field (الرياض, جده, الشرقيه, مكه, المدينة, القصيم…). An unknown city is an honest empty result, not a swallowed filter.
cities	optional	—	Several cities at once.
only_with_image	optional	—	Only listings that carry photos.
only_with_video	optional	—	Only listings that carry a video.
hide_showrooms	optional	—	Drop dealer/showroom listings and keep private sellers.
order_by_newest_id	optional	—	Order strictly by listing id (newest posted first) instead of the site's own relevance order.
page = 1	optional	1–	1-based page number. Note that haraj.com.sa serves the same first page for page 0 and page 1, and that consecutive pages overlap by about one listing because the source over-fetches one row per page.
per_page = 30	optional	1–60	Listings per page, 1-60. Above 60 the source silently falls back to its own small default, so this engine rejects it instead.
lang = ar	optional	ar · en · ur · id · tl · bn · hi · fr	Language Haraj should answer in. Titles come back translated where the site has a translation; city names stay Arabic either way.

Try in playground →

post/haraj/v1/detail1 credit

One Haraj listing (or up to 20 at once) by listing number or listing URL, with every field the search rows carry: the full ad body, price, city and neighbourhood, all photos, tags, comment counts, posting and update times, the public seller handle, and the car / real-estate / jobs blocks where Haraj publishes them. A listing that was removed or never existed answers NOT_FOUND.

Parameter		Allowed / range	Description
listing_id	required	—	A Haraj listing number, or a haraj.com.sa listing URL. Up to 20 comma-separated ids may be given in one call.
lang = ar	optional	ar · en · ur · id · tl · bn · hi · fr	Language Haraj should answer in. Titles come back translated where the site has a translation; city names stay Arabic either way.

Try in playground →

post/haraj/v1/user_listings1 credit

Every currently live ad posted by one Haraj seller, newest first, by the seller's public handle: the same listing shape as search, with city, tag and photo filters and paging. Useful for watching a dealer's inventory or a shop's price moves. The seller's name and contact details are never returned — only the public handle and numeric id the listing page itself shows.

Parameter		Allowed / range	Description
username	required	—	The seller's public Haraj handle, exactly as it appears in a listing's `seller_username`.
city	optional	—	Restrict to one city, spelled as the site spells it in a listing's `city` field (الرياض, جده, الشرقيه, مكه, المدينة, القصيم…). An unknown city is an honest empty result, not a swallowed filter.
cities	optional	—	Several cities at once.
tag	optional	—	Haraj section/tag to restrict to, spelled as the site spells it (it is the value returned in each listing's `tags`). Either query or tag is required; both together narrow the search.
not_tag	optional	—	Exclude every listing carrying this tag. Measured to really remove them (zero overlap with the unfiltered control).
only_with_image	optional	—	Only listings that carry photos.
only_with_video	optional	—	Only listings that carry a video.
order_by_newest_id	optional	—	Order strictly by listing id (newest posted first) instead of the site's own relevance order.
page = 1	optional	1–	1-based page number. Note that haraj.com.sa serves the same first page for page 0 and page 1, and that consecutive pages overlap by about one listing because the source over-fetches one row per page.
per_page = 30	optional	1–60	Listings per page, 1-60. Above 60 the source silently falls back to its own small default, so this engine rejects it instead.
lang = ar	optional	ar · en · ur · id · tl · bn · hi · fr	Language Haraj should answer in. Titles come back translated where the site has a translation; city names stay Arabic either way.

Try in playground →

post/haraj/v1/browse1 credit

Browse the newest Haraj listings without a keyword — the whole site, one tag, one city, or a tag and city together — in the site's own newest-first order. Same listing shape as search. Use this to poll a section for new ads; use `search` when you have a keyword.

Parameter		Allowed / range	Description
tag	optional	—	Haraj section/tag to restrict to, spelled as the site spells it (it is the value returned in each listing's `tags`). Either query or tag is required; both together narrow the search.
not_tag	optional	—	Exclude every listing carrying this tag. Measured to really remove them (zero overlap with the unfiltered control).
city	optional	—	Restrict to one city, spelled as the site spells it in a listing's `city` field (الرياض, جده, الشرقيه, مكه, المدينة, القصيم…). An unknown city is an honest empty result, not a swallowed filter.
cities	optional	—	Several cities at once.
only_with_image	optional	—	Only listings that carry photos.
only_with_video	optional	—	Only listings that carry a video.
order_by_newest_id	optional	—	Order strictly by listing id (newest posted first) instead of the site's own relevance order.
page = 1	optional	1–	1-based page number. Note that haraj.com.sa serves the same first page for page 0 and page 1, and that consecutive pages overlap by about one listing because the source over-fetches one row per page.
per_page = 30	optional	1–60	Listings per page, 1-60. Above 60 the source silently falls back to its own small default, so this engine rejects it instead.
lang = ar	optional	ar · en · ur · id · tl · bn · hi · fr	Language Haraj should answer in. Titles come back translated where the site has a translation; city names stay Arabic either way.

Try in playground →

post/haraj/v1/trending_keywords1 credit

Haraj's own trending search keywords over the last N days, in Arabic, with the site's own score for each — what Saudi buyers are actually searching for right now.

Parameter		Allowed / range	Description
days = 7	optional	1–90	How many days back to score the trending keywords over.
lang = ar	optional	ar · en · ur · id · tl · bn · hi · fr	Language Haraj should answer in. Titles come back translated where the site has a translation; city names stay Arabic either way.

Try in playground →

Example request · search

curl -X POST https://api.reefapi.com/haraj/v1/search \
  -H "x-api-key: $REEF_KEY" \
  -H "content-type: application/json" \
  -d '{"query":"كامري","per_page":20}'

Response shape

{
  "ok": true,
  "data": { /* the result */ },
  "meta": {
    "latency_ms": 240,
    "record_count": 12,
    "completeness_pct": 100
  },
  "error": null
}

Built for volume

5M+ requests a day

Measured at 60 requests a second across the fleet, with no central bottleneck. Volume pricing is on request, and per-key limits are raised for high-volume accounts.

Missing a source?

We build it

Tell us a site we do not cover yet and it becomes an engine. A customer asked for bestprice.gr on a Sunday and it was in the catalog the next day.

Support

2 minute median reply

Median time from a question in the live chat to the first answer, measured across every answered conversation. Setup help included, no support tier to buy.

One key, one balance

Every API included

No per-site plans and no separate subscriptions. One key and one credit pool across the whole catalog, so adding a source costs nothing up front.

Planning something large? Tell us the volume and the sources and we will come back with what it costs and what we would have to build.