جوكر برايس
ابدأ التجربة المجانية
قائمة وثائق المطورين

الأدوات

8 أدوات للقراءة فقط، تغلّف كل منها نقطة وصول واحدة في REST API وتُرجع استجابتها بصيغة JSON، والمبالغ بالريال السعودي.

list_markets

GET /api/v1/markets

كل وجهة تضم 20 عقارًا مجمّعًا على الأقل: المعرّف (slug)، وعدد العقارات حسب المصدر، وأرباع السعر المعروض بالريال السعودي، والإشغال ومتوسط السعر اليومي والإيرادات حيث تُتتبَّع التقويمات. يستدعيها المساعد أولًا لمعرفة المعرّفات.

لا توجد وسائط.

get_market

GET /api/v1/markets/{slug}

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

الوسيطالنوعالوصف
slugstringمعرّف السوق مثل riyadh أو dubai أو cairo، ويصلح اسم المدينة أيضًا.

get_metrics

GET /api/v1/metrics

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

الوسيطالنوعالوصف
citystring، اختياريمعرّف السوق أو اسمه.
boundsobject، اختياريnorth وsouth وeast وwest بالدرجات، بعرض لا يتجاوز 5 درجات. يُستخدم بدلًا من city.
past_daysinteger، اختياريعدد الليالي السابقة، من 1 إلى 365 (افتراضيًا 30).
forward_daysinteger، اختياريعدد الليالي القادمة، من 1 إلى 365 (افتراضيًا 60).
include_seriesboolean، اختياريتضمين السلسلة الليلية. القيمة الافتراضية false لإبقاء الاستجابات صغيرة.

list_listings

GET /api/v1/listings

العقارات المجمّعة مع المصدر والعنوان والحي ومعرّف النوع وعدد غرف النوم والإحداثيات وآخر سعر معروض بالريال السعودي والتقييم من 10 والرابط. ويتنقل المساعد بين الصفحات باستخدام nextCursor.

الوسيطالنوعالوصف
citystringمعرّف السوق أو اسمه.
limitinteger، اختياريعدد العقارات في كل صفحة، من 1 إلى 500 (افتراضيًا 100).
cursorstring، اختياريقيمة nextCursor من الصفحة السابقة.

estimate_revenue

POST /api/v1/estimate

السعر الليلي المتوقع والإشغال والإيرادات الشهرية والسنوية استنادًا إلى العقارات المماثلة القريبة والتقويمات المتتبَّعة، أو سيناريوهات بنسب 40٪ و55٪ و70٪ عندما لا يكون الإشغال مقيسًا.

الوسيطالنوعالوصف
latitude, longitudenumberموقع العقار.
radiusKmnumber، اختيارينصف قطر البحث عن العقارات المماثلة، من 0.5 إلى 20 كم (افتراضيًا 3).
bedroomsinteger، اختياريعدد غرف النوم بالضبط، أو 0 لأي عدد (افتراضي).
typeIdstring، اختياري1 منتجع، 2 شاليه، 3 استراحة، 4 مزرعة، 5 مخيم، 6 شقة، 7 فيلا، 8 غرفة، 9 استوديو، 11 شقة فندقية، أو all (افتراضي).
compsarray، اختياريمن 3 إلى 50 قيمة key من candidates في تقدير سابق، و50 قيمة على الأكثر. يستخدم التقدير عندها هذه العقارات وحدها، بقواعد POST /api/v1/estimate نفسها: دون اللجوء إلى نطاق أوسع، وتكون قيمة selection.status هي too-few حين يطابق أقل من 3 مفاتيح، وتُحسب المفاتيح التي لم تعد بين العقارات المرشحة في selection.ignored.

get_market_pace

GET /api/v1/pace

نسبة الليالي المحجوزة مسبقًا لكل تاريخ إقامة خلال الأيام الثلاثين القادمة، ومقدار الحجوزات المستجدة (pickup) خلال 7 و14 يومًا، ومنحنى الحجز المتوسط حسب عدد الأيام السابقة للوصول. تبقى البيانات قيد الجمع حتى يتوفر أسبوع من اللقطات.

الوسيطالنوعالوصف
citystringمعرّف السوق أو اسمه.

get_events

GET /api/v1/events

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

الوسيطالنوعالوصف
citystring، اختياريمعرّف السوق أو اسمه.
from, tostring، اختيارينطاق التواريخ بصيغة YYYY-MM-DD.
kindarray، اختياريreligious (دينية)، أو national (وطنية)، أو school (مدرسية)، أو season (موسمية)، أو sports (رياضية)، أو culture (ثقافية)، أو business (أعمال).

السلوك

  • يقدّم الخادم المستضاف والخادم المحلي الأدوات نفسها بالوسائط نفسها.
  • جميع الأدوات مصنفة للقراءة فقط.
  • تقبل وسائط المدينة معرّفًا (al-khobar) أو اسمًا (Al Khobar).
  • تحتاج get_metrics إلى city أو bounds، وتستبدل السلسلة الليلية بعدد عناصرها ما لم تكن قيمة include_series هي true.
  • تعود الأخطاء أخطاءَ أدوات مع شرح واضح، ليتمكن المساعد من إخبارك بما يجب إصلاحه.
  • مدخلات الاستثمار في التقديرات (التدفق النقدي ومعدل العائد وفترة الاسترداد) متاحة عبر REST API فقط.