التصدير الشامل

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

curl -X POST https://api.darak.app/v1/exports \
  -H "Authorization: Bearer $DARAK_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"dataset": "listings", "format": "ndjson", "filters": {"city": ["riyadh", "jeddah"]}}'

تكون الاستجابة تصديرًا بحالة status: "queued". استعلم عن GET /exports/{export_id} كل بضع ثوانٍ إلى دقيقة؛ يبدأ خلال نحو دقيقة، وتستغرق لقطة كل إعلانات المملكة بضع دقائق. عند status بالقيمة completed، يحتوي files رابطًا موقّعًا لكل ملف صالحًا لساعة. اطلب مجددًا لروابط جديدة. تُحذف الملفات بعد 7 أيام من اكتمال التصدير.

مجموعات البيانات.

• listings: كل إعلان نشط يطابق filters، وهي مرشّحات /listings بصيغة JSON؛ يقبل city وlisting_type عدة قيم، والافتراضي كلها. أضف updated_since للقطة تزايدية.
• listing_changes: كل حدث created أو price_changed أو delisted بين filters.from وfilters.to، حتى 366 يومًا، مع الإعلان كما هو الآن. تُضمّن كل تغيّرات السعر المسجلة بسعري ما قبل وما بعد؛ هذه المجموعة المناسبة للسجل التاريخي. يبدأ سجل الإعلانات في 2026-03-09.
• registered_transactions: صفقات البيع المسجلة لدى وزارة العدل، كما يعيدها GET /transactions.
• registered_rents: خلايا مؤشر الإيجار لدى الهيئة العامة للعقار، كما يعيدها GET /market/registered-rents.

الملفات. تأتي البيانات في أجزاء تصل إلى 25,000 صف (part-00001.ndjson.gz وpart-00002.ndjson.gz و…)، وكل جزء مستقل ويمكن تحميلها بالتوازي. صف NDJSON هو كائن data نفسه الذي تعيده نقطة النهاية. يسطّح CSV البيانات إلى أعمدة ذات أسماء منقّطة (price.yearly_sar وlocation.neighborhood_id) مع المصفوفات بصيغة JSON. يسرد manifest.json الأجزاء وأعداد صفوفها والأعمدة والمرشّحات والترخيص وأي ملاحظات على البيانات. ترميز CSV هو UTF-8 بلا علامة ترتيب بايتات.

التكلفة والحدود. مجموعات الإعلانات متاحة لـEnterprise بالنطاق exports كتغذية بيانات مرخصة. تُعدّ الصفوف قبل الكتابة، وتُحسب 100 وحدة لكل 1,000 صف مرة واحدة على الحصة الشهرية لا معدل الدقيقة، ويعرض units المبلغ. إذا لم تغطها الحصة أو سقف الإنفاق أو سقف المشروع، يفشل التصدير بالرمز monthly_quota_exceeded أو spend_cap_reached أو project_cap_exceeded دون احتساب، وتُرد وحدات التصدير الفاشل. تكلف لقطة من نحو 230,000 إعلان نحو 23,000 وحدة. مجموعات البيانات المفتوحة مجانية في كل خطة ولا تكلف وحدات. يمكن للمؤسسة تشغيل 2 تصدير في الوقت نفسه وإنشاء 20 يوميًا، وبحد أقصى 2,000,000 صف للتصدير الواحد.

ما يجوز فعله بالملفات. تخضع صادرات الإعلانات لشروط بيانات دارك مثل API، ومنها الاحتفاظ حتى 30 يومًا من الجلب إلا إذا نص اتفاقك على غير ذلك. أعد التصدير دوريًا بدل التراكم. صادرات البيانات المفتوحة بيانات حكومية سعودية مفتوحة يجوز حفظها وإعادة توزيعها شرط مرافقة ATTRIBUTION.txt لها.