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 选民可以投下已完成选票的地点。选民必须在到达相应地点之前已收到并完成选票。该地点可能没有选票。这些地点可能会在选举日当天或之前开放，如 PolingHours 字段所示。
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，但实际上也同时在 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 此地区的地理范围。如果未指定，则学区的地理位置未知。以下各项之一：national、statewide、congressional、stateUpper、stateLower、countywide、judicial、schoolBoard、cityWide、township、countyCouncil、cityCouncil、ward、special

可接受的值包括： <ph type="x-smartling-placeholder">
    </ph>
  • “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 这组公投的投票响应。选票回应表示选票上的一条线。常见示例可能包括“是”或“no”或评委的姓名只有“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 这些数据是否来自政府官方来源。

试试看！