Customsearch API - Billing：超过免费配额是否收费？

2026-10-24支付小周

结论

是否收费，取决于发送这些请求时，项目有没有为 JSON Custom Search API 启用结算账号。

未启用 Billing：通常每天只能使用 100 次免费查询。超过配额后，请求会返回配额错误，不会自动产生费用。
已启用 Billing：超出免费额度且成功处理的查询可能会计费。按照题述价格，额外 260 次查询的理论费用约为：

[ 260 \div 1000 \times $5 = $1.30 ]

$1.30 是按照每次查询 $0.005 得出的估算值。实际费用应以 Google Cloud Billing 导出的用量和请求发生时生效的官方计费规则为准。

Dashboard 暂时没有显示费用，不能证明这些请求是免费的。用量和费用数据可能尚未更新，也可能是超额请求没有成功。

如何确认是否产生费用

1. 检查是否启用了 Billing

进入 Google Cloud Console，查看调用 API 的项目是否关联了有效的结算账号：

选择实际发送请求的项目。
打开 Billing。
确认项目是否关联了结算账号，以及账号状态是否正常。

如果项目没有关联结算账号，超过免费配额的请求通常会被拒绝，不会在事后补收费用。

2. 查看 API 的请求结果

检查昨天请求的 HTTP 状态码和响应正文。超过配额时，常见结果是 HTTP 403，响应中会包含配额超限信息，例如：

{
  "error": {
    "code": 403,
    "message": "Daily Limit Exceeded",
    "errors": [
      {
        "reason": "dailyLimitExceeded"
      }
    ]
  }
}

具体的 message 和 reason 可能随项目配置和 Google API 返回格式而变化，因此不能只看错误文本。需要确认：

HTTP 状态码是否为 200
响应中是否有正常的搜索数据
是否出现 403、429 或配额相关错误
360 次请求中有多少次实际成功

请求成功发出，不等于查询已被成功处理。

3. 查看配额用量

在 Google Cloud Console 中进入：

APIs & Services → Enabled APIs & services → Custom Search API → Quotas

查看对应日期的查询量。如果图表只记录了约 100 次成功查询，其余请求均显示为错误，通常不会按照 360 次成功查询计费。

4. 查看 Billing 报表

在 Billing → Reports 或费用明细中：

选择正确的结算账号和项目
将日期范围设为请求发生当天至之后几天
按服务筛选 Custom Search API
检查现有过滤条件，避免费用数据被隐藏

账单数据可能不会实时更新。如果 Billing 已启用且请求已经成功，可以等结算数据汇总完成后再核对。

建议在代码中记录成功与失败请求

不要只统计发出了多少次请求，还要记录状态码和错误响应：

import requests

url = "https://www.googleapis.com/customsearch/v1"
params = {
    "key": "YOUR_API_KEY",
    "cx": "YOUR_SEARCH_ENGINE_ID",
    "q": "example query",
}

response = requests.get(url, params=params, timeout=30)

print("HTTP status:", response.status_code)

if response.ok:
    data = response.json()
    print("Request succeeded")
    print("Result count:", len(data.get("items", [])))
else:
    try:
        error = response.json()
    except ValueError:
        error = response.text

    print("Request failed:", error)

生产环境还应按日期分别统计成功和失败的请求：

if response.status_code == 200:
    successful_queries += 1
else:
    failed_queries += 1

不要在日志或错误报告中输出完整的 API Key。

注意事项

“每天 100 次免费查询”通常按照项目或 API 配额规则计算，不一定按单个用户或单个 API Key 分别计算。
同一项目下的多个 API Key 可能共享配额。创建新 Key 通常不会获得另一份免费额度。
搜索结果的分页请求也可能分别计为查询。例如，修改 start 获取下一页会发出新的 API 请求。
是否收费，要以请求发生时的 Billing 状态、成功查询数量以及当时生效的价格规则为准。
如果项目已启用 Billing，建议设置预算提醒和配额限制。预算提醒通常只会发送通知，不会自动阻止费用继续产生。
题述的 $5/1000 queries 和每天 10k 上限可能随官方政策调整。长期运行前，应重新核对当前的 Custom Search JSON API 定价与配额页面。