واجهة برمجة البيانات العامة لأفريقيا

نظرة عامة

تقدم الواجهة البرمجية البيانات نفسها التي تراها على PollsAfrica، مبنية من الملفات نفسها، لذا لا تختلف الصفحة والواجهة البرمجية أبدا. الردود بصيغة JSON بإطار ثابت: صفوفك في data، والمصدر وتاريخ التحديث والترخيص واقتباس جاهز في meta.

إذا كنت تحتاج إلى ملف فقط، فإن تنزيلات CSV وJSON المفتوحة لا تحتاج إلى مفتاح على الإطلاق. واجهة API مخصصة للشيفرة التي تريد صفوفا مفلترة ومقسمة إلى صفحات أو عنوانا ثابتا لكل مورد.

العنوان الأساسي: https://pollsafrica.com/api/v1

المصادقة

أرسل مفتاحك في ترويسة Authorization. تعمل ترويسة X-API-Key أيضا. لا توضع المفاتيح أبدا في العنوان، فتبقى خارج السجلات والروابط المشتركة.

curl -H "Authorization: Bearer YOUR_KEY" \
  "https://pollsafrica.com/api/v1/offices?country=ghana"

الطلب دون مفتاح يحصل على 401 ورسالة تبين أين يوجد المفتاح وأين الملفات المفتوحة. ولا تستجيب دون مفتاح إلا قائمة نقاط النهاية على /api/v1. اخترنا هذا بدلا من حصة مجهولة لأن ملفات JSON المفتوحة تغطي بالفعل الاستخدام المجهول دون حد يجب إدارته.

نقاط النهاية

تستخدم جميع نقاط النهاية GET. يمكن للمتصفحات استدعاءها أيضا: الطلبات عبر المصادر مسموح بها.

معرفات مجموعات البيانات والمؤشرات مدرجة في /api/v1/datasets. وهي تطابق أسماء الملفات في صفحة البيانات.

معاملات الاستعلام

• country: معرف الدولة، مثل ghana، أو اسم الدولة. يعمل على أي مجموعة بيانات تحتوي على عمود الدولة.
• limit: عدد الصفوف في الصفحة. القيمة الافتراضية 100 والحد الأقصى الذي يمكن طلبه 1,000.
• offset: عدد الصفوف التي يجب تخطيها. يحمل meta.next عنوان الصفحة التالية، أو null في الصفحة الأخيرة.
• أي اسم عمود، على سبيل المثال status=upcoming في انتخابات، يبقي فقط الصفوف التي تحمل تلك القيمة بالضبط.

مثال

curl -H "Authorization: Bearer YOUR_KEY" \
  "https://pollsafrica.com/api/v1/elections?limit=1"

{
  "data": [
    {
      "id": "nigeria-0",
      "country": "Nigeria",
      "label": "Presidential election",
      "date": "2015-03-28",
      "status": "held",
      "source_url": "https://www.inecnigeria.org"
    }
  ],
  "meta": {
    "source": "https://pollsafrica.com/elections",
    "updated": "2026-10-21",
    "licence": "CC BY 4.0",
    "licence_url": "https://creativecommons.org/licenses/by/4.0/",
    "cite": "PollsAfrica (year). Elections. Retrieved ... from https://pollsafrica.com/elections",
    "dataset": "elections",
    "total": 126,
    "limit": 100,
    "offset": 0
  }
}

حدود المعدل

تتيح الطبقة المجانية 1,000 طلب لكل مفتاح في اليوم. يعاد ضبط العداد عند الساعة 00:00 بالتوقيت العالمي المنسق. يحمل كل رد الترويسات X-RateLimit-Limit وX-RateLimit-Remaining وX-RateLimit-Reset (وقت يونكس). بعد تجاوز الحد تحصل على 429 مع ترويسة Retry-After بالثواني. خزّن مؤقتا ما تجلبه: تتغير البيانات وفق الجدول المعروض على صفحة البيانات، لا بالدقيقة.

أخطاء

تشترك الأخطاء في شكل واحد، وتخبرك حالة HTTP بفئة المشكلة.

{ "error": { "code": "missing_key", "message": "..." }, "meta": { "docs": "https://pollsafrica.com/developers" } }

الترخيص والإسناد

البيانات مجانية للاستخدام والمشاركة والتعديل، بما في ذلك الاستخدام التجاري، بموجب CC BY 4.0، ما دمتم تنسبونها إلى PollsAfrica وتذكرون ما إذا غيرتم فيها. وتتضمن كل استجابة الترخيص واقتباسا بصيغة meta. يرجى إظهار هذا الإسناد حيث يرى قراؤكم البيانات.

الاقتباس من البيانات

استخدم meta.cite كما هو مكتوب. يذكر مجموعة البيانات وسنة آخر تحديث لها والصفحة التي تشرحها. وحيث يكون لإصدار مجموعة البيانات DOI، يستخدم الاقتباس رابط DOI بدلا من عنوان الصفحة. لاقتباس سؤال استبيان واحد، استخدم السطر الموجود تحت ذلك السؤال في بنك الأسئلة.

احصل على مفتاح

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