根据选民的注册地址查询与选民相关的信息。 立即尝试。
返回的信息可能包括
- 指定住宅街道地址的投票点(包括早期投票点)
- 比赛和候选人信息
- 选举官方信息
请求
HTTP 请求
GET https://www.googleapis.com/civicinfo/v2/voterinfo
参数
参数名称 | 值 | 说明 |
---|---|---|
必需的查询参数 | ||
address |
string |
要查询的选民的注册地址。 |
可选的查询参数 | ||
electionId |
long |
要查找的选举的唯一 ID。您可以访问 https://www.googleapis.com/civicinfo/{version}/elections 来获取选举 ID 列表。 如果查询中未指定选举 ID,并且有多个选举包含指定选民的数据,则 如果指定的选民地址没有实时选举结果,则只有在指定了选举 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 一级执行,但实际上同时在 administrativeArea2 和administrativeArea1 都执行。有效值包括:
|
|
contests[].roles[] |
list |
本次竞赛中担任的办公室所担任的职位。职务并不是详尽无遗的,也不是详尽说明指定办事处的全部职责,但只是粗略的类别,有助于对办事处进行一般选择或排序。 有效值包括:
|
|
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
可接受的值包括:
|
|
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 |
渠道的类型。下面列出了渠道类型,但并非详尽无遗。日后可能会添加更多频道类型。以下各项中的一项:
|
|
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 |
这些数据是否来自政府官方来源。 |