开发者数据指南

投票信息

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

数据可用性

开发者指南

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

  • 遵守 API 服务条款。
  • 使用此 API 即表示开发者同意遵循所有缓存控制标头（如果有）。如果没有缓存控制标头，开发者同意不会将投票地点和竞选信息缓存超过 24 小时，也不会将现任职位和选区缓存超过 30 天。
  • 使用该 API 的开发者应尽最大努力确保所有用户都能获得相同的体验。我们不允许进行预留、A/B 测试或类似实验。

  • 如果您需要额外的配额来实现您的用例，可以在 Developer Console 中申请增加每个项目的配额。我们会限制额外配额的预配，并设有配额上限。

    注意：审批流程需要 1-2 个月的时间。请据此规划配额增加请求。为准备 2024 年总统大选配额增加，请在 8 月之前提交配额申请。

  • Civic Info API 的额外配额仅用于支持面向用户的用例。我们不会为其他用例批准配额增加请求。

其他数据指南

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

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

归因

是否提供对 Civic Information API 的归因信息取决于您。如果开发者选择归因于 Civic Information API 并将用户链接到 Civic Information API 的更多信息，则必须使用以下某种归因语言选项和下方链接的网页：

  • “Powered by the Civic Information API”（由 Civic Information API 提供支持）
  • “Voting information powered by the Civic Information API”（由 Civic Information API 提供支持的投票信息）
  • “Ballot information powered by the 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 处理请求时发生未指明的错误。