# Aqar — Saudi Arabia real-estate marketplace (sa.aqar.fm, sale + rent, SAR)

> Search Saudi Arabia's largest property marketplace by category (66 of them, each pairing a property type with sale/rent/booking), city, district, price, area, bedrooms, bathrooms, building age, street width, furnishing, amenities, advertiser type and free Arabic or English text. Every row carries the price WITH ITS PERIOD — Saudi rent is normally quoted per year, and this engine says so on each row instead of leaving a caller to assume monthly. Rows also carry the real first-publication time separately from the advertiser's bump time, coordinates, the REGA ad licence number and the advertising office.
> ReefAPI engine `aqar` · 9 endpoints · clean JSON, no scraping or browsers to manage.

## How to call
- **Endpoint:** `POST https://api.reefapi.com/aqar/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 except verified SHEIN NOT_FOUND on product/detail and price (4 credits).
- **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). Send the key as `Authorization: Bearer <key>`, or put it in the URL (`?key=<key>`) when the client has no header field, as ChatGPT does.

## Endpoints

### POST https://api.reefapi.com/aqar/v1/search — 2 credits
Search Saudi Arabia's largest property marketplace by category (66 of them, each pairing a property type with sale/rent/booking), city, district, price, area, bedrooms, bathrooms, building age, street width, furnishing, amenities, advertiser type and free Arabic or English text. Every row carries the price WITH ITS PERIOD — Saudi rent is normally quoted per year, and this engine says so on each row instead of leaving a caller to assume monthly. Rows also carry the real first-publication time separately from the advertiser's bump time, coordinates, the REGA ad licence number and the advertising office.

**Parameters:**
- `category` (enum, optional) — Property type AND deal type in one value, exactly as aqar models it — 'apartment-for-rent' and 'apartment-for-sale' are two different categories, not one category plus a flag. 66 values, from 'villa-for-sale' to 'communication-towers-for-rent'. The numeric id the source uses is accepted too. Omit it (or pass 'all-real-estates') to search everything. [one of: all-real-estates, apartment-for-rent, apartment-for-sale, apartments-for-booking, banks-and-atms-for-rent, banks-and-atms-for-sale, big-flat-for-rent, building-for-rent, building-for-sale, chalet-for-rent, chalets-for-booking, cinemas-for-rent, cinemas-for-sale, communication-towers-for-rent, communication-towers-for-sale, complexes-for-rent, complexes-for-sale, factories-for-rent, factories-for-sale, farm-for-sale, farms-for-booking, farms-for-rent, flat-for-sale, halls-for-booking, hospitals-for-rent, hospitals-for-sale, hotels-for-rent, hotels-for-sale, kiosks-for-rent, kiosks-for-sale, land-for-rent, land-for-sale, lounge-for-rent, lounge-for-sale, lounges-for-booking, office-for-rent, offices-for-sale, other, parking-for-rent, parking-for-sale, power-stations-for-rent, power-stations-for-sale, room-for-rent, rooms-for-sale, schools-for-rent, schools-for-sale, small-house-for-rent, small-house-for-sale, stations-for-rent, stations-for-sale, store-for-rent, store-for-sale, studios-for-booking, studios-for-rent, studios-for-sale, tent-for-rent, tents-for-booking, towers-for-rent, towers-for-sale, villa-for-rent, villa-for-sale, villas-for-booking, warehouse-for-rent, warehouses-for-sale, workshops-for-rent, workshops-for-sale]
- `city` (string, optional) — City name in English ('riyadh', 'jeddah', 'al khobar'), in Arabic ('الرياض'), or the source's numeric city_id. 96 cities carry stock; Riyadh 83,837 and Jeddah 41,570 are most of the market. Use the `cities` action for the full live list with counts.
- `district_id` (integer, optional) — Narrow to one district (neighbourhood). Get ids and live counts from the `districts` action — e.g. An Narjis in Riyadh is 600 with 1,975 listings.
- `direction_id` (integer, optional) — Narrow to one quadrant of a city (North/East/West/South). Ids come from `districts`; North Riyadh is 4 with 10,720 listings.
- `keyword` (string, optional) — Free text matched against the advertiser's own description. Arabic works and is what most listings are written in — 'فيلا' returned 1,420 of the 22,758 Riyadh rentals in the measurement. English text only matches the minority of listings with an English body.
- `price_min` (number, optional) — Lowest price, in SAR, in the listing's own period.
- `price_max` (number, optional) — Highest price, in SAR. ⚠️ Saudi rent is normally quoted PER YEAR — a 60,000 ceiling on 'apartment-for-rent' means 60,000 a year, not a month. Each row says which with `price_period`.
- `rent_period` (enum, optional) — Only keep listings priced per day / per month / per year. Most Saudi rentals are yearly; daily stock is holiday lets. Note the source also leaves this unset on many rows, and those rows are excluded when you filter on it. [one of: daily, monthly, yearly]
- `area_min` (number, optional) — Smallest built/plot area in square metres.
- `area_max` (number, optional) — Largest area in square metres.
- `meter_price_min` (number, optional) — Lowest price per square metre, in SAR. Often null on rentals.
- `meter_price_max` (number, optional) — Highest price per square metre, in SAR.
- `beds_min` (integer, optional) — At least this many bedrooms.
- `rooms_min` (integer, optional) — At least this many rooms in total.
- `livings_min` (integer, optional) — At least this many living rooms / salons.
- `bathrooms_min` (integer, optional) — At least this many bathrooms.
- `age_max` (integer, optional) — Building age ceiling in years. 0 means brand new.
- `street_width_min` (number, optional) — Minimum width in metres of the street the property faces — a standard Saudi land/villa criterion.
- `furnished` (enum, optional) — Only furnished (true) or only unfurnished (false). [one of: true, false]
- `has_image` (enum, optional) — Only listings with photos. 20,151 of the 22,758 control rows had at least one. [one of: true, false]
- `has_video` (enum, optional) — Only listings with a walkthrough video — 9,304 of 22,758 in the control. [one of: true, false]
- `verified` (enum, optional) — Only aqar-verified listings. ⚠️ Measured near-constant: 22,253 of 22,758 control rows are already verified, so this narrows almost nothing. [one of: true, false]
- `elevator` (enum, optional) — Only buildings with a lift. [one of: true, false]
- `pool` (enum, optional) — Only properties with a pool. [one of: true, false]
- `basement` (enum, optional) — Only properties with a basement. [one of: true, false]
- `duplex` (enum, optional) — Only duplex units. [one of: true, false]
- `near_metro` (enum, optional) — Only properties the advertiser flagged as near a metro station. [one of: true, false]
- `seller_type` (enum, optional) — Who is advertising. In the control query 4,206 of 22,758 rows were offices/agencies and 18,552 individuals. [one of: office, individual]
- `user_id` (integer, optional) — Only this advertiser's stock. The id comes back on every row as `seller.user_id` and is what the `agent` action takes.
- `created_after_days` (integer, optional) — 🔴 The honest way to ask for NEW listings on this source: keep only ads first published within N days. Measured on the Riyadh rental control — 7 days → 1,775 of 22,758, 30 days → 7,052. Prefer this over sorting, because the source refuses to sort by creation date.
- `bumped_after_days` (integer, optional) — Keep only ads the advertiser re-promoted within N days. This is activity, not newness.
- `sort` (enum, optional, default "relevance") — Result order. Only these were measured to actually reorder the set; 'newest' and 'oldest' are accepted as courtesy aliases and mapped to the bump order with a warning, because the source accepts a creation-date sort and then ignores it (ascending and descending return identical rows). [one of: relevance, recently_bumped, least_recently_bumped, price_asc, price_desc, area_asc, area_desc]
- `max_results` (integer, optional, default 70) — How many rows to return. The source serves at most 70 per request — measured, and it never says so: size=100/200/500/1000 all returned exactly 70 and an identical body — so bigger asks are walked across pages, 70 at a time, inside the request budget.
- `offset` (integer, optional, default 0) — Skip this many rows before collecting. There is no deep-paging ceiling on this source: offsets of 10,000 and 20,000 returned fresh rows, and an offset past the total returns an empty list instead of repeating the last page.
- `lang` (enum, optional, default "ar") — Which description to put in the `description` field. Both `description_ar` and `description_en` are always returned when the advertiser wrote them; most listings are Arabic-only. [one of: ar, en]
- `include_pii` (enum, optional, default "false") — Include the advertiser's phone number and (on `detail`) the deed owner fields. Off by default. Measured 2026-10-06: the source withholds these from anonymous callers anyway (`phone` comes back as 0), so this flag mostly future-proofs the default. [one of: true, false]

**Returns:** `{rows[], summary, filters_applied}`. Each row: id, url, category + category_id, listing_kind (rent/sale/booking), description (+ description_ar / description_en), `title` — ⚠️ the source publishes NO title field, so this is the FIRST LINE of the advertiser's own description, verbatim, including any emphasis markers they typed — **price + currency + price_period (daily|monthly|yearly) + price_period_source + price_per_year**, meter_price, instalments, area_sqm, plot width/length, street_width_m, bedrooms, rooms, living_rooms, bathrooms, floor, age_years, property_type{villa_type, apartment_type, floor_type}, features{furnished, elevator, pool, driver_room, maid_room, near_metro, …}, location{address, city, city_ar, city_id, district, district_id, direction_id, region, lat, lng}, **created_at (the real first-publication time) and refreshed_at (the advertiser's bump)**, updated_at, photos[] + photo_count, has_video, verified, is_promoted, is_auction, licensing{ad_license_number, rega_licensed, deed_number, deed_area_sqm}, seller{user_id, name, company_name, rating, identity_verified, rega_id, advertiser_type}. `summary` carries BOTH of the source's totals: `total_results` (retrievable) and `index_count` (the index's own count), plus `counts_disagree`, `page_size`, `pages_fetched`, `has_more`, `sort`, `currency`.

**Example request body:**
```json
{
  "category": "apartment-for-rent",
  "city": "riyadh",
  "price_max": 80000,
  "beds_min": 2,
  "sort": "recently_bumped",
  "max_results": 20
}
```

### POST https://api.reefapi.com/aqar/v1/detail — 1 credit
The full record for one listing: the complete description, every photo and its caption, walkthrough videos, view and like counts, the room-by-room breakdown, internal vs external area, the extended amenity set, whether the deed is constrained or pawned, the REGA / off-plan / Ministry-of-Tourism licence numbers with the plan and parcel numbers, the national address, the agent's commission terms, auction state and booking rules. Takes the numeric id from a search row, or a full aqar listing URL.

**Parameters:**
- `id` (string, required) — Listing id as `search` returns it in `rows[].id` (e.g. 6776778). A full aqar listing URL works too — the id is read out of its slug.
- `lang` (enum, optional, default "ar") — Which description goes in `description`. Both languages are returned when the advertiser wrote them. [one of: ar, en]
- `include_pii` (enum, optional, default "false") — Include the advertiser's phone and the deed owner name/id. Off by default; measured, the source returns these as null/0 to anonymous callers anyway. [one of: true, false]

**Returns:** Everything a search row carries plus: the full description, every photo with its captions, walkthrough video URLs, views and likes, rooms_detail (apartments, kitchens, men's/women's majlis, bedroom/guest/driver room counts, floors), areas{internal_sqm, external_sqm}, the extended feature set (balcony, master bedroom, separate water/electricity meters, fibre optic, private parking, bank finance accepted, laundry room, A/C type, wifi), encumbrances{is_constrained, is_pawned, obligations, guarantees}, licensing{ad_license_number, off_plan_license_number, rega_license_url, mot_license_number, plan_no, parcel_no, rega_total_price, rega_meter_price}, the national-address street, postal code and building number, nearby_services[] with coordinates, commission{type, percentage, amount}, auction{is_auction, biddable, ends_at}, booking{minimum_days, check_in_hour, check_out_hour} and the canonical `url`/`uri`. Seller phone and deed-owner fields only with `include_pii=true`.

**Example request body:**
```json
{
  "id": "6776778"
}
```

### POST https://api.reefapi.com/aqar/v1/count — 1 credit
How many properties match a filter combination, without parsing a single row — one small request, built for market sizing and for watching a segment over time. 🔴 It returns BOTH numbers the source publishes, because they disagree: `total_results` is what you can actually page through and `index_count` is the index's own tally. Measured gap: 22,666 vs 22,760 on Riyadh apartments, and 1 vs 3,952 on daily-rate stock.

**Parameters:**
- `category` (enum, optional) — Property type AND deal type in one value, exactly as aqar models it — 'apartment-for-rent' and 'apartment-for-sale' are two different categories, not one category plus a flag. 66 values, from 'villa-for-sale' to 'communication-towers-for-rent'. The numeric id the source uses is accepted too. Omit it (or pass 'all-real-estates') to search everything. [one of: all-real-estates, apartment-for-rent, apartment-for-sale, apartments-for-booking, banks-and-atms-for-rent, banks-and-atms-for-sale, big-flat-for-rent, building-for-rent, building-for-sale, chalet-for-rent, chalets-for-booking, cinemas-for-rent, cinemas-for-sale, communication-towers-for-rent, communication-towers-for-sale, complexes-for-rent, complexes-for-sale, factories-for-rent, factories-for-sale, farm-for-sale, farms-for-booking, farms-for-rent, flat-for-sale, halls-for-booking, hospitals-for-rent, hospitals-for-sale, hotels-for-rent, hotels-for-sale, kiosks-for-rent, kiosks-for-sale, land-for-rent, land-for-sale, lounge-for-rent, lounge-for-sale, lounges-for-booking, office-for-rent, offices-for-sale, other, parking-for-rent, parking-for-sale, power-stations-for-rent, power-stations-for-sale, room-for-rent, rooms-for-sale, schools-for-rent, schools-for-sale, small-house-for-rent, small-house-for-sale, stations-for-rent, stations-for-sale, store-for-rent, store-for-sale, studios-for-booking, studios-for-rent, studios-for-sale, tent-for-rent, tents-for-booking, towers-for-rent, towers-for-sale, villa-for-rent, villa-for-sale, villas-for-booking, warehouse-for-rent, warehouses-for-sale, workshops-for-rent, workshops-for-sale]
- `city` (string, optional) — City name in English ('riyadh', 'jeddah', 'al khobar'), in Arabic ('الرياض'), or the source's numeric city_id. 96 cities carry stock; Riyadh 83,837 and Jeddah 41,570 are most of the market. Use the `cities` action for the full live list with counts.
- `district_id` (integer, optional) — Narrow to one district (neighbourhood). Get ids and live counts from the `districts` action — e.g. An Narjis in Riyadh is 600 with 1,975 listings.
- `direction_id` (integer, optional) — Narrow to one quadrant of a city (North/East/West/South). Ids come from `districts`; North Riyadh is 4 with 10,720 listings.
- `keyword` (string, optional) — Free text matched against the advertiser's own description. Arabic works and is what most listings are written in — 'فيلا' returned 1,420 of the 22,758 Riyadh rentals in the measurement. English text only matches the minority of listings with an English body.
- `price_min` (number, optional) — Lowest price, in SAR, in the listing's own period.
- `price_max` (number, optional) — Highest price, in SAR. ⚠️ Saudi rent is normally quoted PER YEAR — a 60,000 ceiling on 'apartment-for-rent' means 60,000 a year, not a month. Each row says which with `price_period`.
- `rent_period` (enum, optional) — Only keep listings priced per day / per month / per year. Most Saudi rentals are yearly; daily stock is holiday lets. Note the source also leaves this unset on many rows, and those rows are excluded when you filter on it. [one of: daily, monthly, yearly]
- `area_min` (number, optional) — Smallest built/plot area in square metres.
- `area_max` (number, optional) — Largest area in square metres.
- `meter_price_min` (number, optional) — Lowest price per square metre, in SAR. Often null on rentals.
- `meter_price_max` (number, optional) — Highest price per square metre, in SAR.
- `beds_min` (integer, optional) — At least this many bedrooms.
- `rooms_min` (integer, optional) — At least this many rooms in total.
- `livings_min` (integer, optional) — At least this many living rooms / salons.
- `bathrooms_min` (integer, optional) — At least this many bathrooms.
- `age_max` (integer, optional) — Building age ceiling in years. 0 means brand new.
- `street_width_min` (number, optional) — Minimum width in metres of the street the property faces — a standard Saudi land/villa criterion.
- `furnished` (enum, optional) — Only furnished (true) or only unfurnished (false). [one of: true, false]
- `has_image` (enum, optional) — Only listings with photos. 20,151 of the 22,758 control rows had at least one. [one of: true, false]
- `has_video` (enum, optional) — Only listings with a walkthrough video — 9,304 of 22,758 in the control. [one of: true, false]
- `verified` (enum, optional) — Only aqar-verified listings. ⚠️ Measured near-constant: 22,253 of 22,758 control rows are already verified, so this narrows almost nothing. [one of: true, false]
- `elevator` (enum, optional) — Only buildings with a lift. [one of: true, false]
- `pool` (enum, optional) — Only properties with a pool. [one of: true, false]
- `basement` (enum, optional) — Only properties with a basement. [one of: true, false]
- `duplex` (enum, optional) — Only duplex units. [one of: true, false]
- `near_metro` (enum, optional) — Only properties the advertiser flagged as near a metro station. [one of: true, false]
- `seller_type` (enum, optional) — Who is advertising. In the control query 4,206 of 22,758 rows were offices/agencies and 18,552 individuals. [one of: office, individual]
- `user_id` (integer, optional) — Only this advertiser's stock. The id comes back on every row as `seller.user_id` and is what the `agent` action takes.
- `created_after_days` (integer, optional) — 🔴 The honest way to ask for NEW listings on this source: keep only ads first published within N days. Measured on the Riyadh rental control — 7 days → 1,775 of 22,758, 30 days → 7,052. Prefer this over sorting, because the source refuses to sort by creation date.
- `bumped_after_days` (integer, optional) — Keep only ads the advertiser re-promoted within N days. This is activity, not newness.

**Returns:** `{total_results, index_count, counts_disagree, count_gap, pages_at_70, currency, filters_applied}`.

**Example request body:**
```json
{
  "category": "villa-for-sale",
  "city": "jeddah"
}
```

### POST https://api.reefapi.com/aqar/v1/categories — 1 credit
The complete category vocabulary — 66 entries, each the pairing of a property type with sale, rent or booking — with the slug and numeric id that `search` and `count` take, in both Arabic and English, plus the search keywords the site itself associates with each one. Cheap lookup; call it once and cache.

**Parameters:** none

**Returns:** `rows[]` of {id, slug, name_en, name_ar, plural_en, plural_ar, path, keywords[]}, plus `summary.total_results`.

### POST https://api.reefapi.com/aqar/v1/cities — 1 credit
Every Saudi city that carries stock, with its numeric city_id and a LIVE listing count, optionally for one category. 96 cities at capture: Riyadh 83,837, Jeddah 41,570, Dammam 8,523. Also returns the 13 administrative regions. This is the cheapest way to size the market by city.

**Parameters:**
- `category` (enum, optional, default "all-real-estates") — Count cities for one category only. Omit for the whole catalogue. [one of: all-real-estates, apartment-for-rent, apartment-for-sale, apartments-for-booking, banks-and-atms-for-rent, banks-and-atms-for-sale, big-flat-for-rent, building-for-rent, building-for-sale, chalet-for-rent, chalets-for-booking, cinemas-for-rent, cinemas-for-sale, communication-towers-for-rent, communication-towers-for-sale, complexes-for-rent, complexes-for-sale, factories-for-rent, factories-for-sale, farm-for-sale, farms-for-booking, farms-for-rent, flat-for-sale, halls-for-booking, hospitals-for-rent, hospitals-for-sale, hotels-for-rent, hotels-for-sale, kiosks-for-rent, kiosks-for-sale, land-for-rent, land-for-sale, lounge-for-rent, lounge-for-sale, lounges-for-booking, office-for-rent, offices-for-sale, other, parking-for-rent, parking-for-sale, power-stations-for-rent, power-stations-for-sale, room-for-rent, rooms-for-sale, schools-for-rent, schools-for-sale, small-house-for-rent, small-house-for-sale, stations-for-rent, stations-for-sale, store-for-rent, store-for-sale, studios-for-booking, studios-for-rent, studios-for-sale, tent-for-rent, tents-for-booking, towers-for-rent, towers-for-sale, villa-for-rent, villa-for-sale, villas-for-booking, warehouse-for-rent, warehouses-for-sale, workshops-for-rent, workshops-for-sale]

**Returns:** `rows[]` of {city_id, name_en, name_ar, count, has_directions, uri} ordered by stock, `regions[]` of {admin_region_id, name_ar}, and `summary.total_results`.

**Example request body:**
```json
{
  "category": "villa-for-sale"
}
```

### POST https://api.reefapi.com/aqar/v1/districts — 1 credit
Every district (neighbourhood) of one city with a live listing count, plus the city's quadrants (North/East/West/South) with their own counts. These ids are what `search`'s `district_id` and `direction_id` take. Riyadh apartments split into 10,720 north / 7,678 east / 3,124 west, and An Narjis alone holds 1,975.

**Parameters:**
- `city` (string, required) — City name in English or Arabic, or the numeric city_id from `cities`.
- `category` (enum, optional, default "apartment-for-rent") — District counts are per category on this source, so pick the one you will search. [one of: all-real-estates, apartment-for-rent, apartment-for-sale, apartments-for-booking, banks-and-atms-for-rent, banks-and-atms-for-sale, big-flat-for-rent, building-for-rent, building-for-sale, chalet-for-rent, chalets-for-booking, cinemas-for-rent, cinemas-for-sale, communication-towers-for-rent, communication-towers-for-sale, complexes-for-rent, complexes-for-sale, factories-for-rent, factories-for-sale, farm-for-sale, farms-for-booking, farms-for-rent, flat-for-sale, halls-for-booking, hospitals-for-rent, hospitals-for-sale, hotels-for-rent, hotels-for-sale, kiosks-for-rent, kiosks-for-sale, land-for-rent, land-for-sale, lounge-for-rent, lounge-for-sale, lounges-for-booking, office-for-rent, offices-for-sale, other, parking-for-rent, parking-for-sale, power-stations-for-rent, power-stations-for-sale, room-for-rent, rooms-for-sale, schools-for-rent, schools-for-sale, small-house-for-rent, small-house-for-sale, stations-for-rent, stations-for-sale, store-for-rent, store-for-sale, studios-for-booking, studios-for-rent, studios-for-sale, tent-for-rent, tents-for-booking, towers-for-rent, towers-for-sale, villa-for-rent, villa-for-sale, villas-for-booking, warehouse-for-rent, warehouses-for-sale, workshops-for-rent, workshops-for-sale]

**Returns:** `{districts[], directions[], summary}` — districts carry {district_id, name_ar, name_en, count, direction{direction_id, name_ar, name_en}} and directions carry {direction_id, name_ar, name_en, count}.

**Example request body:**
```json
{
  "city": "riyadh",
  "category": "apartment-for-rent"
}
```

### POST https://api.reefapi.com/aqar/v1/price_history — 2 credits
Aqar's own half-yearly price series per district of a city, going back to 2015: for each period, how many deals were recorded and the average price per square metre. This is the market-trend dataset behind the site's district pages — one request returns every district of the city at once (Riyadh apartments: 137 KB covering the whole city). Use it for yield models, district ranking and time-series charts.

**Parameters:**
- `city` (string, required) — City name in English or Arabic, or the numeric city_id.
- `category` (enum, optional, default "apartment-for-rent") — Which market to chart. Series exist for the main residential categories. [one of: all-real-estates, apartment-for-rent, apartment-for-sale, apartments-for-booking, banks-and-atms-for-rent, banks-and-atms-for-sale, big-flat-for-rent, building-for-rent, building-for-sale, chalet-for-rent, chalets-for-booking, cinemas-for-rent, cinemas-for-sale, communication-towers-for-rent, communication-towers-for-sale, complexes-for-rent, complexes-for-sale, factories-for-rent, factories-for-sale, farm-for-sale, farms-for-booking, farms-for-rent, flat-for-sale, halls-for-booking, hospitals-for-rent, hospitals-for-sale, hotels-for-rent, hotels-for-sale, kiosks-for-rent, kiosks-for-sale, land-for-rent, land-for-sale, lounge-for-rent, lounge-for-sale, lounges-for-booking, office-for-rent, offices-for-sale, other, parking-for-rent, parking-for-sale, power-stations-for-rent, power-stations-for-sale, room-for-rent, rooms-for-sale, schools-for-rent, schools-for-sale, small-house-for-rent, small-house-for-sale, stations-for-rent, stations-for-sale, store-for-rent, store-for-sale, studios-for-booking, studios-for-rent, studios-for-sale, tent-for-rent, tents-for-booking, towers-for-rent, towers-for-sale, villa-for-rent, villa-for-sale, villas-for-booking, warehouse-for-rent, warehouses-for-sale, workshops-for-rent, workshops-for-sale]

**Returns:** `rows[]` of {district_id, district, series[]{period, year, half, deal_count, avg_meter_price}} plus `summary.total_results` (districts) and `summary.points` (data points), `summary.currency`.

**Example request body:**
```json
{
  "city": "riyadh",
  "category": "apartment-for-rent"
}
```

### POST https://api.reefapi.com/aqar/v1/agent — 1 credit
The public profile of one advertising office or private advertiser — company name, commercial registration, REGA/BML brokerage licence, rating, how many listings they have live and archived, followers, completed deals, when they joined and when they were last seen — together with their current stock in the same request. The `user_id` comes back on every search row.

**Parameters:**
- `user_id` (integer, required) — Advertiser id, as `search` returns it in `rows[].seller.user_id`.
- `max_results` (integer, optional, default 20) — How many of their live listings to return alongside the profile. The source serves at most 70 per request.
- `include_pii` (enum, optional, default "false") — Include the office phone. Off by default; the source returns null to anonymous callers. [one of: true, false]

**Returns:** `{agent{user_id, name, company_name, company_cr, about, logo, rating, identity_verified, verified, is_office, live_listings, archived_listings, followers, following, completed_deals, bml_license_number, bml_url, joined_at, last_seen_at, office_location{lat,lng}}, listings[], summary}`.

**Example request body:**
```json
{
  "user_id": 815188
}
```

### POST https://api.reefapi.com/aqar/v1/suggest — 1 credit
Place autocomplete straight from the site's own search box: type a partial Arabic or English place name and get the matching Saudi places back. Useful to turn a user's free text into a place before searching.

**Parameters:**
- `query` (string, required) — Partial place name, Arabic or English (at least two characters).

**Returns:** `rows[]` of {description, place_id} plus `summary.total_results`.

**Example request body:**
```json
{
  "query": "الرياض"
}
```

## 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=aqar
- Human docs page: https://reefapi.com/docs/aqar
- Overview page: https://reefapi.com/aqar-api
- Every ReefAPI API in one file (for your AI): https://reefapi.com/llms-full.txt