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 會傳回第一次/最早選舉的投票資訊。如果最早的選舉並非預計的選舉，請在第二個 API 要求中，使用 electionId 欄位指定所需選舉的選舉 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 -- 市內第二級行政區的政府，例如華盛頓特區的顧問社區委員會。 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	這個區域的地理範圍。如果未指定，則無法得知行政區的地理位置。以下其中之一：全國、州/省、國會、州立大學、州立下、郡/縣、司法、學校委員會、全市、鄉鎮、郡縣、市政府、國會、特殊 可接受的值為： 「cityCouncil」 「citywide」 「congressional」 「countyCouncil」 「countywide」 「judicial」 「national」 「schoolBoard」 「special」 「stateLower」 「stateUpper」 「statewide」 「township」 「ward」
contests[].district.id	string	這個學區的 ID，相對於其範圍。舉例來說，第 34 州參議院編號會是「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 號提案」)。只有「Referendum」類型的競賽才需填寫這個欄位。
contests[].referendumSubtitle	string	公投的簡短說明。只有「Referendum」類型的競賽才需填寫這個欄位。
contests[].referendumUrl	string	公投的連結。只有「Referendum」類型的競賽才需填寫這個欄位。
contests[].referendumBrief	string	指出公投的簡短摘要，該資訊通常出現在標題下方、文字上方。只有「Referendum」類型的競賽才需填寫這個欄位。
contests[].referendumText	string	公投的全文。只有「Referendum」類型的競賽才需填寫這個欄位。
contests[].referendumProStatement	string	一份有利於公投的陳述。但這不一定出現在選票上。只有「Referendum」類型的競賽才需填寫這個欄位。
contests[].referendumConStatement	string	與公投相反的陳述。但這不一定出現在選票上。只有「Referendum」類型的競賽才需填寫這個欄位。
contests[].referendumPassageThreshold	string	公投必須通過的票數門檻，例如「三分之二」只有「Referendum」類型的競賽才需填寫這個欄位。
contests[].referendumEffectOfAbstain	string	說明讓提案無法 (而非投票) 對提案產生什麼影響 (即是否將缺漏視為決選票)。只有「Referendum」類型的競賽才需填寫這個欄位。
contests[].referendumBallotResponses[]	list	公投的投票回覆集合。代表投票中的一段投票表示投票正確，常見的例子包括「是」或「否」或舉辦保留比賽的評審姓名。只有「Referendum」類型的競賽才需填寫這個欄位。
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	此管理機構提供的最近 1 分鐘或緊急通知文字。
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	這項資料是否來自政府官方來源。

試試看！