جوكر برايس
ابدأ التجربة المجانية

البدء السريع مع واجهة API

وصفات لجلب ملخصات الأسواق ومؤشرات الإشغال والعقارات وتقديرات الإيرادات إلى جداولك وأدواتك الخاصة.

احصل على مفتاح

سجّل الدخول، وافتح البيانات وواجهة API، وأنشئ مفتاح API شخصيًا. تحدد خطتك عدد المفاتيح التي تحتفظ بها: حتى 5 مفاتيح خلال التجربة المجانية. يُعرض المفتاح مرة واحدة فقط، ولا تخزّن جوكر برايس منه إلا تجزئة SHA-256، لذا احفظه في مكان آمن وألغِه إن تسرّب. أرسله مع كل طلب:

Authorization: Bearer ss_your_key_here

خلال التجربة المجانية لمدة 30 يومًا يتيح الحساب 120 طلبًا في الدقيقة و25,000 طلب يوميًا تتقاسمها مفاتيحه. وبعد التجربة تحتاج الواجهة إلى خطة، وتعرض أسعار API حدود كل خطة.

اعرض الأسواق

curl -H "Authorization: Bearer $JOKERPRICE_KEY" \
  https://jokerprice.com/api/v1/markets

تُرجع كل وجهة لها تقرير، مع معرّفها (slug) وعدد عقاراتها ووسيط السعر المعروض وحالة التتبّع. استخدم المعرّف في الطلبات الأخرى. وتُرجع GET /api/v1/markets/{slug} التقرير الكامل لوجهة واحدة.

الإشغال ومتوسط السعر اليومي لمدينة أو منطقة

GET /api/v1/metrics?city=riyadh&past_days=90&forward_days=60

أو مرّر مربعًا جغرافيًا بدلًا من المدينة باستخدام north وsouth وeast وwest (بعرض 5 درجات كحد أقصى). وتقبل past_days وforward_days القيم من 1 إلى 365. تحقق من الحقل maturity قبل استخدام الأرقام: القيمة collecting تعني أن السجل غير كافٍ بعد.

تصفّح العقارات صفحةً صفحة

GET /api/v1/listings?city=jeddah&limit=500
GET /api/v1/listings?city=jeddah&limit=500&cursor={nextCursor}

تتضمن كل استجابة nextCursor؛ واصل الطلب به حتى تصبح قيمته null. وتقبل limit القيم من 1 إلى 500.

قدّر إيرادات عقار

curl -X POST -H "Authorization: Bearer $JOKERPRICE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"latitude":24.71,"longitude":46.67,"radiusKm":3,"bedrooms":2,"typeId":"6"}' \
  https://jokerprice.com/api/v1/estimate

تتراوح radiusKm من 0.5 إلى 20، وbedrooms من 0 (أي عدد) إلى 6، أما typeId فقيمتها all أو رمز نوع العقار (مثل 6 للشقق و7 للفلل و2 للشاليهات).

تعامل مع الأخطاء

تُرجع الأخطاء JSON يتضمن code ورسالة. توقّع 401 عند غياب المفتاح أو إلغائه، و404 لسوق غير معروف، و400 لمدخلات غير صالحة، و429 عند بلوغ أحد الحدود؛ ويبيّن الترويس Retry-After مدة الانتظار.

المزيد في أمثلة واجهة API

اجعل الأرقام تعمل لصالح عقارك.

ابدأ التجربة المجانية