Google Custom Search API 每日100次查询限额如何计算？

2026-10-24数据小陈

结论

“每天 100 次免费查询”通常按启用了 Custom Search JSON API 的 Google Cloud 项目计算，而不是按应用程序的最终用户分别计算。

如果 50 位用户通过同一个 Google Cloud 项目调用 API，他们的查询会共同消耗该项目当天的免费配额。整个项目合计有 100 次，而不是每位用户各有 100 次。

普通 API 请求本身无法让 Google 自动识别应用中的具体用户。请求里的 key 用于关联 Google Cloud 项目及其配额，cx 用于指定 Programmable Search Engine，不会为不同用户分配独立的免费额度。

配额如何消耗

每次成功提交的搜索请求通常计为一次查询。例如：

GET https://www.googleapis.com/customsearch/v1
    ?key=YOUR_API_KEY
    &cx=YOUR_SEARCH_ENGINE_ID
    &q=example
    &searchType=image

只要使用的凭据属于同一个项目，不同用户发出的请求都会累计到同一份项目配额中：

用户 A：40 次
用户 B：35 次
用户 C：25 次
合计：100 次

到这里，该项目当天的 100 次免费查询已经用完。如果没有启用 billing，后续请求通常会因配额不足而失败。启用 billing 后，超出免费额度的查询会按适用价格计费，同时仍受项目每日总配额限制。

还需要注意以下几点：

分页也会消耗查询次数。例如修改 start 获取下一页，相当于发起一次新的 API 请求。
图片搜索虽然使用 searchType=image，但没有单独的免费配额。
在同一项目下创建多个 API key，通常不会按 key 的数量增加免费额度，因为这些 key 仍然属于同一个项目。
更换 cx 一般不会重置项目的 API 配额。
失败请求是否计入某项指标，应查看 Google Cloud Console 中实际显示的配额指标及官方定义，不宜只根据 HTTP 状态码判断。

如何查看实际用量

可以在 Google Cloud Console 中查看项目的配额和使用情况：

打开 Google Cloud Console。
选择调用 API 时使用的项目。
进入 APIs & Services。
打开 Enabled APIs & services。
选择 Custom Search API。
查看 Quotas 和 Metrics 页面。

这些页面显示的是项目侧的统计数据，可以用来判断应用中所有用户是否已经共同耗尽免费额度。控制台的指标名称和界面可能调整，请以当前页面为准。

应用应自行限制每位用户的调用量

如果要限制每位用户每天的搜索次数，需要在自己的服务器端实现计数和限流。Google 提供的项目配额控制的是项目总量，不能代替应用内部的用户级配额。

下面是一个简化的 Node.js 示例。生产环境中应把计数保存在 Redis、数据库等共享存储里：

const dailyUsage = new Map();

function getDateKey() {
  return new Date().toISOString().slice(0, 10);
}

function consumeUserQuota(userId, dailyLimit = 10) {
  const key = `${userId}:${getDateKey()}`;
  const used = dailyUsage.get(key) ?? 0;

  if (used >= dailyLimit) {
    throw new Error("User daily search quota exceeded");
  }

  dailyUsage.set(key, used + 1);
}

async function searchImages(userId, keyword) {
  consumeUserQuota(userId, 10);

  const params = new URLSearchParams({
    key: process.env.GOOGLE_API_KEY,
    cx: process.env.GOOGLE_SEARCH_ENGINE_ID,
    q: keyword,
    searchType: "image"
  });

  const response = await fetch(
    `https://www.googleapis.com/customsearch/v1?${params}`
  );

  if (!response.ok) {
    throw new Error(`Google API request failed: ${response.status}`);
  }

  return response.json();
}

用于生产环境时，还要处理并发安全、计数周期采用的时区、失败请求是否退还内部额度，以及项目总配额接近上限时的熔断策略。

是否能让每位用户分别获得 100 次免费额度

仅传入不同的应用用户 ID，一般不能让每位用户分别获得 100 次免费额度。即使部分 Google API 支持 quotaUser 等参数，这类参数通常用于区分调用者和实施更细粒度的配额管理，并不表示每个参数值都会自动得到一套免费配额。

不同的 Google Cloud 项目理论上可能各自拥有项目配额，但不应通过批量创建项目或 API key 来绕过限制。具体是否允许以及如何计费，应遵守 Google Cloud 服务条款和当前的配额政策。

官方参考入口

可优先查阅以下官方页面：

配额、价格和产品可用性可能变化。对于“100 次”“$5/1000 次”和“每天最多 10,000 次”等具体数字，请以调用项目的 Google Cloud Console及官方 Custom Search 文档当前显示的内容为准。