انتقل إلى المحتوى
كيلر ويليامز السعودية
واجهة البيانات المفتوحة

وثائق المطورين

وصول للقراءة فقط بصيغة JSON وملفات إلى الأرقام خلف هذا الموقع: ما هو متاح، والمعاملات، وشكل الاستجابة، والأخطاء، وكيفية الاقتباس.

01

ما المتاح

كل ما هنا للقراءة فقط ولا يكشف إلا أرقامًا منشورة أصلًا في هذا الموقع. لا مفتاح ولا تسجيل. هذه هي نقاط الوصول الموجودة اليوم؛ ولا نَعِد بغيرها.

نقطة الوصولماذا تعيد
/data/catalog.jsonفهرس آلي لمجموعات البيانات القابلة للتنزيل: المصدر وتاريخ البيانات ووتيرة التحديث، واسم كل عمود ووحدته ومعناه.
/data/<file>مجموعات البيانات نفسها بصيغة CSV أو JSON. أسماء الملفات مذكورة في الفهرس.
/api/metricsفهرس كل السلاسل الزمنية: مفتاحها ووحدتها وأنواع فتراتها وعدد المناطق وأنواع العقار وأول فترة وآخر فترة وعدد النقاط.
/api/metrics/<key>سلسلة زمنية واحدة بصيغة JSON، تُصفّى بالمعاملات أدناه. كل قيمة تحمل فترتها ووحدتها وعنوان مصدرها وتاريخ جمع الموقع لها.
/api/public/v1/snapshot?lang=enلقطة سوق مختصرة يستخدمها قسم الرؤى في موقع كي دبليو السعودية (المعامل: lang=en أو ar).
/llms.txt · /llms-full.txt · <page>.mdالموقع كنص عادي للمساعدات الذكية والزواحف، ونسخة ماركداون من الأدلة وصفحات المدن والأحياء (أضف .md إلى العنوان).
02

معاملات السلسلة الزمنية

كل المعاملات اختيارية. تُقارَن الفترات كنص، فيأتي 2025-Q1 قبل 2025-Q2.

المعاملالمعنىالافتراضي
geographyمنطقة جغرافية محددة فقط، مثل KSA أو Riyadh أو Makkah.—
property_typeنوع عقار محدد فقط، مثل * (الكل) أو apartment أو villa.—
fromأول فترة تقرير تُدرج (شاملة): 2025 أو 2025-Q1 أو 2025-06 أو 2025-06-30.—
toآخر فترة تقرير تُدرج (شاملة).—
orderasc (الأقدم أولًا) أو desc (الأحدث أولًا).asc
limitعدد الصفوف المعادة، من 1 إلى 5000.1000
offsetعدد الصفوف المتجاوَزة للتصفح بين الصفحات.0
03

شكل الاستجابة

observedAt هي الفترة التي تصفها القيمة. وsource.collectedAt هو وقت جلب الموقع لها، لا وقت نشر المصدر.

{
  "metricKey": "kapsarc.repi.national",
  "count": "<rows returned>", "limit": 2, "offset": 0, "order": "desc",
  "data": [{
    "observedAt": "2026-Q1",
    "periodType": "quarterly",
    "geography": "KSA",
    "propertyType": "*",
    "value": "<number>",
    "unit": "index",
    "changePercent": null,
    "sourceSnapshotId": "…",
    "source": { "collector": "…", "url": "…", "collectedAt": "…" }
  }]
}
05

الأخطاء والتخزين المؤقت والحدود

400 invalid_request: معامل غير صالح. 404 unknown_metric: المفتاح غير موجود (لا يُعاد الخطأ المطبعي كنتيجة فارغة ناجحة). يتيح CORS الاستخدام من المتصفح. تُخزَّن الاستجابات مؤقتًا بضع دقائق، فقد تتأخر القيمة عن التحديث اليومي. يحدّ الخادم من الاستخدام المكثف؛ وحدوده غير منشورة، فخزّن ما تجلبه ولا تستعلم بوتيرة أعلى من تغيّر البيانات. لا ضمان لوقت التشغيل ولا وعد بإصدارات بخلاف حقل version في الفهرس.

06

الاقتباس وإعادة الاستخدام والترخيص

اقتبس هكذا: «بيانات سوق كي دبليو السعودية»، واسم مجموعة البيانات أو السلسلة، وعنوان الصفحة أو نقطة الوصول، وتاريخ اطلاعك. اذكر فترة التقرير مع كل رقم؛ فالقيمة بلا فترتها ليست بيانًا عن السوق. تأتي الأرقام من جهات نشر رسمية (وزارة العدل وREGA والبنك المركزي السعودي والهيئة العامة للإحصاء ومعيد نشرها KAPSARC) ومن حسابات كي دبليو، وهي موسومة بذلك في كل صفحة وفي سجل المصادر. تتبع إعادة الاستخدام شروط المصادر الأصلية التي لم نعد ترخيصها: وحيثما وصلت مجموعة بيانات عبر نسخة مجتمعية فراجع شروط الناشر الأصلي قبل إعادة توزيعها. أما حسابات كي دبليو مثل العائد الإجمالي فهي من حسابنا وليست رقمًا رسميًا.

مجموعات البيانات والتنزيلاتالمنهجية والمصادر