הנחיות בנושא נתוני מפתחים

מידע על הצבעה

הממשק Google Civic Information API מחזיר למשתמשים מידע אזרחי כמו מיקום הקלפי, מיקום להצבעה מוקדמת, פרטים ליצירת קשר עם פקיד בחירות מקומי ומידע על פתקי הצבעה לבחירות שנתמכות על ידי Voting Information Project.

זמינות הנתונים

הנחיות למפתחים

אנחנו דורשים מכל המפתחים לפעול בהתאם להנחיות הבאות:

  • עליכם לפעול בהתאם לתנאים ולהגבלות של ממשקי ה-API.
  • השימוש ב-API מחייב את המפתחים לציית לכל כותרת cache-control, אם יש כזו. בהיעדר כותרות של Cache-Control, המפתחים מסכימים לא לשמור במטמון מידע על מיקומי הצבעה ותחרויות למשך יותר מ-24 שעות, ומידע על בעלי תפקידים ומחוזות למשך יותר מ-30 ימים.
  • מפתחים שמשתמשים ב-API צריכים לעשות כל מאמץ כדי לוודא שכל המשתמשים יקבלו את אותה חוויה. אסור להשתמש בשיטות של השהיית מודעות, בדיקות A/B או ניסויים דומים.

  • אם אתם צריכים מכסה נוספת כדי להשתמש בתרחיש לדוגמה, אתם יכולים לבקש הגדלה של המכסה לכל פרויקט ב-Developer Console. הקצאה של מכסה נוספת היא מוגבלת וכפופה למכסה מקסימלית.

    הערה: תהליך האישור נמשך חודש עד חודשיים.כדאי לתכנן את הבקשות להגדלת המכסה בהתאם. כדי להתכונן להגדלת המכסה לקראת הבחירות לנשיאות ב-2024,צריך לשלוח בקשות להגדלת מכסה עד אוגוסט.

  • מכסה נוספת ל-Civic Info API מיועדת רק לתמיכה בתרחישי שימוש שפונים למשתמשים. בקשות להגדלת מכסה לא מאושרות לתרחישי שימוש אחרים.

הנחיות נוספות לגבי נתונים

קשה במיוחד לעבוד עם הנתונים האלה. חשוב לזכור את הנקודות הבאות.

  • פקידי הבחירות מעדכנים את הנתונים האלה לעיתים קרובות בשבועות האחרונים, ואפילו בימים האחרונים לפני הבחירות. מומלץ להזהיר את המשתמשים שהם צריכים לחזור ולבדוק לפני ההצבעה.
  • רוב הפידים הרשמיים מכילים פלחים של רחובות, כלומר פקידי בחירות משייכים טווח של כתובות לקלפיות ולמיקומי הצבעה. יכול להיות שיהיו מצביעים רשומים בכתובות האלה, ויכול להיות שלא. לכן, במדינות שמספקות פידים רשמיים דרך פרויקט מידע על הצבעה, יכול להיות שכתובת שאין בה מצביעים רשומים תחזיר הצלחה.
  • במדינות שלא מספקות פיד רשמי, רק כתובות שבהן רשום מצביע יחזירו הצלחה.
  • לפעמים יש לנו כמה מקורות לאותו מידע. אנחנו מספקים את המידע האיכותי ביותר שזמין לגבי פרטים ליצירת קשר עם פקידי בחירות מקומיים ומידע על פתקי הצבעה. אין דרך לשנות את ההתנהגות הזו, אלא אם משתמשים בפרמטר officialSourcesOnly כדי להסיר מקורות לא רשמיים. כשמדובר במידע על קלפיות, אנחנו תמיד נותנים עדיפות למקורות נתונים רשמיים על פני מקורות אחרים.
  • אם נגלה בעיות באיכות הנתונים, יכול להיות שלא נציג נתונים לגבי מחוז בחירה מסוים עד שהבעיה תיפתר.
  • אם אין לנו נתונים לגבי כתובת מסוימת, זה לא אומר בהכרח שאף אחד לא רשום שם להצבעה. האפליקציות צריכות להפנות את המשתמשים אל פקידי הבחירות המקומיים לקבלת מידע מלא.
  • התוקף של בחירות יפוג באופן אוטומטי אחרי יום הבחירות. אחרי הנקודה הזו לא יוחזרו נתונים לגבי הבחירות.

שיוך (Attribution)

השיוך ל-Civic Information API הוא אופציונלי. אם מפתחים בוחרים לתת קרדיט ל-Civic Information API ולקשר משתמשים למידע נוסף על ה-API, אנחנו דורשים מהם להשתמש באחת מאפשרויות השפה הבאות למתן קרדיט ובדף האינטרנט המקושר שלמטה:

  • ‫“Powered by the Civic Information API”
  • ‫"מידע על הצבעה שמבוסס על Civic Information API"
  • ‫"Ballot information powered by the Civic Information API"
  • מידע נוסף

קודי סטטוס

קריאות אל voterInfoQuery כוללות את השדה status שמוגדר לערך success כשכתובת מתקבלת. במקרים אחרים, יוחזר קוד שגיאה. בהמשך מפורטים הסברים נפוצים לקודי שגיאה. שימו לב: יכול להיות שיוחזר מידע גם אם מופיע קוד שגיאה.

סטטוס הסבר
success כתובת ה-API המבוקשת מזוהה על ידי ה-API ככתובת תקינה.
noStreetSegmentFound נכון לעכשיו, אין ל-API מידע על הקלפי או המחוז שאליהם הכתובת הזו משתייכת. יכול להיות שאנחנו עדיין מחפשים או מעבדים נתונים חדשים, או שאין מצביעים שנרשמו להצבעה בכתובת הזו.
addressUnparseable הפורמט של הכתובת שביקשת שגוי או שלא ניתן לבצע לה קידוד גיאוגרפי (כלומר, Google Maps API לא יודע דבר על הכתובת הזו).
noAddressParameter לא סופקה כתובת.
multipleStreetSegmentsFound ל-API אין מידע על הכתובת שצוינה, אבל יש לו מידע על כתובות סמוכות. המשתמש צריך ליצור קשר עם פקיד הבחירות כדי לקבל מידע נוסף.
electionOver הבחירות המבוקשות הסתיימו. התוצאות של הבחירות ב-API כבר לא זמינות. מבצעים electionQuery כדי למצוא מזהה של בחירות קרובות.
electionUnknown מזהה הבחירות שצוין בבקשה לא תקין. מבצעים electionQuery כדי למצוא מזהה תקין.
internalLookupFailure אירעה שגיאה לא מזוהה במהלך עיבוד הבקשה.