开发者数据指南

投票信息

Google Civic Information API 会向用户返回投票信息项目支持的选举的公民信息，例如投票地点、提前投票地点、 当地选举官员联系信息和选票信息。

数据可用性

开发者指南

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

  • 遵守 API 服务条款。
  • 使用该 API 即表示开发者同意遵守任何缓存控制标头（如果有）。如果没有缓存控制标头，开发者同意不缓存投票地点和选举信息超过 24 小时，不缓存官员和选区信息超过 30 天。
  • 使用该 API 的开发者应尽一切努力确保所有用户获得相同的体验。我们不允许保留、A/B 测试或类似实验。

  • 如果您需要额外的配额来启用您的用例，可以在您的 开发者控制台 中为每个项目申请增加配额。额外配额的预配有限，且有最大配额限制。

    注意 ：审批流程需要 1-2 个月，因此我们建议开发者相应地规划配额增加申请。对于 11 月的选举配额增加，我们强烈建议您在 8 月底之前提交配额申请。

  • Civic Info API 的额外配额仅用于支持面向用户 的用例。对于其他用例，系统不会批准配额增加申请。

其他数据准则

处理此类数据尤其棘手。 请注意以下几点。

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

归因

您可以选择是否归因于 Civic Information API。 如果开发者选择归因于 Civic Information API 并向用户提供指向 Civic Information API 更多信息的链接，我们要求开发者使用以下归因语言选项之一以及下方链接的网页：

  • “由 Civic Information API 提供支持”
  • “投票信息由 Civic Information API 提供支持”
  • “选票信息由 Civic Information API 提供支持”
  • “了解详情”

状态代码

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

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