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

מידע על הצבעה

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

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

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

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

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

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

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

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