وثائق المطورين
وصول للقراءة فقط بصيغة JSON وملفات إلى الأرقام خلف هذا الموقع: ما هو متاح، والمعاملات، وشكل الاستجابة، والأخطاء، وكيفية الاقتباس.
ما المتاح
كل ما هنا للقراءة فقط ولا يكشف إلا أرقامًا منشورة أصلًا في هذا الموقع. لا مفتاح ولا تسجيل. هذه هي نقاط الوصول الموجودة اليوم؛ ولا نَعِد بغيرها.
| نقطة الوصول | ماذا تعيد |
|---|---|
| /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 إلى العنوان). |
معاملات السلسلة الزمنية
كل المعاملات اختيارية. تُقارَن الفترات كنص، فيأتي 2025-Q1 قبل 2025-Q2.
| المعامل | المعنى | الافتراضي |
|---|---|---|
| geography | منطقة جغرافية محددة فقط، مثل KSA أو Riyadh أو Makkah. | — |
| property_type | نوع عقار محدد فقط، مثل * (الكل) أو apartment أو villa. | — |
| from | أول فترة تقرير تُدرج (شاملة): 2025 أو 2025-Q1 أو 2025-06 أو 2025-06-30. | — |
| to | آخر فترة تقرير تُدرج (شاملة). | — |
| order | asc (الأقدم أولًا) أو desc (الأحدث أولًا). | asc |
| limit | عدد الصفوف المعادة، من 1 إلى 5000. | 1000 |
| offset | عدد الصفوف المتجاوَزة للتصفح بين الصفحات. | 0 |
شكل الاستجابة
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": "…" }
}]
}الأخطاء والتخزين المؤقت والحدود
400 invalid_request: معامل غير صالح. 404 unknown_metric: المفتاح غير موجود (لا يُعاد الخطأ المطبعي كنتيجة فارغة ناجحة). يتيح CORS الاستخدام من المتصفح. تُخزَّن الاستجابات مؤقتًا بضع دقائق، فقد تتأخر القيمة عن التحديث اليومي. يحدّ الخادم من الاستخدام المكثف؛ وحدوده غير منشورة، فخزّن ما تجلبه ولا تستعلم بوتيرة أعلى من تغيّر البيانات. لا ضمان لوقت التشغيل ولا وعد بإصدارات بخلاف حقل version في الفهرس.
الاقتباس وإعادة الاستخدام والترخيص
اقتبس هكذا: «بيانات سوق كي دبليو السعودية»، واسم مجموعة البيانات أو السلسلة، وعنوان الصفحة أو نقطة الوصول، وتاريخ اطلاعك. اذكر فترة التقرير مع كل رقم؛ فالقيمة بلا فترتها ليست بيانًا عن السوق. تأتي الأرقام من جهات نشر رسمية (وزارة العدل وREGA والبنك المركزي السعودي والهيئة العامة للإحصاء ومعيد نشرها KAPSARC) ومن حسابات كي دبليو، وهي موسومة بذلك في كل صفحة وفي سجل المصادر. تتبع إعادة الاستخدام شروط المصادر الأصلية التي لم نعد ترخيصها: وحيثما وصلت مجموعة بيانات عبر نسخة مجتمعية فراجع شروط الناشر الأصلي قبل إعادة توزيعها. أما حسابات كي دبليو مثل العائد الإجمالي فهي من حسابنا وليست رقمًا رسميًا.
