تسجيل الدخول
​

الواجهة البرمجية (API)

 هذه الخدمة تتطلب اشتراك فعّال في العضوية (الباقة المتقدمة) .

شرح الربط Documentation

الارتباط بالواجهة البرمجية لـ عقارساس سهل، واضح، ومباشر. الواجهة تمكنك من الاستعلام والبحث برمجيا عن أحدث بيانات الصفقات فور إفراغها. بالإضافة للاستفادة من الإحصائيات الجاهزة مثل قيمة وعدد الصفقات.

كل ما عليك هو الاتصال بروابط الواجهة باستخدام طريقة POST عبر بروتوكول HTTPS مع إرفاق مفتاح API الخاص بك. إرسال واستقبال البيانات عبر الواجهة يتم عن طريق صيغة JSON. (إذا كانت المصطلحات السابقة غير واضحة، نقترح في البداية البحث عن موضوع الربط مع الواجهات البرمجية عبر الويب، لتعلم ومعرفة أساسياتها.)

حاليا نقوم بتوفير الخدمات التالية:

  • الاستعلام، جلب، والبحث عن الصفقات. عبر الرابط: https://api2.aqarsas.com/deals
  • احصائيات عامة عن الصفقات. عبر الرابط: https://api2.aqarsas.com/stats

أمثلة توضيحية

  • الرابط التالي (هنا) سوف ينقلك إلى خدمة تستطيع من خلالها تجريب الواجهة. يمكنك استعراض خيارات البحث من تبويب content ثم الضغط على خيار الإرسال. كل ما تحتاجه ليكون طلبك صحيح هو وضع مفتاح API الخاص بك في المكان المخصص.
  • مثال آخر لرابط لبرنامج مكتوب بلغة بايثون Python3. قم بتعديله فقط عن طريقة إضافة مفتاح الواجهة في الخانة المناسبة ثم قم بتشغيل البرنامج.
ستجد مفتاح API الخاص بك أعلى هذه الصفحة (عند تسجيل الدخول). المزيد من الأمثلة والتوضيحات موجودة في القسم الأخير من هذا المستند.


كامل التفاصيل التقنية مذكورة في الشرح التالي بالانجليزية، لصعوبة ترجمة بعض المصطلحات الخاصة بالمطورين.


Two API endpoints are available /deals/ and /stats/. We always expect a POST JSON request (over https only) with at least an API key provided. A JSON response will always return to you with either a result or an error with explanation. Results are provided in Arabic.


API endpoints


1. Getting real estate deals

https://api2.aqarsas.com/deals/

Use this endpoint to get details of any deal(s) according to your search criteria. With up to 5000 records at a time . If your results exceeded 5000, a random of 5000 within those are returned. Note: Deals data starting from 2019-01-01 are not accessible for free trial users.

Request Structure (Parameters)

  • key * [string] : Your API key. Error will be returned if you don't provide a valid key
  • calendar [string] : Choose between hijri or gregorian. Default is gregorian
  • start_date [string] : Only the following pattern is supported yyyy-mm-dd. Default is none (no restriction).
  • end_date [string] : Only the following pattern is supported yyyy-mm-dd. Default is none (no restriction).
  • category [string] : options are: سكني, تجاري. Default is none (no restriction).
  • dtype [string] : options are: قطعة أرض,عمارة, فيلا, شقة, معرض/محل,مركز تجاري,قصر,بيت,مرفق, إستراحة,أرض زراعية . Default is none (no restriction).
  • state [integer] : Options are: 0: Riyadh,1: Makkah,2: Medina,3: Alqasim,4: Alsharqiah,5: Asir,6: Tabouk,7: Hail,8: Northern Borders,9: Jizan,10: Najran,11: Albaha,12: Aljouf. Default is none (no restriction).
  • city[string] : Exact match for city name. To get an overview about valid names please visit aqarsas.com and check available city names in the search form.
  • min_meter_price [integer] : Minimum price of square meter. Default is 0.
  • max_meter_price [integer] : Maximum price of square meter. Default is none (no restriction).
  • min_deal_price [integer] : Minimum overall price for the deal. Default is 0.
  • max_deal_price [integer] : Maximum overall price for the deal. Default is none (no restriction).
  • min_area [integer] : Minimum area (مساحة) in square meter. Default is 0
  • max_area [integer] : Maximum area (مساحة) in square meter.
  • hai [string] : Neighborhood (حي) name. Default is none.
  • hai_exact_match [integer] : a flag to indicate whether to exactly match the provided hai name: 1, or use our built-in search pattern: 0. It is recommended to set this flag to 0. Default is 0.
  • m566 [string] : m566 (مخطط) name/number.
  • m566_exact_match [integer] : a flag to indicate whether to exactly match the provided m566 name/number: 1, or use our built-in search pattern: 0. It is recommended to set this flag to 0. Default is 0.
  • unit [string] : unit (قطعة) name/number.
  • unit_exact_match[integer] : a flag to indicate whether to exactly match the provided unit name/number: 1, or use our built-in search pattern: 0. It is recommended to set this flag to 0. Default is 0.

Response structure

  • Error_code: Options are:
    • 0: No errors.
    • 1: Error exists. error_msg has the details.
  • Error_msg: If error/warning exists, the explanation is provided here.
  • Deals_list: List of JSON objects. Each with the following structure (refer to request structure for explanation): Date،Category،DType Meter_price،Deal_price،Area،State City،Hai،M566،Unit


2 . Getting real estate statistics

https://api2.aqarsas.com/stats/

Use this endpoint to get statistics in terms of number of deals or total value of deals, according to your search criteria. Those stats could be used to build up-to-date indicators about the Saudi real estate market.

Request Structure (Parameters)

  • key * [string] : Your API key. Error will be returned if you don't provide a valid key.
  • stat_type [string] : Choose between number_of_deals or value_of_deals. Default is value_of_deals
  • calendar [string] : Choose between hijri or gregorian. Default is gregorian
  • start_date [string] : Only the following pattern is supported yyyy-mm-dd. Default is none (no restriction).
  • end_date [string] : Only the following pattern is supported yyyy-mm-dd. Default is none (no restriction).
  • state [integer] : Options are: 0: Riyadh,1: Makkah,2: Medina,3: Alqasim,4: Alsharqiah,5: Asir,6: Tabouk,7: Hail,8: Northern Borders,9: Jizan,10: Najran,11: Albaha,12: Aljouf. Default is none (no restriction).
  • city [string] : Exact match for city name. To get an overview about valid names please visit aqarsas.com and check available city names in the search form. Default is none (no restriction).

Response Structure

  • Error_code: Options are:
    • 0: No errors.
    • 1: Error exists. Error_msg has the details.
  • Error_msg: If error/warning exists, the explanation is provided here.
  • Stats_list: List of JSON objects. Each with the following structure: Category,DType,Stat: contains the requested statistic for the provided type and category

Examples

1. JSON request & response for /deals/

//request {"key": "your_api_key", "calendar": "hijri", "start_date": "1438-08-01","end_date": "1438-12-30", "category": "تجاري","dtype": "قطعة أرض","state": 0,"city": "الرياض", "min_meter_price": 200,"max_meter_price": 600, "min_area": 1000,"max_area": 5500, "hai": "القادسيه","hai_exact_match": 0, "m566": "2670","m566_exact_match": 0} //response {"Error_code": 0,"Error_msg": "", "Deals_list": [{"Date": "26/08/1438","Category": "تجاري","Dtype": "قطعة أرض", "Meter_price": 349,"Deal_price": 1750000,"Area": 5017.91,"State": 0, "City": "الرياض","Hai": "القادسية","M566": "2670","Unit": "314"}, {"Date": "27/08/1438", "Category": "تجاري","Dtype": "قطعة أرض", "Meter_price": 450,"Deal_price": 2250000,"Area": 5000,"State": 0, "City": "الرياض", "Hai": "القادسية", "M566": "2670/ أ","Unit": "1313/أ"}]}

2. JSON request & response for /stats/

//request {'key': 'your_api_key', 'stat_type': 'number_of_deals', 'calendar': 'gregorian', 'start_date': '2018-01-01', 'end_date': '2018-01-01', 'state': 0, 'city': 'الرياض'} //response {'Error_code': 0, 'Error_msg': '', 'Stats_list': [{'Stat': 100, 'Category': 'قطعة أرض', 'Dtype': 'سكني'}, {'Stat': 16, 'Category': 'قطعة أرض', 'Dtype': 'تجاري'}, {'Stat': 4, 'Category': 'شقة', 'Dtype': 'سكني'}, {'Stat': 6, 'Category': 'معرض/محل', 'Dtype': 'سكني'}, {'Stat': 3, 'Category': 'بيت', 'Dtype': 'سكني'}, {'Stat': 10, 'Category': 'مرفق', 'Dtype': 'تجاري'}]}

3. Python3 script

Check this file which contains a sample python3 script calling this API