توثيق واجهة برمجة التطبيقات

توفر واجهة برمجة تطبيقات نظام البيانات المفتوحة للمطورين وصولاً برمجياً للقراءة فقط إلى مجموعات البيانات المنشورة علناً والمنظمات التي تنشرها — نفس الدليل الذي يمكنك تصفحه عبر /datasets و/organizations، متوفرة بصيغة JSON عبر HTTPS.

1. 1

   أنشئ حساباً

   سجّل وأنشئ مساحة عملك — كل مفتاح API مرتبط بحساب مستخدم.

2. 2

   أنشئ مفتاح API

   انتقل إلى صفحة مفاتيح API في لوحة التحكم لطلب الوصول. تُعرض المفاتيح مرة واحدة فقط عند الإنشاء — احتفظ بها في مكان آمن.

3. 3

   أرسل أول طلب لك

   curl "https://api.opendatasystem.io/v1/datasets?limit=5" \
     -H "Authorization: Bearer <your_api_key>"

4. 4

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

   تحقق من حقل success، ثم اقرأ data، وفي حال القوائم، pagination.

تتم مصادقة كل طلب باستخدام رمز الحامل (bearer token) — مفتاح API الخاص بك — يُرسل ضمن ترويسة Authorization.

Authorization: Bearer <your_api_key>

المفاتيح مرتبطة بحسابك وترث الصلاحيات المحددة عند إنشائها (للقراءة فقط حالياً). تعامل مع المفتاح كما تتعامل مع كلمة المرور — أعد إصداره من لوحة التحكم إذا تعرض للانكشاف.

جميع نقاط النهاية نسبية إلى هذا الرابط الأساسي، مع ترقيم إصدار ضمن /v1:

https://api.opendatasystem.io/v1

الطلبات هي HTTPS بسيطة مع معاملات في سلسلة الاستعلام — لا حاجة لجسم طلب (request body) لنقاط النهاية للقراءة أدناه.

كل استجابة هي كائن JSON يحتوي على علم success. تُعيد نقاط نهاية القوائم مصفوفة ضمن data بالإضافة إلى كائن pagination؛ أما الموارد المفردة فتُعيد data ككائن دون ترقيم صفحات.

{
  "success": true,
  "data": [ /* … */ ],
  "pagination": {
    "currentPage": 1,
    "limit": 20,
    "totalItems": 128,
    "totalPages": 7,
    "next": 2,
    "prev": null
  }
}

يتم ترقيم صفحات نقاط نهاية القوائم باستخدام معاملي page وlimit. الحجم الافتراضي للصفحة هو 20؛ والحد الأقصى هو 100.

GET https://api.opendatasystem.io/v1/datasets?page=2&limit=20

يكون next وprev في الاستجابة إما رقم الصفحة المجاورة أو null عند عدم وجودها.

تستخدم الأخطاء نفس بنية الاستجابات الناجحة، مع success: false وmessage قابلة للقراءة.

{
  "success": false,
  "message": "Organization not found."
}

يحمل كل مفتاح API حصته الخاصة من الطلبات كل ساعة — 1000 طلب/ساعة افتراضياً. الطلبات التي تتجاوز هذه الحصة تتلقى استجابة 429 حتى تُعاد النافذة الزمنية. يمكن تخصيص الحد لكل مفتاح من لوحة تحكم مفاتيح API.

تُعاد فقط مجموعات البيانات المنشورة (الحالة ACTIVE) والعامة (مستوى الظهور PUBLIC).

{
  "success": true,
  "data": [
    {
      "id": 42,
      "title": "Global Temperature Trends 2024",
      "slug": "global-temperature-trends-2024",
      "description": "Monthly temperature anomalies …",
      "state": "ACTIVE",
      "visibility": "PUBLIC",
      "viewCount": 48312,
      "downloadCount": 9847,
      "updatedAt": "2026-05-15T00:00:00Z",
      "organization": {
        "name": "Open Climate Institute",
        "slug": "open-climate-institute"
      },
      "distributions": [
        { "format": "CSV" },
        { "format": "JSON" }
      ]
    }
  ],
  "pagination": {
    "currentPage": 1,
    "limit": 20,
    "totalItems": 1,
    "totalPages": 1,
    "next": null,
    "prev": null
  }
}

{
  "success": true,
  "data": {
    "id": 42,
    "title": "Global Temperature Trends 2024",
    "slug": "global-temperature-trends-2024",
    "description": "Monthly temperature anomalies …",
    "state": "ACTIVE",
    "visibility": "PUBLIC",
    "downloadCount": 9847,
    "organization": {
      "name": "Open Climate Institute",
      "slug": "open-climate-institute"
    },
    "distributions": [
      { "format": "CSV", "name": "temperature_anomalies.csv" }
    ]
  }
}

تُعاد التوزيعات متداخلة ضمن استجابة مجموعة البيانات، بعنصر واحد لكل ملف منشور (CSV، JSON، XML، XLSX). لا توجد بعد نقطة نهاية منفصلة للتوزيعات — تنزيل الملفات والاستعلام عن السجلات الفردية عبر واجهة برمجة التطبيقات مخطط له في إصدار مستقبلي.

لا توجد نقطة نهاية بحث منفصلة — تقبل كل نقطة نهاية للقوائم معامل استعلام search يطابق عنوان/اسم المورد ووصفه.

GET https://api.opendatasystem.io/v1/datasets?search=temperature

تُنشأ المفاتيح وتُدار من لوحة التحكم الخاصة بك، وليس عبر واجهة برمجة التطبيقات نفسها. لكل مفتاح اسم، وحد لمعدل الطلبات، وتاريخ انتهاء اختياري، وأعلام صلاحيات للقراءة/الكتابة (الوصول العام حالياً للقراءة فقط).

{
  "id": 12,
  "name": "Production integration",
  "keyPreview": "a1b2c3d4",
  "permissions": { "read": true, "write": false },
  "rateLimitPerHour": 1000,
  "lastUsedAt": "2026-06-28T10:15:00Z",
  "expiresAt": null,
  "createdAt": "2026-01-04T09:00:00Z"
}

تُعرض قيمة المفتاح الكاملة مرة واحدة فقط عند الإنشاء — احتفظ بها في مكان آمن. تُعرض بعد ذلك معاينة قصيرة فقط.

• تحقق دائماً من حقل success قبل قراءة data — لا تفترض أن الاستجابة ناجحة دائماً.
• استخدم التصفية عبر search والترقيم بدلاً من سحب قوائم كبيرة غير مصفاة.
• خزّن الاستجابات مؤقتاً حيثما كان ذلك منطقياً — مجموعات البيانات والمنظمات المنشورة لا تتغير كل ثانية.
• تعامل مع استجابات 429 عبر إعادة المحاولة التدريجية (backoff) واحترم الحد الساعي لمفتاحك.
• لا تكشف مفتاح API الخاص بك أبداً في كود جانب العميل، أو السجلات، أو المستودعات العامة.
• واجهة برمجة التطبيقات هذه في مرحلة معاينة — قد تتغير نقاط النهاية قبل الإصدار المستقر.