開發人員資料指南

投票資訊

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 提供」
「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`	處理要求時發生不明錯誤。