# Haraj API (حراج) — haraj.com.sa, Saudi Arabia's largest general classifieds site: search cars, real estate, phones, furniture, livestock and jobs by Arabic keyword, tag and city; read a full listing and its public comments; list one seller's ads; read the site's own trending keywords. Prices in Saudi riyal. No account, no browser. Ad text is returned as published, contacts included.

> 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.
> ReefAPI engine `haraj` · 6 endpoints · clean JSON, no scraping or browsers to manage.

## How to call
- **Endpoint:** `POST https://api.reefapi.com/haraj/v1/<action>` with a JSON body.
- **Auth:** header `x-api-key: <YOUR_REEFAPI_KEY>` — create one free (1,000 credits, no card): https://reefapi.com/signup
- **Response (every call):** `{ ok: boolean, data: ..., meta: { record_count, credits, ... }, error: { code, message } }` — branch on `ok`. Failed calls are free.
- **One key + one shared credit pool** across every ReefAPI API. Per-call credits are listed on each endpoint below.
- **Use it from an AI agent (MCP):** connect `https://api.reefapi.com/mcp` (remote streamable-http). Clients that add connectors by URL, such as ChatGPT and the Claude app, connect with OAuth 2.1 (the user pastes their key once on a ReefAPI page; discovery at `/.well-known/oauth-protected-resource/mcp`). Config files send the key as `Authorization: Bearer <key>`. `?key=<key>` in the URL also works as a last-resort fallback.

## Endpoints

### POST https://api.reefapi.com/haraj/v1/search — 1 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.

**Parameters:**
- `query` (string, 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` (string, 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` (array, optional) — Several tags at once; a listing matching any of them is served.
- `not_tag` (string, optional) — Exclude every listing carrying this tag. Measured to really remove them (zero overlap with the unfiltered control).
- `city` (string, 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` (array, optional) — Several cities at once.
- `only_with_image` (boolean, optional) — Only listings that carry photos.
- `only_with_video` (boolean, optional) — Only listings that carry a video.
- `hide_showrooms` (boolean, optional) — Drop dealer/showroom listings and keep private sellers.
- `order_by_newest_id` (boolean, optional) — Order strictly by listing id (newest posted first) instead of the site's own relevance order.
- `page` (integer, optional, default 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` (integer, optional, default 30) — Listings per page, 1-60. Above 60 the source silently falls back to its own small default, so this engine rejects it instead.
- `lang` (enum, optional, default "ar") — Language Haraj should answer in. Titles come back translated where the site has a translation; city names stay Arabic either way. [one of: ar, en, ur, id, tl, bn, hi, fr]

**Returns:** results[]{listing_id, title, url, url_path, price (integer SAR, null when the listing publishes none or when the row's two price witnesses disagree), price_display (the source's own formatted string), currency, description, description_html, seller_username, seller_id, seller_url, city, geo_city, neighborhood, geohash, tags[], tag_filters[], post_type, is_promoted, is_active, has_image, has_video, image, images[], image_count, comment_count, comments_enabled, comment_status, up_rank, down_rank, posted_at, updated_at, posted_at_epoch, updated_at_epoch, car_info{model, mileage, fuel, gear, condition, is_4wd, sell_or_waiver, car_or_related, bank}, real_estate_info{rega_advertiser_registration_number, rega_authorization_number}, jobs_info{offer_type, experience_level, contract_type, qualification, commercial_register_number}, attributes[]{key, value}, badges[]{note, icon, icon_url, link}, store{name, label, link, offers_enabled, escrow_available}}, count, page, per_page, page_overlaps_previous, has_next_page, price_disagreements

**Example request body:**
```json
{
  "query": "كامري",
  "per_page": 20
}
```

### POST https://api.reefapi.com/haraj/v1/detail — 1 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.

**Parameters:**
- `listing_id` (string, 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` (enum, optional, default "ar") — Language Haraj should answer in. Titles come back translated where the site has a translation; city names stay Arabic either way. [one of: ar, en, ur, id, tl, bn, hi, fr]

**Returns:** listing{…same shape as a search row…}, listings[]{…}, count, requested_ids[], missing_ids[]

**Example request body:**
```json
{
  "listing_id": "189640871"
}
```

### POST https://api.reefapi.com/haraj/v1/user_listings — 1 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 is identified by the handle and numeric id Haraj publishes on each ad.

**Parameters:**
- `username` (string, required) — The seller's public Haraj handle, exactly as it appears in a listing's `seller_username`.
- `city` (string, 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` (array, optional) — Several cities at once.
- `tag` (string, 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` (string, optional) — Exclude every listing carrying this tag. Measured to really remove them (zero overlap with the unfiltered control).
- `only_with_image` (boolean, optional) — Only listings that carry photos.
- `only_with_video` (boolean, optional) — Only listings that carry a video.
- `order_by_newest_id` (boolean, optional) — Order strictly by listing id (newest posted first) instead of the site's own relevance order.
- `page` (integer, optional, default 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` (integer, optional, default 30) — Listings per page, 1-60. Above 60 the source silently falls back to its own small default, so this engine rejects it instead.
- `lang` (enum, optional, default "ar") — Language Haraj should answer in. Titles come back translated where the site has a translation; city names stay Arabic either way. [one of: ar, en, ur, id, tl, bn, hi, fr]

**Returns:** results[]{listing_id, title, url, url_path, price (integer SAR, null when the listing publishes none or when the row's two price witnesses disagree), price_display (the source's own formatted string), currency, description, description_html, seller_username, seller_id, seller_url, city, geo_city, neighborhood, geohash, tags[], tag_filters[], post_type, is_promoted, is_active, has_image, has_video, image, images[], image_count, comment_count, comments_enabled, comment_status, up_rank, down_rank, posted_at, updated_at, posted_at_epoch, updated_at_epoch, car_info{model, mileage, fuel, gear, condition, is_4wd, sell_or_waiver, car_or_related, bank}, real_estate_info{rega_advertiser_registration_number, rega_authorization_number}, jobs_info{offer_type, experience_level, contract_type, qualification, commercial_register_number}, attributes[]{key, value}, badges[]{note, icon, icon_url, link}, store{name, label, link, offers_enabled, escrow_available}}, count, page, per_page, page_overlaps_previous, has_next_page, price_disagreements, username

**Example request body:**
```json
{
  "username": "abdullah-aljalal"
}
```

### POST https://api.reefapi.com/haraj/v1/browse — 1 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.

**Parameters:**
- `tag` (string, 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` (string, optional) — Exclude every listing carrying this tag. Measured to really remove them (zero overlap with the unfiltered control).
- `city` (string, 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` (array, optional) — Several cities at once.
- `only_with_image` (boolean, optional) — Only listings that carry photos.
- `only_with_video` (boolean, optional) — Only listings that carry a video.
- `order_by_newest_id` (boolean, optional) — Order strictly by listing id (newest posted first) instead of the site's own relevance order.
- `page` (integer, optional, default 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` (integer, optional, default 30) — Listings per page, 1-60. Above 60 the source silently falls back to its own small default, so this engine rejects it instead.
- `lang` (enum, optional, default "ar") — Language Haraj should answer in. Titles come back translated where the site has a translation; city names stay Arabic either way. [one of: ar, en, ur, id, tl, bn, hi, fr]

**Returns:** results[]{listing_id, title, url, url_path, price (integer SAR, null when the listing publishes none or when the row's two price witnesses disagree), price_display (the source's own formatted string), currency, description, description_html, seller_username, seller_id, seller_url, city, geo_city, neighborhood, geohash, tags[], tag_filters[], post_type, is_promoted, is_active, has_image, has_video, image, images[], image_count, comment_count, comments_enabled, comment_status, up_rank, down_rank, posted_at, updated_at, posted_at_epoch, updated_at_epoch, car_info{model, mileage, fuel, gear, condition, is_4wd, sell_or_waiver, car_or_related, bank}, real_estate_info{rega_advertiser_registration_number, rega_authorization_number}, jobs_info{offer_type, experience_level, contract_type, qualification, commercial_register_number}, attributes[]{key, value}, badges[]{note, icon, icon_url, link}, store{name, label, link, offers_enabled, escrow_available}}, count, page, per_page, page_overlaps_previous, has_next_page, price_disagreements

**Example request body:**
```json
{
  "tag": "حراج السيارات",
  "per_page": 10
}
```

### POST https://api.reefapi.com/haraj/v1/comments — 1 credit
Every public comment on one Haraj listing, by listing number or URL, oldest first: comment id, the commenter's public Haraj handle, numeric id and profile link, the comment text exactly as posted (prices, offers and phone numbers included), the date, and the id of the comment it replies to. Also the de-duplicated list of people who commented, the listing's own comment count and its title. Comments Haraj hides from the public (private replies, deleted ones) are kept, flagged `is_hidden`, with Haraj's own placeholder text. A listing with no comments is an empty list; a removed listing answers NOT_FOUND.

**Parameters:**
- `listing_id` (string, required) — ONE Haraj listing number, or its haraj.com.sa listing URL (https://haraj.com.sa/11169318604/… is listing 169318604).
- `sort` (enum, optional, default "oldest") — Order of the returned comments. [one of: oldest, newest]

**Returns:** comments[]{comment_id, author_username, author_id, author_url, author_level, author_is_new_user, text, status, is_hidden, delete_reason, seq_id, posted_at, posted_at_epoch, is_reply, reply_to_comment_id, mention{contains_mention, username, handle, user_id}}, count, visible_count, hidden_count, reply_count, commenters[]{username, user_id, url, comments, is_listing_author}, listing_comment_count (the listing's own published count, visible comments only), comments_enabled, listing_id, listing_url, listing_title, seller_username, sort, pages_read, truncated

**Example request body:**
```json
{
  "listing_id": "169318604"
}
```

### POST https://api.reefapi.com/haraj/v1/trending_keywords — 1 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.

**Parameters:**
- `days` (integer, optional, default 7) — How many days back to score the trending keywords over.
- `lang` (enum, optional, default "ar") — Language Haraj should answer in. Titles come back translated where the site has a translation; city names stay Arabic either way. [one of: ar, en, ur, id, tl, bn, hi, fr]

**Returns:** keywords[]{keyword, score}, count, days

**Example request body:**
```json
{
  "days": 7
}
```

## At scale
- **Volume:** 5M+ requests a day, measured at 60 requests a second across the fleet with no
  central bottleneck. Per-key limits are raised for high-volume accounts; volume pricing on request.
- **Missing a source:** tell us a site we do not cover and it becomes an engine. A customer asked
  for bestprice.gr on 21 Sep 2026 and it was in the catalog on 22 Sep.
- **Support:** 2 minute median time from a question in the live chat to the first answer. Setup
  help included, no support tier to buy.
- **One key, one credit pool** across every API. No per-site plans, no separate subscriptions.

## More
- Try it live, no code: https://reefapi.com/playground?engine=haraj
- Human docs page: https://reefapi.com/docs/haraj
- Overview page: https://reefapi.com/haraj-api
- Every ReefAPI API in one file (for your AI): https://reefapi.com/llms-full.txt
