開發人員資料指南

投票資訊

Google Civic Information API 會針對投票資訊計畫支援的選舉，向使用者提供投票所、提前投票地點、當地選舉官員聯絡資訊和選票資訊等公民資訊。

資料可用性

開發人員規範

所有開發人員都必須遵守下列規範：

  • 遵守 API 服務條款。
  • 使用 API 即表示開發人員同意遵守任何快取控制標頭 (如有)。如果沒有快取控制標頭，開發人員同意投票地點和競賽資訊的快取時間不超過 24 小時，辦公室持有人和選區的快取時間不超過 30 天。
  • 使用 API 的開發人員應盡一切努力，確保所有使用者都能獲得相同體驗。我們不允許進行保留測試、A/B 測試或類似實驗。

  • 如要啟用用途，但配額不足，可以在開發人員控制台中，為每個專案申請提高配額。額外配額的供應量有限，且設有上限。

    注意：審核程序需要 1 到 2 個月，因此建議開發人員據此規劃配額增加要求。如要提高 11 月選舉的配額，我們強烈建議您最晚在 8 月底前提交配額要求。

  • Civic Info API 的額外配額僅適用於使用者面向的用途。其他用途的配額提高要求不會獲得核准。

其他資料規定

這類資料特別難以處理。請注意以下幾點。

  • 選舉官員通常會在選舉前幾週，甚至是前幾天，修訂這類資料。建議您警告使用者，投票前請先確認。
  • 大多數官方動態饋給都包含街道區段，也就是選舉官員將一系列地址與選區和投票所綁定。這些範圍可能沒有任何選民登記在這些地址。因此，如果州政府透過「投票資訊計畫」提供官方動態消息，沒有登記選民的地址可能會傳回成功。
  • 如果州政府未提供官方動態饋給，只有已登記選民的地址才會傳回成功。
  • 有時，同一項資訊會有多個來源。我們會提供當地選舉官員聯絡資訊和選票資訊，確保資訊品質最高。除了透過 officialSourcesOnly 參數排除非官方來源，沒有其他方法可以覆寫這項行為。如果能取得官方資料來源的投票所資訊，我們一律會優先採用。
  • 如果我們發現資料品質問題，可能會在問題解決前，不傳回特定選區的資料。
  • 如果我們沒有某個地址的資料，不一定代表該地址沒有已登記的選民。應用程式應引導使用者向當地選舉官員查詢完整資訊。
  • 選舉會在投票日後自動到期。之後的選舉就不會再傳回任何資料。

歸因

您可以選擇是否要註明出處為 Civic Information API。如果開發人員選擇將出處歸給 Civic Information API，並連結使用者以取得 Civic Information API 的詳細資訊，我們要求開發人員使用下列其中一個出處語言選項，以及下方連結的網頁：

  • 「由 Civic Information API 提供技術」
  • 「投票資訊由 Civic Information API 提供」
  • 「Ballot information powered by the Civic Information API」(選票資訊由 Civic Information API 提供)
  • 「瞭解詳情」

狀態碼

呼叫 voterInfoQuery 時，如果系統接受地址，會將 status 欄位設為 success。在其他情況下，則會傳回錯誤代碼。以下是錯誤代碼的常見說明。請注意，即使出現錯誤代碼，系統仍可能會傳回資訊。

狀態 說明
success API 會將要求的地址視為有效地址。
noStreetSegmentFound 目前 API 沒有這項地址所屬的選區和/或行政區資訊。我們可能仍在尋找/處理新資料，或是沒有任何選民在這個地址登記投票。
addressUnparseable 要求的地址格式不正確，或無法進行地理編碼 (也就是說，Google 地圖 API 不知道這個地址)。
noAddressParameter 未提供地址。
multipleStreetSegmentsFound API 找不到指定地址的資訊，但有附近地址的資訊。如需更多資訊，使用者應洽詢選舉官員。
electionOver 要求的選舉已結束。選舉的 API 結果已無法再使用，進行 electionQuery，找出即將舉行的選舉 ID。
electionUnknown 要求提供的選舉 ID 無效，進行 electionQuery，找出有效 ID。
internalLookupFailure 處理要求時發生不明錯誤。