此页面由 Cloud Translation API 翻译。

开发者数据指南

政治地理和民选代表

Google Civic Information API 提供美国联邦政府和地方级别的政治地域划分和民选代表的相关信息。目前，我们在州、县和国会选区的覆盖率已接近 100%，并且力争让州立法选区的覆盖率超过 90%。下级组织（如市县委员会）将尽最大努力为其提供服务，并会随着时间的推移而不断完善。

我们预计拥有美国各州最大城市以及人口超过 250,000 人的任何城市的所有联邦、州和县级民选官员的最新信息，以及城市官员的信息。我们会汇总来自多个来源的这些数据，并提供最优质的可用信息。如果发现数据质量问题，我们可能会停止返回特定地域部门、民选公职或民选官员的数据。

对于由投票信息项目提供支持的选举，Google Civic Information API 会向用户返回投票地点、提前投票地点、当地选举官方联系信息以及选票信息等公民信息。

我们要求所有开发者都遵守以下准则：

遵守 API 服务条款。
使用该 API，开发者同意遵循任何 Cache-Control 标头（如果有）。如果没有缓存控制标头，开发者同意在投票地点和比赛信息中缓存的时间不超过 24 小时，对于公职人员和选区，则不超过 30 天。
使用该 API 的开发者应尽一切努力确保所有用户都能获得相同的体验。我们不允许使用对照组、A/B 测试或类似实验。
如果您需要额外的配额来启用您的用例，可以在 Play 管理中心申请增加每个项目。预配额外配额受到限制，并受最大限额限制。

注意：审批流程需要 1-2 个月的时间。请相应规划您的配额增加申请。为了针对 2024 年总统选举配额增加做好准备，请在 8 月之前提交配额申请。
Civic Info API 的额外配额仅用于支持面向用户的用例。对于其他用例，不会授予增加配额申请。

此类数据的使用特别难以处理。请注意以下几点。

选举官员在过去几周乃至选举前的最后几天经常会修订这些数据。最好在投票前提醒用户应回来查看。
大多数官方 Feed 都包含街道路段，这意味着选举官员会将一系列地址与选区和投票点联系起来。这些地址范围不一定有在此地址登记的选民。因此，对于通过投票信息项目提供官方 Feed 的州，没有登记选民的地址可能会返回成功。
对于未提供官方 Feed 的州，只有已登记选民的地址才会返回成功结果。
有时，我们会从多个信息来源获取相同的信息。我们针对当地选举官方联系信息和选票信息提供最优质的信息。除了通过 websiteSourcesOnly 参数删除非官方来源之外，没有其他方法可以替换此行为。对于投票点信息，我们始终会优先考虑官方数据源，而非其他来源。
如果发现数据质量问题，我们可能会不返回特定选区的数据，直到问题解决为止。
如果我们没有某个地址的相关数据，并不一定意味着该地方没有人登记投票。申请应将用户引导至当地选举官员，以便获取完整信息。
选举将在选举日之后自动过期。在此时间点之后，将不再为选举返回任何数据。

对 Civic Information API 的提供方说明并非强制性要求。如果开发者选择注明 Civic Information API 并链接用户提供有关 Civic Information API 的详细信息，我们要求开发者使用以下提供方说明语言选项及下方链接的网页之一：

对 voterInfoQuery 的调用包含一个 status 字段，在接受地址时，该字段会被设置为 success。在其他情况下，系统会返回错误代码。下面给出了错误代码的常见说明。请注意，即使出现错误代码，也可能会返回相关信息。

状态	说明
`success`	API 会将请求的地址识别为有效地址。
`noStreetSegmentFound`	该 API 目前没有任何关于此地址所属的选举选区和/或选区的信息。这可能是因为我们仍在收集/处理新数据，或者没有选民登记在此地址进行投票。
`addressUnparseable`	请求的地址格式不正确，或者无法进行地理编码（即 Google Maps API 对此地址一无所知）。
`noAddressParameter`	未提供地址。
`multipleStreetSegmentsFound`	API 找不到指定地址的信息，但包含附近地址的相关信息。用户应与选举官员联系以了解详情。
`electionOver`	要求的选举已结束。选举的 API 结果已无法使用。执行 electionQuery 以查找即将举行的选举的 ID。
`electionUnknown`	所请求的选举 ID 无效。执行 electionQuery 以查找有效 ID。
`internalLookupFailure`	处理请求时发生不明错误。