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

الجغرافيا السياسية والممثلون المنتخبون

تعرض واجهة برمجة تطبيقات المعلومات المدنية من Google معلومات حول التقسيمات الجغرافية السياسية والممثلين المنتخبين لعناوين الولايات المتحدة من المستوى الفيدرالي إلى المستوى المحلي. في الوقت الحالي، تتوفر لدينا تغطية تقترب من 100% للمقاطعات التشريعية في الولاية والمقاطعة والكونغرس، ونهدف إلى تجاوز نسبة 90% من التغطية للمقاطعات التشريعية في الولاية. يتم تقديم المستويات الأدنى، مثل مجالس المدينة والمقاطعة، على أساس أفضل جهد، وسيتم التحسن بمرور الوقت.

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

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

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

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

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

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

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

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

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

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

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

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

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

تحديد المصدر

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

  • "مُقدَّم من خلال واجهة برمجة تطبيقات المعلومات المدنية"
  • "معلومات التصويت المتوفرة من خلال واجهة برمجة تطبيقات المعلومات المدنية"
  • "معلومات استطلاع الرأي المستندة إلى واجهة برمجة تطبيقات المعلومات المدنية"
  • "معلومات تمثيلية تستند إلى واجهة برمجة تطبيقات المعلومات المدنية"
  • "مزيد من المعلومات"

رموز الحالة

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

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