開發人員資料指南

投票資訊

Google Civic Information API 會針對投票資訊專案支援的選舉，向使用者傳回公民資訊，例如投票地點、提前投票地點、當地選舉辦公室聯絡資訊和選票資訊。

資料可用性

開發人員規範

我們要求所有開發人員遵守下列規範：

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

  • 如果您需要額外配額才能執行用途，可以在 開發人員控制台中要求增加每個專案的配額。額外配額的供應量有限，且須遵守最高限額。

    注意：核准程序需要 1 到 2 個月的時間，請據此規劃配額提高要求。如要為 2024 年總統大選提高配額，請在 8 月前提交配額要求。

  • Civic Info API 的額外配額僅適用於支援面向使用者的用途。我們不會核准其他用途的配額增加要求。

其他資料規範

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

  • 選舉官員經常在選舉前幾週，甚至是選舉前幾天，都會修訂這項資料。建議您提醒使用者在投票前先查看。
  • 大多數官方動態饋給都包含街道區段，也就是說選務人員會將一系列地址與選區和投票地點連結。範圍內的選民可能已註冊地址，也可能未註冊地址。因此，對於透過投票資訊專案提供官方動態饋給的州，如果地址沒有登記選民，系統可能會傳回成功訊息。
  • 對於未提供官方動態饋給的州，只有有註冊選民住址的地址會傳回成功。
  • 有時我們會從多個來源取得相同資訊。我們會提供最優質的當地選舉辦公單位聯絡資訊和選票資訊。除了透過 officialSourcesOnly 參數排除非官方來源，沒有其他方法可以覆寫這項行為。對於投票地點資訊，我們一律優先使用官方資料來源，而非其他來源。
  • 如果我們發現資料品質問題，可能會在問題解決前，不提供特定選區的資料。
  • 如果我們沒有某個地址的資料，並不代表該地址沒有任何已註冊的選民。應用程式應將使用者導向當地選舉官員，以取得完整資訊。
  • 選舉活動會在選舉日後自動失效。系統不會傳回該選舉之後的任何資料。

歸因

您可以選擇是否要為 Civic Information API 提供出處資訊。如果開發人員選擇歸功於 Civic Information API，並將使用者連結至 Civic Information API 的更多資訊，我們要求開發人員使用下列其中一種歸功語言選項和連結網頁：

  • 「由 Civic Information API 提供技術支援」
  • 「投票資訊由 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 處理要求時發生不明錯誤。