Aqar API & Scraper
The Aqar API returns sa.aqar.fm, Saudi Arabia's largest real-estate marketplace, as clean JSON in nine actions.
🤖 Using an AI assistant? Copy this link into ChatGPT / Claude / Cursor — it reads every endpoint and parameter instantly and tells you if this API fits your use case.
search filters live stock by 66 categories - and a category on Aqar pairs the property type with the deal, so apartment-for-rent and apartment-for-sale are two different values rather than one value plus a flag - then by city, district, city quadrant, price, price per square metre, area, bedrooms, rooms, living rooms, bathrooms, building age, street width, furnishing, lift, pool, basement, duplex, metro proximity, advertiser type, a specific advertiser, how recently the ad was first published, how recently it was bumped, and free text in Arabic or English. Every row carries the listing id and URL, the category and whether it is a sale, a rent or a daily booking, the asking price with its currency, the area in square metres, bedrooms, rooms, living rooms, bathrooms, floor, building age, plot width and length, street width, the amenity set, the full address with district, city, region and exact coordinates, the REGA advertisement licence number, the deed number and deed area, the advertising office with its rating and licence, every photo, and two separate timestamps: when the ad was first published and when the advertiser last bumped it. detail opens one listing in full - the complete description in Arabic and English where the advertiser wrote both, every photo with its caption, walkthrough videos, the view and like counts, the room-by-room breakdown, internal versus external area, the extended amenity set down to separate water and electricity meters and fibre optic, whether the deed is constrained or pawned, the off-plan and Ministry-of-Tourism licence numbers with the plan and parcel numbers, the national address, the agent's commission terms, the auction state and the booking rules. count sizes a segment in a 56-byte request. categories, cities and districts hand you the site's own vocabulary with live counts - 66 categories in both languages, 96 cities, 152 Riyadh districts and the four city quadrants - so you never guess an id. price_history is the one that is hard to get anywhere else: Aqar's own half-yearly series of recorded deal count and average price per square metre for every district of a city, going back to 2015, 124 Riyadh districts in a single request. agent returns an office's public profile and its live stock together. suggest turns half-typed Arabic into a Saudi place. Four things we publish rather than hide. First, rent in Saudi Arabia is normally quoted per YEAR - 27,149 listings site-wide are priced yearly against 3,952 daily and 5 monthly - so every row states its price_period as a word, and when the advertiser left the period unset, price_period_source says the period came from the category default rather than from them. Second, Aqar publishes two different totals for the same query and they disagree, so both are returned: total_results is what you can actually page through and index_count is the index's own tally, with the gap named. Third, newest on this marketplace means last bumped, not newly listed - so the recency sort is called recently_bumped, the real publication date is on every row as created_at, and created_after_days filters on it. Fourth, there is no deep-paging ceiling here: offsets of 10,000 and 20,000 returned fresh rows, a full walk of a 186-row query returned 186 unique ids, and an offset past the end returns an empty list instead of repeating the last page. On 2026-10-06, eighteen live searches across ten cities and eleven categories returned 417 rows with id, URL, category, price, currency, area, district, region, coordinates, deed number, publication date and bump date filled on 417 of 417. No Aqar account, no browser - one ReefAPI key and the standard { ok, data, meta, error } envelope.
What is on Aqar right now - and how much of each slice an API call can reach
Measured on 2026-10-06 with the count action. Aqar publishes two totals for every query and they do not match, so both are shown: the middle column is the index's own tally and the right-hand column is what paging can actually reach. The right-hand number is the one to build against - and unlike most marketplaces, there is no paging ceiling cutting it short.
| Slice | Index count | Reachable by paging |
|---|---|---|
| Everything, all categories, all cities | 174,523 | 168,956 |
| Apartments for sale | 42,413 | 41,582 |
| Apartments for rent | 34,519 | 34,355 |
| Land for sale | 26,468 | 26,338 |
| Villas for sale | 25,691 | 25,467 |
| Villas for rent | 5,322 | 5,298 |
| Buildings for sale | 4,709 | 4,695 |
| Shops for rent | 2,398 | 2,393 |
| Apartments for daily booking | 2,441 | 2,438 |
| Offices for rent | 1,671 | 1,663 |
| Rooms for rent | 1,377 | 1,371 |
| Farms for sale | 849 | 844 |
| Riyadh, every category | 83,837 | see per-query total |
| Jeddah, every category | 41,570 | see per-query total |
| Dammam / Al Khobar / Medina / Mecca | 8,523 / 8,456 / 5,124 / 4,115 | see per-query total |
The two columns diverge most where a separate booking funnel sits behind the category: a daily-rate filter reported 3,952 in the index and exactly 1 reachable row. That is why both numbers are returned on every search and count response instead of one averaged figure.
Real request and response JSON
Captured from the indexed primary action, search, on .
{
"method": "POST",
"url": "https://api.reefapi.com/aqar/v1/search",
"headers": {
"x-api-key": "$REEF_KEY",
"content-type": "application/json"
},
"body": {
"category": "apartment-for-rent",
"city": "riyadh",
"price_max": 80000,
"beds_min": 2,
"sort": "recently_bumped",
"max_results": 20
}
}{
"ok": true,
"meta": {
"api": "aqar",
"endpoint": "search",
"mode": "live",
"latency_ms": 439,
"record_count": 20,
"bytes": 87218,
"cache_hit": false,
"completeness_pct": 100,
"stop_reason": "complete",
"warnings": [
"the source publishes two different totals for this query: 13456 rows are actually retrievable and its index reports 13513. `total_results` is the retrievable one."
],
"charged_credits": 1,
"version": "1.0.0",
"request_id": "a69875db9ec7445c",
"queue_ms": 20.2,
"fetched_at": "2026-10-06T14:47:16.739Z"
},
"data": {
"rows": [
{
"id": 6852864,
"url": "https://sa.aqar.fm/listing/6852864",
"category_id": 1,
"category": "apartment-for-rent",
"listing_kind": "rent",
"title": "🏡 luxury apartment for annual rent – 2 bedrooms, al arid district, a0713 – ready to move in, flexible payment options available",
"description": "🏡شقة فاخرة للإيجار السنوي غرفتين حي العارض A0713 جاهزة للسكن توجد دفعات مرنه\n\n📞 للتواصل 9200032342\nبتصاميم المساكن العصرية والتشطيب الراقي\n\nمميزات إضافية:\nتطبيق خاص للمستأجرين\nنظافة يومية للعقار\nالصيانة متوفرة من خلال التطبيق\nخدمة عملاء على مدار الساعة\nالعقار مراقب بكاميرات المراقبة\nخدمات متنوعة داخل التطبيق\n\nمواصفات الشقة:\n2 غرف نوم\n2 دورات مياه\nحوش خاص\nمدخل خاص\nمطبخ راكب\nمكيفات راكبة بالكامل\nموقف خاص\nصالة واسعة بنوافذ كبيرة\nدخول ذكي لمزيد من الأمان\n\n💰 السعر:\n70,000 سنوياً للدفعة\n72,000 سنوياً دفعتين\n\n📍 الموقع: حي العارض – الرياض\n\n━━━━━━━━━━━━━━━━━━\n\n🏡Luxury Apartment for Annual Rent – 2",
"description_en": "🏡 luxury apartment for annual rent – 2 bedrooms, al arid district, a0713 – ready to move in, flexible payment options available\n\n📞 contact: 9200032342\nmodern residential designs with high-end finishing\n\nadditional features:\ndedicated tenant app\ndaily property cleaning\nmaintenance available through the app\n24/7 customer service\nproperty monitored by security cameras\nvarious services within the app\n\napartment specifications:\n2 bedrooms\n2 bathrooms\nprivate yard\nprivate entrance\nfitted kitchen\nfully installed air conditioners\nprivate parking\nspacious living room with large windows\nsmart entry fo",
"description_ar": "🏡شقة فاخرة للإيجار السنوي غرفتين حي العارض A0713 جاهزة للسكن توجد دفعات مرنه\n\n📞 للتواصل 9200032342\nبتصاميم المساكن العصرية والتشطيب الراقي\n\nمميزات إضافية:\nتطبيق خاص للمستأجرين\nنظافة يومية للعقار\nالصيانة متوفرة من خلال التطبيق\nخدمة عملاء على مدار الساعة\nالعقار مراقب بكاميرات المراقبة\nخدمات متنوعة داخل التطبيق\n\nمواصفات الشقة:\n2 غرف نوم\n2 دورات مياه\nحوش خاص\nمدخل خاص\nمطبخ راكب\nمكيفات راكبة بالكامل\nموقف خاص\nصالة واسعة بنوافذ كبيرة\nدخول ذكي لمزيد من الأمان\n\n💰 السعر:\n70,000 سنوياً للدفعة\n72,000 سنوياً دفعتين\n\n📍 الموقع: حي العارض – الرياض\n\n━━━━━━━━━━━━━━━━━━\n\n🏡Luxury Apartment for Annual Rent – 2",
"price": 68000,
"currency": "SAR",
"price_period": "yearly",
"price_period_ar": "سنوي",
"price_period_source": "category_default",
"price_per_year": 68000,
"instalments": {
"two_payments": 36000,
"four_payments": 18000,
"twelve_payments": 6000
},
"accepts_payment_every": {
"monthly": true
},
"area_sqm": 825,
"street_width_m": 30,
"bedrooms": 3,
"rooms": 3,
"age_years": 0,
"features": {
"near_metro": false,
"near_bus": false
},
"location": {
"address": "شارع العدل, حي العارض, مدينة الرياض, منطقة الرياض",
"city_id": 21,
"city": "riyadh",
"city_ar": "الرياض",
"district_id": 494,
"direction_id": 4,
"province_id": 5,
"lat": 24.876529,
"lng": 46.620496
},
"created_at": "2026-09-01T16:42:23Z",
"published_at": "2026-09-30T17:29:25Z",
"updated_at": "2026-10-01T11:58:26Z",
"refreshed_at": "2026-10-06T14:46:32Z",
"photos": [
"https://images.aqar.fm/webp/750x0/props/040110617_1788281438513.jpg",
"https://images.aqar.fm/webp/750x0/props/040110610_1788281438461.jpg",
"https://images.aqar.fm/webp/750x0/props/040110617_1788281438442.jpg"
],
"photo_count": 19,
"has_video": true,
"verified": true,
"is_promoted": false,
"licensing": {
"ad_license_number": "7201113228",
"rega_licensed": true,
"deed_number": "360001312596",
"deed_area_sqm": 825
},
"seller": {
"user_id": 4011061,
"name": "البراء عبدالله",
"company_name": "شركة اساكن للتطوير العقاري",
"rating": 4,
"identity_verified": true,
"is_office": false,
"phone": null,
"phone_available": false
}
},
{
"id": 6827009,
"url": "https://sa.aqar.fm/listing/6827009",
"category_id": 1,
"category": "apartment-for-rent",
"listing_kind": "rent",
"title": "🏡 luxury apartment for annual rent – 3 bedrooms, al malqa district – b0108 – ready to move in – flexible payment options available",
"description": "🏡شقة فاخرة للإيجار السنوي 3 غرف حي الملقا B0108 جاهزة للسكن توجد دفعات مرنه\n\n📞 للتواصل 9200032342\nبتصاميم المساكن العصرية والتشطيب الراقي\n\nمميزات إضافية:\nتطبيق خاص للمستأجرين\nنظافة يومية للعقار\nالصيانة متوفرة من خلال التطبيق\nخدمة عملاء على مدار الساعة\nالعقار مراقب بكاميرات المراقبة\nخدمات متنوعة داخل التطبيق\n\nمواصفات الشقة:\n3 غرف نوم\n2 دورات مياه\nمطبخ راكب\nمجلس مغلق\nمكيفات راكبة بالكامل\nموقف خاص\nصالة واسعة بنوافذ كبيرة\nدخول ذكي لمزيد من الأمان\n\n💰 السعر:\n69,000 سنوياً للدفعة\n75,000 سنوياً دفعتين\n📍 الموقع: حي الملقا – الرياض\n\n━━━━━━━━━━━━━━━━━━\n\n🏡Luxury Apartment for Annual Rent – 3 Bedrooms",
"description_en": "🏡 luxury apartment for annual rent – 3 bedrooms, al malqa district – b0108 – ready to move in – flexible payment options available\n\n📞 contact: 9200032342\nmodern residential designs with high-end finishing\n\nadditional features:\ndedicated tenant app\ndaily property cleaning\nmaintenance available through the app\n24/7 customer service\nproperty monitored by security cameras\nvarious services available within the app\n\napartment specifications:\n3 bedrooms\n2 bathrooms\nfitted kitchen\nenclosed sitting room (majlis)\nfully installed air conditioning units\nprivate parking space\nspacious living room with la",
"description_ar": "🏡شقة فاخرة للإيجار السنوي 3 غرف حي الملقا B0108 جاهزة للسكن توجد دفعات مرنه\n\n📞 للتواصل 9200032342\nبتصاميم المساكن العصرية والتشطيب الراقي\n\nمميزات إضافية:\nتطبيق خاص للمستأجرين\nنظافة يومية للعقار\nالصيانة متوفرة من خلال التطبيق\nخدمة عملاء على مدار الساعة\nالعقار مراقب بكاميرات المراقبة\nخدمات متنوعة داخل التطبيق\n\nمواصفات الشقة:\n3 غرف نوم\n2 دورات مياه\nمطبخ راكب\nمجلس مغلق\nمكيفات راكبة بالكامل\nموقف خاص\nصالة واسعة بنوافذ كبيرة\nدخول ذكي لمزيد من الأمان\n\n💰 السعر:\n69,000 سنوياً للدفعة\n75,000 سنوياً دفعتين\n📍 الموقع: حي الملقا – الرياض\n\n━━━━━━━━━━━━━━━━━━\n\n🏡Luxury Apartment for Annual Rent – 3 Bedrooms",
"price": 75000,
"currency": "SAR",
"price_period": "yearly",
"price_period_ar": "سنوي",
"price_period_source": "category_default",
"price_per_year": 75000,
"area_sqm": 900,
"bedrooms": 3,
"rooms": 3,
"living_rooms": 1,
"bathrooms": 3,
"floor": 2,
"age_years": 3,
"features": {
"elevator": true,
"near_metro": false,
"near_bus": true
},
"location": {
"address": "شارع عبدالله بن شهيوين, حي الملقا, مدينة الرياض, منطقة الرياض",
"city_id": 21,
"city": "riyadh",
"city_ar": "الرياض",
"district_id": 570,
"direction_id": 4,
"province_id": 5,
"lat": 24.792154,
"lng": 46.618932
},
"created_at": "2026-08-17T10:54:01Z",
"published_at": "2026-09-15T11:27:36Z",
"updated_at": "2026-10-01T11:58:26Z",
"refreshed_at": "2026-10-06T14:46:31Z",
"photos": [
"https://images.aqar.fm/webp/750x0/props/040110614_1786964259072.jpg",
"https://images.aqar.fm/webp/750x0/props/040110613_1786964259078.jpg",
"https://images.aqar.fm/webp/750x0/props/040110615_1786964258961.jpg"
],
"photo_count": 11,
"has_video": false,
"verified": true,
"is_promoted": false,
"licensing": {
"ad_license_number": "7201089675",
"rega_licensed": true,
"deed_number": "398514001600",
"deed_area_sqm": 900
},
"seller": {
"user_id": 4011061,
"name": "البراء عبدالله",
"company_name": "شركة اساكن للتطوير العقاري",
"rating": 4,
"identity_verified": true,
"is_office": false,
"phone": null,
"phone_available": false
}
},
{
"id": 6707565,
"url": "https://sa.aqar.fm/listing/6707565",
"category_id": 1,
"category": "apartment-for-rent",
"listing_kind": "rent",
"title": "🏡 luxury apartment for annual rent – 2 bedrooms, al narjis district, a1411 – ready to move in, flexible payment options available",
"description": "🏡شقة فاخرة للإيجار السنوي غرفتين حي النرجس A1411 جاهزة للسكن توجد دفعات مرنه\n\n📞 للتواصل 9200032342\nبتصاميم المساكن العصرية والتشطيب الراقي\n\nمميزات إضافية:\nتطبيق خاص للمستأجرين\nنظافة يومية للعقار\nالصيانة متوفرة من خلال التطبيق\nخدمة عملاء على مدار الساعة\nالعقار مراقب بكاميرات المراقبة\nخدمات متنوعة داخل التطبيق\n\nمواصفات الشقة:\n2 غرف نوم\n2 دورات مياه\nمطبخ راكب\nمكيفات راكبة بالكامل\nموقف خاص\nصالة واسعة بنوافذ كبيرة\nدخول ذكي لمزيد من الأمان\n\n💰 السعر:\n66,000 سنوياً للدفعة\n68,000 سنوياً دفعتين\n📍 الموقع: حي النرجس – الرياض\n\n━━━━━━━━━━━━━━━━━━\n\n🏡Luxury Apartment for Annual Rent – 2 Bedrooms, Al Narj",
"description_en": "🏡 luxury apartment for annual rent – 2 bedrooms, al narjis district, a1411 – ready to move in, flexible payment options available\n\n📞 contact: 9200032342\nmodern residential designs with premium finishing\n\nadditional features:\ndedicated tenant app\ndaily property cleaning\nmaintenance available through the app\n24/7 customer service\nproperty monitored by security cameras\nvarious services within the app\n\napartment specifications:\n2 bedrooms\n2 bathrooms\nfitted kitchen\nfully installed air conditioning units\nprivate parking space\nspacious living room with large windows\nsmart entry system for added se",
"description_ar": "🏡شقة فاخرة للإيجار السنوي غرفتين حي النرجس A1411 جاهزة للسكن توجد دفعات مرنه\n\n📞 للتواصل 9200032342\nبتصاميم المساكن العصرية والتشطيب الراقي\n\nمميزات إضافية:\nتطبيق خاص للمستأجرين\nنظافة يومية للعقار\nالصيانة متوفرة من خلال التطبيق\nخدمة عملاء على مدار الساعة\nالعقار مراقب بكاميرات المراقبة\nخدمات متنوعة داخل التطبيق\n\nمواصفات الشقة:\n2 غرف نوم\n2 دورات مياه\nمطبخ راكب\nمكيفات راكبة بالكامل\nموقف خاص\nصالة واسعة بنوافذ كبيرة\nدخول ذكي لمزيد من الأمان\n\n💰 السعر:\n66,000 سنوياً للدفعة\n68,000 سنوياً دفعتين\n📍 الموقع: حي النرجس – الرياض\n\n━━━━━━━━━━━━━━━━━━\n\n🏡Luxury Apartment for Annual Rent – 2 Bedrooms, Al Narj",
"price": 70000,
"currency": "SAR",
"price_period": "yearly",
"price_period_ar": "سنوي",
"price_period_source": "stated_by_advertiser",
"price_per_year": 70000,
"instalments": {
"two_payments": 72000,
"four_payments": 72000,
"twelve_payments": 72000
},
"accepts_payment_every": {
"monthly": true,
"quarterly": true,
"semiannually": true
},
"area_sqm": 97,
"bedrooms": 2,
"rooms": 2,
"living_rooms": 1,
"bathrooms": 2,
"floor": 2,
"age_years": 0,
"features": {
"furnished": false,
"elevator": true,
"near_metro": false,
"near_bus": false
},
"location": {
"address": "شارع سليمان الحمدان, حي النرجس, مدينة الرياض, منطقة الرياض",
"city_id": 21,
"city": "riyadh",
"city_ar": "الرياض",
"district_id": 600,
"direction_id": 4,
"province_id": 5,
"lat": 24.86368,
"lng": 46.657446
},
"created_at": "2026-05-22T10:33:12Z",
"published_at": "2026-09-15T13:30:43Z",
"updated_at": "2026-10-01T11:58:26Z",
"refreshed_at": "2026-10-06T14:46:30Z",
"photos": [
"https://images.aqar.fm/webp/750x0/props/040110610_1779445862619.jpg",
"https://images.aqar.fm/webp/750x0/props/040110610_1779445862614.jpg",
"https://images.aqar.fm/webp/750x0/props/040110612_1779445862618.jpg"
],
"photo_count": 21,
"has_video": true,
"verified": true,
"is_promoted": false,
"licensing": {
"ad_license_number": "7200981919",
"rega_licensed": true,
"deed_number": "3147721289100020",
"deed_area_sqm": 97.28
},
"seller": {
"user_id": 4011061,
"name": "البراء عبدالله",
"company_name": "شركة اساكن للتطوير العقاري",
"rating": 4,
"identity_verified": true,
"is_office": false,
"phone": null,
"phone_available": false
}
}
],
"summary": {
"total_results": 13456,
"index_count": 13513,
"counts_disagree": true,
"count_gap": 57,
"returned": 20,
"offset": 0,
"page_size": 70,
"pages_fetched": 1,
"has_more": true,
"sort": "recently_bumped",
"currency": "SAR"
},
"filters_applied": {
"category": "apartment-for-rent",
"city": "riyadh",
"price_max": 80000,
"beds_min": 2
}
}
}What the Aqar API does
| Action | Description | Concrete use case | Key params |
|---|---|---|---|
| search | 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. | Real-estate investors call search to search Saudi Arabia's largest property marketplace by category (66 of them, each pairing a pr…. | category, city, district_id, direction_id, keyword, ... |
| detail | 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. | Brokerage tools call detail to get the full record for one listing. | id, lang, include_pii |
| count | 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. | Property dashboards call count to get how many properties match a filter combination, without parsing a single row. | category, city, district_id, direction_id, keyword, ... |
| categories | 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. | Lead-generation teams call categories to get the complete category vocabulary. | none |
| cities | 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. | Real-estate investors call cities to get every Saudi city that carries stock, with its numeric city_id and a LIVE listing count, optio…. | category |
| districts | 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. | Brokerage tools call districts to get every district (neighbourhood) of one city with a live listing count, plus the city's quadran…. | city, category |
| price_history | 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. | Property dashboards call price_history to get aqar's own half-yearly price series per district of a city, going back to 2015. | city, category |
| agent | 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. | Lead-generation teams call agent to get the public profile of one advertising office or private advertiser. | user_id, max_results, include_pii |
| suggest | 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. | Real-estate investors call suggest to get place autocomplete straight from the site's own search box. | query |
Call search from your stack
curl -X POST https://api.reefapi.com/aqar/v1/search \
-H "x-api-key: $REEF_KEY" \
-H "content-type: application/json" \
-d '{"category":"apartment-for-rent","city":"riyadh","price_max":80000,"beds_min":2,"sort":"recently_bumped","max_results":20}'import requests
r = requests.post(
"https://api.reefapi.com/aqar/v1/search",
headers={"x-api-key": REEF_KEY},
json={
"category": "apartment-for-rent",
"city": "riyadh",
"price_max": 80000,
"beds_min": 2,
"sort": "recently_bumped",
"max_results": 20
},
)
print(r.json()["data"])const res = await fetch("https://api.reefapi.com/aqar/v1/search", {
method: "POST",
headers: {
"x-api-key": process.env.REEF_KEY,
"content-type": "application/json",
},
body: JSON.stringify({
"category": "apartment-for-rent",
"city": "riyadh",
"price_max": 80000,
"beds_min": 2,
"sort": "recently_bumped",
"max_results": 20
}),
});
const { ok, data, meta, error } = await res.json();Ask your MCP-connected assistant: call reefapi.aqar.search with {"category":"apartment-for-rent","city":"riyadh","price_max":80000,"beds_min":2,"sort":"recently_bumped","max_results":20}.Who uses this API and why
- Saudi property analysts call price_history per city to chart average price per square metre by district from 2015 to today, then count to size the live stock behind each district.
- Rental-yield models call search with rent_period and read price_period off every row, so an annual rent is never mistaken for a monthly one, then price_history for the district's sale price per square metre.
- Portal and aggregator builders call categories, cities and districts once for the numeric ids, then page search with no depth limit - a 22,000-row Riyadh query really is 22,000 rows.
- New-listing feeds call search with created_after_days instead of a newest sort, because on this marketplace the recency sort is a bump order and created_after_days is the real publication filter.
- Brokerage and lead-gen teams call agent on the user_id that comes back on every row to get an office's licence number, rating, live and archived stock counts and current listings in one request.
Questions developers ask before integrating
Is a rent price on Aqar monthly or yearly?
Usually yearly. Site-wide at capture, 27,149 rent listings were priced per year, 3,952 per day and only 5 per month, so a caller who assumes monthly is out by twelve times. Every row returns price_period as a word - daily, monthly or yearly - and price_per_year is derived only where the period is known. Sale rows carry no period at all.
What happens when the advertiser did not state a rent period?
It happens often: 68 of 153 rent rows in a 417-row sample had no stated period. Aqar's own listing page still prints a period for those - it renders a yearly label and its structured data says annually - so the API returns yearly and sets price_period_source to category_default. When the advertiser did state it, price_period_source says stated_by_advertiser. The distinction is on every row, so nothing is assumed silently.
Why does the response return two different totals?
Because Aqar computes two. total_results is the number of rows that can actually be paged through and index_count is the index's own tally. They differ by 94 on a Riyadh apartment query, by 349 on Jeddah apartments for sale, and by 3,951 on daily-rate stock. Both are returned along with counts_disagree and count_gap. Build against total_results.
Can I sort by newest listing?
Not reliably, and the API says so instead of pretending. Aqar accepts a creation-date sort and then ignores it - ascending and descending return the same rows, measured. The only working recency order is recently_bumped, which is when the advertiser last re-promoted the ad. For genuinely new stock use created_after_days: seven days returned 1,775 of 22,758 Riyadh rentals and thirty days returned 7,052. Passing sort=newest is accepted, mapped to recently_bumped, and the response explains the swap.
How deep can I page?
To the end. Offsets of 1,000, 5,000, 9,000, 10,000, 12,000 and 20,000 all returned fresh rows on a 22,666-row query, an offset of 22,666 returned an empty list, and a full walk of a 186-row query returned 186 unique ids. There is no silent repeat of the last page. Each request serves up to 70 rows; bigger asks are walked for you.
Does the API give me the advertiser's phone number?
No. Aqar does not publish per-listing contact numbers to anonymous callers, so there is nothing to return. What is published is the advertiser's display name, the office's company name, its rating, its REGA and brokerage licence numbers, its live and archived listing counts and its numeric id, which the agent action resolves into a full public profile.
What is in price_history and how far back does it go?
Aqar's own half-yearly market series per district: for each period, how many deals were recorded and the average price per square metre. Riyadh apartments returned 124 districts and a series starting in the first half of 2015, all in one request. It is the dataset behind the site's district pages, and it is the main reason to use this API for analysis rather than just for listings.
Do the filters actually narrow the results?
Every exposed filter was bite-tested against an unfiltered control of 22,758 taken in the same run: price under 30,000 gave 6,453, three or more bedrooms 12,425, area 200 m² and up 8,176, furnished 3,235, has video 9,304, Arabic keyword فيلا 1,420, offices 4,206 against 18,552 private advertisers. One filter is deliberately labelled as weak rather than dropped: verified matched 22,253 of 22,758, so it narrows almost nothing. An unrecognised filter is rejected with a 400 rather than silently ignored.
What is the Aqar API?
Aqar API is a ReefAPI endpoint group for saudi arabia's largest property marketplace: 169,000 reachable apartment, villa, land, office and shop listings in sar, with rent quoted in the period the advertiser actually used. It returns live JSON through POST requests under /aqar/v1.
Is the Aqar API free to try?
Yes. ReefAPI starts with 1,000 free credits, no card required. Aqar calls use the same shared credit balance as every other ReefAPI engine.
Do I need an Aqar login or account?
No login to Aqar is needed for the API response. You call ReefAPI with your x-api-key header, and the playground can run live examples before you create a production key.
How fresh is the Aqar data?
The page example is captured from a live search call, and production requests fetch live data through ReefAPI rather than a static sample.
How many credits does the Aqar API use?
Aqar actions currently cost 1-2 credits per successful call. Failed or blocked calls are free. All APIs draw from one credit pool.
Can I call Aqar from an AI assistant or MCP client?
Yes. Connect ReefAPI once through MCP and your assistant can call aqar actions with the same key, credit pool and JSON envelope used by normal REST requests.