إرشادات بيانات مطوّري البرامج

معلومات التصويت

تعرض Google Civic Information API معلومات مدنية، مثل مكان الاقتراع ومكان التصويت المبكر، ومعلومات الاتصال الرسمية الخاصة بالانتخابات المحلية ومعلومات الاقتراع للمستخدمين في الانتخابات التي يدعمها مشروع Voting Information.

توفّر البيانات

إرشادات المطوّرين

على جميع المطوّرين الالتزام بالإرشادات التالية:

  • الالتزام ببنود خدمة واجهات برمجة التطبيقات
  • من خلال استخدام واجهة برمجة التطبيقات، يوافق المطوّرون على الالتزام بأي رؤوس تحكم في ذاكرة التخزين المؤقت في حال توفّرها. في حال عدم توفّر عناوين التحكّم في ذاكرة التخزين المؤقت، يوافق المطوّرون على عدم تخزين بيانات المواقع الجغرافية لأماكن الاقتراع ومعلومات الانتخابات في ذاكرة التخزين المؤقت لأكثر من 24 ساعة، وبيانات شاغلي المناصب والمناطق لأكثر من 30 يومًا.
  • على المطوّرين الذين يستخدمون واجهة برمجة التطبيقات بذل كل جهد ممكن لضمان تقديم التجربة نفسها لجميع المستخدمين. لا نسمح بالاحتفاظ بالبيانات أو اختبار أ/ب أو تجارب مشابهة.

  • إذا كنت بحاجة إلى حصة إضافية لتفعيل حالة الاستخدام، يمكنك طلب زيادة لكل مشروع في Developer Console. إنّ توفير حصة إضافية محدود ويخضع لحد أقصى مسموح به.

    ملاحظة: تستغرق عملية الموافقة شهرًا أو شهرين.لذا، ننصح بالتخطيط لطلبات زيادة الحصة وفقًا لذلك. للاستعداد لزيادة الحصص في الانتخابات الرئاسية لعام 2024، يُرجى إرسال طلبات الحصص بحلول آب (أغسطس).

  • إنّ الحصة الإضافية لواجهة برمجة التطبيقات Civic Info API مخصّصة فقط لدعم حالات الاستخدام الموجّهة للمستخدمين. لا يتمّ منح طلبات زيادة الحصة لحالات استخدام أخرى.

إرشادات إضافية حول البيانات

من الصعب التعامل مع هذه البيانات بشكل خاص. يُرجى مراعاة النقاط التالية.

  • غالبًا ما يراجع مسؤولو الانتخابات هذه البيانات في الأسابيع القليلة الماضية وحتى في الأيام القليلة الأخيرة قبل الانتخابات. من المستحسن تحذير المستخدمين من ضرورة التحقّق من النتيجة قبل التصويت.
  • تحتوي معظم الخلاصات الرسمية على أجزاء من الشوارع، ما يعني أنّ مسؤولي الانتخابات يربطون مجموعة من العناوين بمناطق الانتخابات ومواقع مراكز الاقتراع. قد تتضمّن النطاقات أي ناخبين مسجّلين في تلك العناوين أو لا تتضمّن. ونتيجةً لذلك، بالنسبة إلى الولايات التي تقدّم خلاصات رسمية من خلال مشروع Voting Information Project، قد يُظهر عنوان لا يتضمّن ناخبين مسجّلين أنّه ناجح.
  • بالنسبة إلى الولايات التي لا تقدّم خلاصة رسمية، لن يتم عرض سوى العناوين التي يتوفّر فيها ناخب مسجّل.
  • في بعض الأحيان، سيكون لدينا مصادر متعددة للمعلومات نفسها. نقدّم المعلومات الأعلى جودة المتاحة لمعلومات الاتصال الرسمية بالانتخابات المحلية ومعلومات الاقتراع. لا تتوفّر طريقة لإلغاء هذا السلوك، باستثناء إزالة المصادر غير الرسمية من خلال المَعلمة officialSourcesOnly. بالنسبة إلى معلومات أماكن الاقتراع، نعطي دائمًا الأولوية لمصادر البيانات الرسمية على المصادر الأخرى.
  • إذا رصدنا مشاكل في جودة البيانات، قد لا نعرض أي بيانات لدائرة انتخابية معيّنة إلى أن يتم حلّ المشكلة.
  • إذا لم تتوفّر لدينا بيانات عن عنوان معيّن، لا يعني ذلك بالضرورة أنّه ما مِن شخص مسجّل للتصويت فيه. يجب أن توجّه التطبيقات المستخدمين إلى المسؤولين المحليين عن الانتخابات للحصول على المعلومات الكاملة.
  • تنتهي صلاحية الانتخابات تلقائيًا بعد يوم الانتخابات. ولن يتم عرض أي بيانات عن الانتخابات بعد ذلك التاريخ.

تحديد المصدر

إنّ تحديد المصدر إلى Civic Information API اختياري. إذا اختار المطوّر نسب المصدر إلى Civic Information API وربط المستخدمين بمزيد من المعلومات حول Civic Information API، نطلب من المطوّرين استخدام أحد خيارات لغة الإسناد التالية وصفحة الويب المرتبطة أدناه:

  • "مستندة إلى واجهة برمجة التطبيقات Civic Information API"
  • ‎“Voting information powered by the Civic Information API”‎
  • ‎“Ballot information powered by the Civic Information API”‎
  • "مزيد من المعلومات"

رموز الحالة

تتضمّن طلبات البيانات إلى voterInfoQuery حقل status يتم ضبطه على success عند قبول عنوان. وفي الحالات الأخرى، سيتم عرض رمز خطأ. في ما يلي التفسيرات الشائعة لرموز الأخطاء. يُرجى العلم أنّه قد يتم عرض المعلومات حتى في حال توفّر رمز خطأ.

الحالة الشرح
success تتعرّف واجهة برمجة التطبيقات على العنوان المطلوب كعنوان صالح.
noStreetSegmentFound لا تتوفّر في واجهة برمجة التطبيقات حاليًا معلومات عن الدائرة الانتخابية و/أو المنطقة التي ينتمي إليها هذا العنوان. قد يرجع ذلك إلى أنّنا ما زلنا نحصل على بيانات جديدة أو نعالجها، أو أنّه ما مِن ناخبين سجّلوا للتصويت في هذا العنوان.
addressUnparseable التنسيق غير صحيح للعنوان المطلوب أو لا يمكن ترميزه جغرافيًا (أي أنّ Google Maps API لا تعرف أي معلومات عن هذا العنوان).
noAddressParameter لم يتم تقديم أي عنوان.
multipleStreetSegmentsFound لا يمكن لواجهة برمجة التطبيقات العثور على معلومات عن العنوان المحدّد، ولكن تتوفّر لديها معلومات عن العناوين المجاورة. على المستخدم التواصل مع مسؤول الانتخابات للحصول على مزيد من المعلومات.
electionOver انتهت الانتخابات المطلوبة. لم تعُد نتائج الانتخابات متاحة من خلال واجهة برمجة التطبيقات. أنشئ طلب بحث electionQuery للعثور على معرّف لانتخابات قادمة.
electionUnknown رقم تعريف الانتخابات المطلوب غير صالح. أنشئ electionQuery للعثور على معرّف صالح.
internalLookupFailure حدث خطأ غير محدّد أثناء معالجة الطلب.