Elections: voterInfoQuery

根據選民登記的地址查詢選民的相關資訊。 立即試用。

傳回的資訊可能包括
  • 特定住宅街道地址的投票地點 (包括早期投票站)
  • 競賽與候選人資訊
  • 選舉官方資訊

要求

HTTP 要求

GET https://www.googleapis.com/civicinfo/v2/voterinfo

參數

參數名稱 值 說明
必要的查詢參數
address string 查詢選民的登記地址。
選用查詢參數
electionId long

要查詢的選舉專屬 ID。如需選舉 ID 清單，請前往 https://www.googleapis.com/civicinfo/{version}/elections。

如果查詢中未指定選舉 ID，且特定選民在有多個選舉相關資料中，系統會在 otherElections 回應欄位中提供其他選舉資料。

如果指定的選民地址沒有即時選舉，系統只會在已指定選舉 ID 時傳回資料。

在這種情況下，我們建議任何工具使用指定的選舉 ID 發出第二次查詢，確保使用者能取得正確的投票地點、競賽和選舉官方資訊。
officialOnly boolean 如果設為 True，系統只會傳回官方狀態來源的資料。 (預設值：false)

要求主體

請勿使用這個方法提供要求主體。

回應

如果成功的話，這個方法會傳回回應內文，其結構如下：

{
  "kind": "civicinfo#voterInfoResponse",
  "election": elections Resource,
  "otherElections": [
    elections Resource
  ],
  "normalizedInput": {
    "locationName": string,
    "line1": string,
    "line2": string,
    "line3": string,
    "city": string,
    "state": string,
    "zip": string
  },
  "pollingLocations": [
    {
      "address": {
        "locationName": string,
        "line1": string,
        "line2": string,
        "line3": string,
        "city": string,
        "state": string,
        "zip": string
      },
      "notes": string,
      "pollingHours": string,
      "name": string,
      "voterServices": string,
      "startDate": string,
      "endDate": string,
      "latitude": double,
      "longitude": double,
      "sources": [
        {
          "name": string,
          "official": boolean
        }
      ]
    }
  ],
  "earlyVoteSites": [
    {
      "address": {
        "locationName": string,
        "line1": string,
        "line2": string,
        "line3": string,
        "city": string,
        "state": string,
        "zip": string
      },
      "notes": string,
      "pollingHours": string,
      "name": string,
      "voterServices": string,
      "startDate": string,
      "endDate": string,
      "latitude": double,
      "longitude": double,
      "sources": [
        {
          "name": string,
          "official": boolean
        }
      ]
    }
  ],
  "dropOffLocations": [
    {
      "address": {
        "locationName": string,
        "line1": string,
        "line2": string,
        "line3": string,
        "city": string,
        "state": string,
        "zip": string
      },
      "notes": string,
      "pollingHours": string,
      "name": string,
      "voterServices": string,
      "startDate": string,
      "endDate": string,
      "latitude": double,
      "longitude": double,
      "sources": [
        {
          "name": string,
          "official": boolean
        }
      ]
    }
  ],
  "contests": [
    {
      "type": string,
      "primaryParty": string,
      "electorateSpecifications": string,
      "special": string,
      "ballotTitle": string,
      "office": string,
      "level": [
        string
      ],
      "roles": [
        string
      ],
      "district": {
        "name": string,
        "scope": string,
        "id": string
      },
      "numberElected": long,
      "numberVotingFor": long,
      "ballotPlacement": long,
      "candidates": [
        {
          "name": string,
          "party": string,
          "candidateUrl": string,
          "phone": string,
          "photoUrl": string,
          "email": string,
          "orderOnBallot": long,
          "channels": [
            {
              "type": string,
              "id": string
            }
          ]
        }
      ],
      "referendumTitle": string,
      "referendumSubtitle": string,
      "referendumUrl": string,
      "referendumBrief": string,
      "referendumText": string,
      "referendumProStatement": string,
      "referendumConStatement": string,
      "referendumPassageThreshold": string,
      "referendumEffectOfAbstain": string,
      "referendumBallotResponses": [
        string
      ],
      "sources": [
        {
          "name": string,
          "official": boolean
        }
      ]
    }
  ],
  "state": [
    {
      "name": string,
      "electionAdministrationBody": {
        "name": string,
        "electionInfoUrl": string,
        "electionRegistrationUrl": string,
        "electionRegistrationConfirmationUrl": string,
        "electionNoticeText": string,
        "electionNoticeUrl": string,
        "absenteeVotingInfoUrl": string,
        "votingLocationFinderUrl": string,
        "ballotInfoUrl": string,
        "electionRulesUrl": string,
        "voter_services": [
          string
        ],
        "hoursOfOperation": string,
        "correspondenceAddress": {
          "locationName": string,
          "line1": string,
          "line2": string,
          "line3": string,
          "city": string,
          "state": string,
          "zip": string
        },
        "physicalAddress": {
          "locationName": string,
          "line1": string,
          "line2": string,
          "line3": string,
          "city": string,
          "state": string,
          "zip": string
        },
        "electionOfficials": [
          {
            "name": string,
            "title": string,
            "officePhoneNumber": string,
            "faxNumber": string,
            "emailAddress": string
          }
        ]
      },
      "local_jurisdiction": (AdministrationRegion),
      "sources": [
        {
          "name": string,
          "official": boolean
        }
      ]
    }
  ],
  "mailOnly": boolean
}
屬性名稱 值 說明 附註
kind string 識別資源的種類。值：固定字串 "civicinfo#voterInfoResponse"。
election nested object 查詢的選舉資訊。
otherElections[] list 如果選民地址有多個選舉，API 回應中會填入 otherElections 欄位，可能有兩種可能情況：

1.如果這些選舉的日期不同，API 會傳回第一次/最早選舉的投票資訊。如果最早的選舉不是原選舉，請使用 electionId 欄位在第二個 API 要求中指定要選的選舉 ID。

2. 如果這些選舉的同一天舉行，API 不會傳回任何投票地點、競賽或選舉官方資訊，以確保已進行額外的查詢。針對面向使用者的應用程式，建議您向使用者顯示這些選舉，以便區分兩者。請使用 electionId 欄位針對與使用者相關的選舉提出第二個 API 要求。
normalizedInput nested object 要求位址的正規化版本
normalizedInput.locationName string 地點的名稱。
normalizedInput.line1 string 這個地址的街道名稱和門牌號碼。
normalizedInput.line2 string 地址的第二行 (如有需要)。
normalizedInput.line3 string 地址的第三行 (如有需要)。
normalizedInput.city string 地址所在的城市或鄉鎮。
normalizedInput.state string 美國兩個字母的州名縮寫。
normalizedInput.zip string 地址的美國郵遞區號。
mailOnly boolean 指定僅透過郵寄選票的方式指定選區投票者 (也可選擇投下選票)。

投票地點、提前投票地點與下車地點

資源名稱 值 說明 附註
pollingLocations[] list 選民可在選舉日投票的地區。
pollingLocations[].address nested object 地點的地址。
pollingLocations[].address.locationName string 地點的名稱。
pollingLocations[].address.line1 string 這個地址的街道名稱和門牌號碼。
pollingLocations[].address.line2 string 地址的第二行 (如有需要)。
pollingLocations[].address.line3 string 地址的第三行 (如有需要)。
pollingLocations[].address.city string 地址所在的城市或鄉鎮。
pollingLocations[].address.state string 美國兩個字母的州名縮寫。
pollingLocations[].address.zip string 地址的美國郵遞區號。
pollingLocations[].notes string 這個地點的相關附註 (例如無障礙坡道或無障礙入口)。
pollingLocations[].pollingHours string 描述這個地點的營業時間。
pollingLocations[].name string 提前投票網站或下車地點的名稱。系統不會針對投票地點填入這個欄位。
pollingLocations[].voterServices string 這個提前投票網站或下車地點提供的服務。系統不會針對投票地點填入這個欄位。
pollingLocations[].startDate string 可以使用這個提前投票網站或下車地點的第一天。系統不會針對投票地點填入這個欄位。
pollingLocations[].endDate string 可以使用這個提前投票網站或下車地點的最後一天。系統不會針對投票地點填入這個欄位。
pollingLocations[].latitude string 位置的緯度，以赤道以北的角度表示。請注意，部分地區可能無法使用這個欄位。
pollingLocations[].longitude string 地點的經度，以本初子午線以度為單位。請注意，部分地區可能無法使用這個欄位。
pollingLocations[].sources[] list 這個地點的來源清單。如果系統列出多個來源，這些資料都是從這些來源匯總而來。
pollingLocations[].sources[].name string 資料來源的名稱。
pollingLocations[].sources[].official boolean 這項資料是否來自政府官方來源。
earlyVoteSites[] list 投票者可在選舉日之前提前投票的國家/地區。
earlyVoteSites[].address nested object 地點的地址。
earlyVoteSites[].address.locationName string 地點的名稱。
earlyVoteSites[].address.line1 string 這個地址的街道名稱和門牌號碼。
earlyVoteSites[].address.line2 string 地址的第二行 (如有需要)。
earlyVoteSites[].address.line3 string 地址的第三行 (如有需要)。
earlyVoteSites[].address.city string 地址所在的城市或鄉鎮。
earlyVoteSites[].address.state string 美國兩個字母的州名縮寫。
earlyVoteSites[].address.zip string 地址的美國郵遞區號。
earlyVoteSites[].notes string 這個地點的相關附註 (例如無障礙坡道或無障礙入口)。
earlyVoteSites[].pollingHours string 描述這個地點的營業時間。
earlyVoteSites[].name string 提前投票網站或下車地點的名稱。系統不會針對投票地點填入這個欄位。
earlyVoteSites[].voterServices string 這個提前投票網站或下車地點提供的服務。系統不會針對投票地點填入這個欄位。
earlyVoteSites[].startDate string 可以使用這個提前投票網站或下車地點的第一天。系統不會針對投票地點填入這個欄位。
earlyVoteSites[].endDate string 可以使用這個提前投票網站或下車地點的最後一天。系統不會針對投票地點填入這個欄位。
earlyVoteSites[].latitude string 位置的緯度，以赤道以北的角度表示。請注意，部分地區可能無法使用這個欄位。
earlyVoteSites[].longitude string 地點的經度，以本初子午線以度為單位。請注意，部分地區可能無法使用這個欄位。
earlyVoteSites[].sources[] list 這個地點的來源清單。如果系統列出多個來源，這些資料都是從這些來源匯總而來。
earlyVoteSites[].sources[].name string 資料來源的名稱。
earlyVoteSites[].sources[].official boolean 這項資料是否來自政府官方來源。
dropOffLocations[] list 選民有資格放棄完整投票的國家/地區。投票者必須先收到並完成投票，才能抵達該地點。該地點可能沒有在場舉行投票。這些地點可能會在選舉日當天或之前開放營業，如「投票時段」欄位所示。
dropOffLocations[].address nested object 地點的地址。
dropOffLocations[].address.locationName string 地點的名稱。
dropOffLocations[].address.line1 string 這個地址的街道名稱和門牌號碼。
dropOffLocations[].address.line2 string 地址的第二行 (如有需要)。
dropOffLocations[].address.line3 string 地址的第三行 (如有需要)。
dropOffLocations[].address.city string 地址所在的城市或鄉鎮。
dropOffLocations[].address.state string 美國兩個字母的州名縮寫。
dropOffLocations[].address.zip string 地址的美國郵遞區號。
dropOffLocations[].notes string 這個地點的相關附註 (例如無障礙坡道或無障礙入口)。
dropOffLocations[].pollingHours string 描述這個地點的營業時間。
dropOffLocations[].name string 提前投票網站或下車地點的名稱。系統不會針對投票地點填入這個欄位。
dropOffLocations[].voterServices string 這個提前投票網站或下車地點提供的服務。系統不會針對投票地點填入這個欄位。
dropOffLocations[].startDate string 可以使用這個提前投票網站或下車地點的第一天。系統不會針對投票地點填入這個欄位。
dropOffLocations[].endDate string 可以使用這個提前投票網站或下車地點的最後一天。系統不會針對投票地點填入這個欄位。
dropOffLocations[].latitude string 位置的緯度，以赤道以北的角度表示。請注意，部分地區可能無法使用這個欄位。
dropOffLocations[].longitude string 地點的經度，以本初子午線以度為單位。請注意，部分地區可能無法使用這個欄位。
dropOffLocations[].sources[] list 這個地點的來源清單。如果系統列出多個來源，這些資料都是從這些來源匯總而來。
dropOffLocations[].sources[].name string 資料來源的名稱。
dropOffLocations[].sources[].official boolean 這項資料是否來自政府官方來源。

競賽

資源名稱 值 說明 附註
contests[] list 顯示於選民投票的競賽。
contests[].type string 比賽類型。對於候選人的競賽，通常應為「一般」、「主要」或「延長賽」。若是公投，此值會是「推薦」。
contests[].primaryParty string 如果這是某政黨的選舉名稱，說明相關當事方的姓名。
contests[].electorateSpecifications string 說明這項競賽的投票資格規定說明。
contests[].special string 根據是否在正常選舉週期外舉行而定，顯示為「是」或「否」。
contests[].ballotTitle string 這場競賽的投票資訊官方標題 (如果有的話)。
contests[].office string 本次競賽的辦公室名稱。
contests[].level[] list 這場比賽的政府單位層級。如果管轄區實際上有兩個不同層級的政府事務，可能有多種不同情況。例如，哥倫比亞特區市長在locality層級行動，但同時在 administrativeArea2 和 administrativeArea1 採取有效行動。

有效的值包括：
  • international -- 國際政府，例如聯合國或歐盟。
  • country ：國家級政府，例如美國聯邦政府。
  • administrativeArea1：國家/地區頂層行政部門的政府，例如美國。
  • regional -- 所在管轄區的區域性政府；其管轄區可能跨越標準行政區；在美國為很少見，但在其他國家/地區中的大型城市很常見。
  • administrativeArea2：國家/地區第二層行政部門的政府，例如美國郡。
  • locality：市政府或市政政府。
  • subLocality1 -- 華盛頓哥倫比亞特區等頂層行政區的政府單位。
  • subLocality2：城市第二層行政區的政府，例如華盛頓特區 (DC's Advisory Neighborhood Councils)。
  • special - 僅為特殊用途政府設立的地方行政區，例如土壤和水域保護區。
contests[].roles[] list 這場比賽的參賽辦公室職位。我們不能詳盡說明或明確指出特定辦公室的一系列職責，但主要是為了提供一般類別，供一般大眾選擇或選擇辦公室清單。

有效價值包括：
  • headOfState ：政府的首席公開代表。國家/地區的領導人通常稱為「總統」。
  • headOfGovernment - 政府執行長。在美國，這是總統；其他國家/地區通常是首相。而在較低層級，可能是州長或市長。
  • deputyHeadOfGovernment -- 負責假使政府在死亡或民選政府主管的人身安全時擔任政府領導人。在美國，這是副總裁。這個辦公室可能也有其他職責。
  • governmentOfficer -- 現任執行主管-分支官員。在美國的各州，可能包括律師、律師、秘書或州政府或律師等角色。
  • executiveCouncil -- 執行委員會的成員，負責以小組形式擔任高階主管職務。相關例子包括印第安納州郡的委員。
  • legislatorUpperBody - 雙相機立法機關上半部，或單機攝影機立法的唯一身體。
  • legislatorLowerBody -- 雙相機軍團下半部的成員。
  • highestCourtJudge - 特定政府 (例如州立最高法院) 最高法院的法官。
  • judge：
  • schoolBoard：當地學校董事會的成員。
  • specialPurposeOfficer - 專為單一特定用途設計的警官，例如土壤和水域保育委員會的成員，或蚊子加工官員。
contests[].district nested object 本次選舉的選舉區相關資訊。
contests[].district.name string 行政區的名稱。
contests[].district.scope string 這個區域的地理範圍。如未指定，就無法得知這個區域的地理位置。以下其中之一：全國、州/省、國會、StateUpper、StateLower、countywide、judicial、SchoolBoard、CityWide、township、countyCouncil、cityCouncil、ward、設定中

可接受的值如下：
  • "cityCouncil"
  • "citywide"
  • "congressional"
  • "countyCouncil"
  • "countywide"
  • "judicial"
  • "national"
  • "schoolBoard"
  • "special"
  • "stateLower"
  • "stateUpper"
  • "statewide"
  • "township"
  • "ward"
contests[].district.id string 這個區域相對於範圍的 ID。舉例來說，第 34 州參議院的學區 ID 為「34」，並將狀態設為 stateUpper。
contests[].numberElected long 本競賽中即將選出公職的候選人人數。
contests[].numberVotingFor long 選民可在這項競賽中投票的候選人人數。
contests[].ballotPlacement long 指定這項競賽在選民投票上的位置的數字。
contests[].candidates[] list 此比賽的候選人選項。
contests[].candidates[].name string 候選人姓名。
contests[].candidates[].party string 候選人所屬政黨的全名。
contests[].candidates[].candidateUrl string 候選人的廣告活動網站網址。
contests[].candidates[].phone string 候選人競選部門的語音電話號碼。
contests[].candidates[].photoUrl string 候選人相片的網址。
contests[].candidates[].email string 候選人廣告活動的電子郵件地址。
contests[].candidates[].orderOnBallot long 候選人在本次競賽的票選中所顯示的順序。
contests[].candidates[].channels[] list 此候選人的已知 (社群媒體) 媒體管道清單。
contests[].candidates[].channels[].type string 頻道類型。以下僅列出部分管道類型。我們之後會新增更多頻道類型。以下其中之一：
  • GooglePlus
  • YouTube
  • Facebook
  • Twitter
contests[].candidates[].channels[].id string 候選人頻道的專屬公開 ID。
contests[].referendumTitle string 公投的標題 (例如「比例 42」)。這個欄位僅針對「推薦」類型的比賽填入資料。
contests[].referendumSubtitle string 關於公投的簡短說明。這個欄位僅針對「推薦」類型的比賽填入資料。
contests[].referendumUrl string 公投連結。這個欄位僅針對「推薦」類型的比賽填入資料。
contests[].referendumBrief string 指定公投的簡短摘要，通常位於標題下方的選票中，但位於文字上方。這個欄位僅針對「推薦」類型的比賽填入資料。
contests[].referendumText string 公投全文。這個欄位僅針對「推薦」類型的比賽填入資料。
contests[].referendumProStatement string 提出異議的聲明。投票時不一定要出現。這個欄位僅針對「推薦」類型的比賽填入資料。
contests[].referendumConStatement string 反對公投的陳述。投票時不一定要出現。這個欄位僅針對「推薦」類型的比賽填入資料。
contests[].referendumPassageThreshold string 公投通過之投票門檻，例如「三分之二」。這個欄位僅針對「推薦」類型的比賽填入資料。
contests[].referendumEffectOfAbstain string 指出提案缺少哪些作用 (即不是投票) 對提案有何影響 (即是否視作弊的影響)。這個欄位僅針對「推薦」類型的比賽填入資料。
contests[].referendumBallotResponses[] list 公投的投票回覆集。選票的回應代表選票上的某一行。常見的例子包括「是」或「否」代表公投，或是續選競賽的評審姓名。這個欄位僅針對「推薦」類型的比賽填入資料。
contests[].sources[] list 此比賽的來源清單。如果列出多個來源，系統會匯總這些來源的資料。
contests[].sources[].name string 資料來源的名稱。
contests[].sources[].official boolean 這項資料是否來自政府官方來源。

選舉官員

資源名稱 值 說明 附註
state[] list 選民投票所在州的地方選舉資訊。以美國來說，這個陣列只會有一個元素。
state[].name string 管轄區的名稱。
state[].electionAdministrationBody nested object 這個區域的選舉行政機構。
state[].electionAdministrationBody.name string 這個選舉行政機構的名稱。
state[].electionAdministrationBody.electionInfoUrl string 這個行政機關為了查詢一般選舉資訊而提供的網址，
state[].electionAdministrationBody.electionRegistrationUrl string 這個行政機關針對查詢登記投票方式所提供的網址，
state[].electionAdministrationBody.electionRegistrationConfirmationUrl string 由這個行政機關提供的網址，用於確認選民已登記投票。
state[].electionAdministrationBody.electionNoticeText string 由這個管理機構提供的最後一分鐘或緊急通知文字。
state[].electionAdministrationBody.electionNoticeUrl string 由這個行政機關提供的網址，可用於提供過去一分鐘或緊急通知的其他資訊。
state[].electionAdministrationBody.absenteeVotingInfoUrl string 由這個行政機關提供的無人投票資訊網址。
state[].electionAdministrationBody.votingLocationFinderUrl string 這個行政機關提供的網址，用來查詢投票地點。
state[].electionAdministrationBody.ballotInfoUrl string 由這個行政機關提供的網址，可將比賽資訊提供給選民。
state[].electionAdministrationBody.electionRulesUrl string 由這個行政機關提供的網址，用來說明選民的選舉規則。
state[].electionAdministrationBody.voter_services[] list 此管理機構可能提供的服務說明。
state[].electionAdministrationBody.hoursOfOperation string 這個行政機關的營業時間說明。
state[].electionAdministrationBody.correspondenceAddress nested object 這個管理機構的郵寄地址。
state[].electionAdministrationBody.correspondenceAddress.locationName string 地點的名稱。
state[].electionAdministrationBody.correspondenceAddress.line1 string 這個地址的街道名稱和門牌號碼。
state[].electionAdministrationBody.correspondenceAddress.line2 string 地址的第二行 (如有需要)。
state[].electionAdministrationBody.correspondenceAddress.line3 string 地址的第三行 (如有需要)。
state[].electionAdministrationBody.correspondenceAddress.city string 地址所在的城市或鄉鎮。
state[].electionAdministrationBody.correspondenceAddress.state string 美國兩個字母的州名縮寫。
state[].electionAdministrationBody.correspondenceAddress.zip string 地址的美國郵遞區號。
state[].electionAdministrationBody.physicalAddress nested object 這個行政機構的實際地址。
state[].electionAdministrationBody.physicalAddress.locationName string 地點的名稱。
state[].electionAdministrationBody.physicalAddress.line1 string 這個地址的街道名稱和門牌號碼。
state[].electionAdministrationBody.physicalAddress.line2 string 地址的第二行 (如有需要)。
state[].electionAdministrationBody.physicalAddress.line3 string 地址的第三行 (如有需要)。
state[].electionAdministrationBody.physicalAddress.city string 地址所在的城市或鄉鎮。
state[].electionAdministrationBody.physicalAddress.state string 美國兩個字母的州名縮寫。
state[].electionAdministrationBody.physicalAddress.zip string 地址的美國郵遞區號。
state[].electionAdministrationBody.electionOfficials[] list 這個選舉管理機構的選舉官員。
state[].electionAdministrationBody.electionOfficials[].name string 選舉官員的全名。
state[].electionAdministrationBody.electionOfficials[].title string 選舉官員的職稱。
state[].electionAdministrationBody.electionOfficials[].officePhoneNumber string 選舉官員的辦公室電話號碼。
state[].electionAdministrationBody.electionOfficials[].faxNumber string 選舉官員的傳真號碼。
state[].electionAdministrationBody.electionOfficials[].emailAddress string 選舉官員的電子郵件地址。
state[].local_jurisdiction nested object 提供這位選民選舉資訊的城市或縣市。這個物件可包含與狀態相同的元素。
state[].sources[] list 這個區域的來源清單。如果系統列出多個來源，這些資料都是從這些來源匯總而來。
state[].sources[].name string 資料來源的名稱。
state[].sources[].official boolean 這項資料是否來自政府官方來源。

試試看！