开发者数据指南

投票信息

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

数据可用性

开发者指南

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

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

  • 如果您需要更多配额才能实现自己的使用情形，可以在开发者控制台中申请增加每个项目的配额。额外配额的预配有限，且有最高限额。

    注意：审批流程需要 1-2 个月的时间。请相应地规划配额增加申请。如需为 2024 年总统大选做好准备，请在 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 Maps API 不了解此地址）。
noAddressParameter 未提供地址。
multipleStreetSegmentsFound 该 API 找不到指定地址的信息，但有附近地址的信息。用户应与选举官员联系，以了解更多信息。
electionOver 所请求的选举已结束。选举的 API 结果已不再提供。发出 electionQuery 以查找即将举行的选举的 ID。
electionUnknown 所请求的选举 ID 无效。发出 electionQuery 以查找有效 ID。
internalLookupFailure 处理请求时发生未指明的错误。