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

גיאוגרפיה פוליטית ונציגים שנבחרו

Google Civic Information API כולל מידע על חטיבות גיאוגרפיות פוליטיות ונציגים נבחרים של כתובות בארה"ב, מהרמה הפדרלית ועד לרמה המקומית. נכון להיום, הכיסוי של מחוזות המדינה, המחוז והקונגרס עומד על כ-100%, והמטרה שלנו היא להגיע ליותר מ-90% כיסוי של מחוזות המחוקקים במדינה. רמות נמוכות יותר, כמו עיריות ומועצות מחוזיות, מוגשות על בסיס ההנחה הטובה ביותר וישתפרו עם הזמן.

אנחנו מצפים לקבל מידע עדכני על כל נבחרי ציבור בממשל הפדרלי, ברמת המדינה והמחוז ועל נציגים רשמיים בעיר הגדולה ביותר בכל מדינה בארה"ב, וגם בערים עם יותר מ-250,000 נפש. אנחנו צוברים את הנתונים האלה מכמה מקורות ומציגים את המידע האיכותי ביותר שזמין. אם נגלה בעיות באיכות הנתונים, ייתכן שנפסיק להציג נתונים לגבי חטיבות גיאוגרפיות מסוימות, נציגים רשמיים של גופים ציבוריים או נציגים רשמיים של גופים ציבוריים.

מידע על ההצבעה

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

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

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

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

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

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

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

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

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

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

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

שיוך (Attribution)

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

  • "מופעל על ידי Civic Information API"
  • "נתוני ההצבעה מבוססים על Civic Information API"
  • "Ballot information שמופעל על ידי Civic Information API"
  • "מידע ייצוגי שמופעל על ידי Civic Information API"
  • מידע נוסף

קודי סטטוס

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

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