開發人員資料指南

政治地理位置和選民

Google Civic Information API 提供政治地理區域部門和民選代表的相關資訊，說明從聯邦政府到地方層級的美國地址。目前，州、郡和國會選區的覆蓋率達到 100% 以上，州立法機關的覆蓋率則達到 90% 以上。城市和郡立委員會等較低樓層會盡可能提供最佳服務，而且會隨著時間逐漸進步。

我們預計能夠取得美國各州聯邦、州和郡級的所有民選官員最新資訊，以及人口超過 250,000 的所有城市。我們會從多個來源匯總這些資料，並提供最高品質的資訊。一旦發現資料品質問題，我們可能會停止傳回特定地理區域部門、民選官員或民選官員的資料。

投票資訊

Google Civic Information API 會將投票地點、提前投票地點、當地選舉官方聯絡資訊和投票資訊等公民資訊傳回給 Voting Information Project (投票資訊專案) 支援的使用者。

資料可用性

開發人員指南

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

  • 遵守《API 服務條款》。
  • 使用 API 時，開發人員同意遵循任何快取控制標頭 (如果有的話)。如果缺少快取控制標頭，開發人員同意，投票地點和競賽資訊的快取保留時間超過 24 小時，辦公室持有者和學區超過 30 天。
  • 使用 API 的開發人員應盡力確保所有使用者都享有相同的使用體驗。我們不接受區隔劃分、A/B 測試或類似的實驗。

  • 如需額外配額來啟用所需用途，可以在 Developer Console 中申請提高各項專案配額。額外配額的佈建有限，且會面臨最高配額上限。

    注意：核准程序需要 1 至 2 個月，請據此規劃配額提高要求。如要為 2024 年總統大選配額做好準備，請在 8 月前提交配額申請。

  • Civic Info API 的額外配額僅適用於支援使用者的用途。但其他用途無法提出配額提高要求。

其他資料指南

這些資料相當難以處理。請記住以下要點。

  • 選舉官員會在最近幾週 (甚至是選舉前幾天) 修改這項資料。建議您提醒使用者在投票前應返回查看。
  • 大部分的官方動態饋給都包含街道區塊，意味著選務官員可將多個地址與選區和投票地點相結合。有效範圍不一定是位於這些地址的選民。因此，如果是透過 Voting Information Project 提供官方動態饋給的州，登記投票者的地址將有機會獲得成功。
  • 如果是未提供官方動態饋給的州，系統只會傳回已註冊的選民電子郵件地址。
  • 我們有時會提供多個資訊來源，我們提供最優質的當地選舉官方聯絡資訊和投票資訊。除非透過官方 SourcesOnly 參數移除非官方來源，否則無法覆寫這項行為。針對投票地點資訊，我們一律會優先顯示官方資料來源，而非其他來源。
  • 如果發現資料品質問題，在問題解決前，我們可能不會傳回特定選舉區的資料。
  • 如果地址沒有資料，不一定代表沒有人登記投票。申請應將使用者導向當地選舉官員提供完整資訊。
  • 選舉會在選舉日過後自動失效。時間過後，系統就不會傳回任何選舉資料。

歸因

您可以選擇是否提供 Civic Information API 的作者資訊。如果開發人員選擇引述 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 Maps API 無法得知這個地址的任何相關資訊)。
noAddressParameter 未提供地址。
multipleStreetSegmentsFound API 無法找到指定地址的資訊，但包含鄰近地址的資訊。詳情請使用者向選舉官員洽詢詳情。
electionOver 所要求的選舉已結束。不再提供選舉的 API 結果。執行 electionQuery，找出近期選舉的 ID。
electionUnknown 要求的選舉 ID 無效。執行 electionQuery 來找出有效的 ID。
internalLookupFailure 處理要求時發生不明錯誤。