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

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

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

مدى توفُّر البيانات

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

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

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

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

    ملاحظة: تستغرق عملية الموافقة من شهر إلى شهرَين، لذا ننصح المطوّرين بالتخطيط لطلبات زيادة الحصة وفقًا لذلك. بالنسبة إلى طلبات زيادة الحصة للانتخابات في نوفمبر، ننصح بشدة بإرسال طلبات الحصة في موعد أقصاه نهاية أغسطس.

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

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

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

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

تحديد المصدر

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

  • "مدعومة من واجهة برمجة التطبيقات Civic Information API"
  • "معلومات التصويت مدعومة من واجهة برمجة التطبيقات Civic Information API"
  • "معلومات الاقتراع مدعومة من واجهة برمجة التطبيقات Civic Information API"
  • "مزيد من المعلومات"

رموز الحالة

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

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