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

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

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

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

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

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

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

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

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

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

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

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

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

تحديد المصدر

الإشارة إلى Civic Information API هي إجراء اختياري. إذا اختار أحد المطوّرين الإشارة إلى 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 حدث خطأ غير محدّد أثناء معالجة الطلب.