Elections: voterInfoQuery

根据选民的注册地址查询与选民相关的信息。 立即尝试

返回的信息可能包括
  • 指定住宅街道地址的投票点(包括早期投票点)
  • 比赛和候选人信息
  • 选举官方信息

请求

HTTP 请求

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

参数

参数名称 说明
必需的查询参数
address string 要查询的选民的注册地址。
可选的查询参数
electionId long

要查找的选举的唯一 ID。您可以访问 https://www.googleapis.com/civicinfo/{version}/elections 来获取选举 ID 列表。

如果查询中未指定选举 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 选民有资格投下已完成选票的地点。选民必须先收到并完成选票,然后才能到达选区。营业地点的现场可能没有选票。这些地点可能在选举日当天或之前营业,如“pollingHours”字段所示。
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 比赛的类型。通常,此选区为“常规”、“初选”或“附加”与候选人的竞赛。对于公投,这将是“Referendum”。
contests[].primaryParty string 如果是党派选举,则会显示其所属政党的名称。
contests[].electorateSpecifications string 关于在此竞赛中投票的其他资格要求的说明。
contests[].special string “是”或“否”,具体取决于竞赛是在正常选举周期之外举行的。
contests[].ballotTitle string 该竞赛选票上的正式标题(如果有)。
contests[].office string 该竞赛的办公室名称。
contests[].level[] list 参与本次比赛的政府部门的级别。如果一个管辖区在两个不同的政府级别执行有效行动,可能会涉及不止一种情况;例如,哥伦比亚特区的市长在locality一级执行,但实际上同时在 administrativeArea2administrativeArea1都执行。


有效值包括:
  • 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 此地区的地理范围。如果未指定,则地区的地理位置未知。以下各项之一:National、Statewide、Congressional、stateUpper、stateLower、countywide、judicial、schoolBoard、cityWide、township、countyCouncil、cityCouncil、ward、special

可接受的值包括:
  • "cityCouncil"
  • "citywide"
  • "congressional"
  • "countyCouncil"
  • "countywide"
  • "judicial"
  • "national"
  • "schoolBoard"
  • "special"
  • "stateLower"
  • "stateUpper"
  • "statewide"
  • "township"
  • "ward"
contests[].district.id string 此学区的标识符(相对于其范围)。例如,第 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 候选人频道的唯一公开标识符。
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 此管理机构提供的最后一刻或紧急通知文本。
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 这些数据是否来自政府官方来源。

试试看!