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

البدء

من حساب جديد إلى أول استجابة في أربع خطوات.

1. أنشئ حسابًا

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

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

2. أنشئ مفتاح API

في التطبيق، افتح البيانات وواجهة API (Data & API) واختر إنشاء مفتاح (Create key). أعطه اسمًا يسهل تمييزه، مثل spreadsheet أو reporting script. يبدأ المفتاح الكامل بـ ss_ ويظهر مرة واحدة فقط، لأن جوكر برايس لا يحفظ منه إلا قيمة مجزّأة (hash). انسخه إلى مدير كلمات المرور أو مخزن الأسرار لديك.

تحدد خطتك عدد المفاتيح النشطة التي تحتفظ بها: 5 خلال التجربة المجانية وحتى 10 في خطة أعمال API. ويمكنك إلغاء أيٍّ منها من الصفحة نفسها في أي وقت، فتتوقف الطلبات التي تستخدمه فورًا.

3. احفظ المفتاح في متغيرات البيئة

macOS وLinux
export JOKERPRICE_API_KEY="ss_your_key_here"
Windows PowerShell
$env:JOKERPRICE_API_KEY = "ss_your_key_here"

4. نفّذ أول طلب

اعرض الوجهات التي يمكنك الاستعلام عنها. لكل عنصر معرّف slug ستستخدمه مع نقاط الوصول الأخرى.

سطر الأوامر
curl -H "Authorization: Bearer $JOKERPRICE_API_KEY" \
  "https://jokerprice.com/api/v1/markets"
JavaScript (Node 18+)
const res = await fetch("https://jokerprice.com/api/v1/markets", {
  headers: { Authorization: `Bearer ${process.env.JOKERPRICE_API_KEY}` },
});
if (!res.ok) throw new Error((await res.json()).error.message);
const { markets } = await res.json();
console.table(markets.map(m => ({ slug: m.slug, listings: m.listings, median: m.nightly.median })));
Python
import os, requests

res = requests.get(
    "https://jokerprice.com/api/v1/markets",
    headers={"Authorization": f"Bearer {os.environ['JOKERPRICE_API_KEY']}"},
    timeout=30,
)
res.raise_for_status()
for m in res.json()["markets"]:
    print(m["slug"], m["listings"], m["nightly"]["median"])

قراءة الاستجابة

  • المبالغ بالريال السعودي، وقيم nightly أسعار معروضة قبل رسوم المنصة.
  • النسب مثل occupancy كسور عشرية: 0.47 تعني 47٪.
  • تحقق من tracker.maturity (أو metrics.maturity) قبل الاعتماد على الإشغال ومتوسط السعر اليومي: تبقى القيمة "collecting" حتى يتوفر للنطاق تتبّع لمدة 7 أيام و100 ليلة عقار مرصودة.
  • تُرجع الأخطاء جسم JSON يتضمن error.code وerror.message وrequestId. راجع الأخطاء.

الخطوات التالية