Google Custom Search JSON API 调用文档

概述

Google Custom Search JSON API 是一个 RESTful API，用于通过发送 HTTP GET 请求从指定的可编程搜索引擎中检索搜索结果。请求的 URI 结构为：

https://www.googleapis.com/customsearch/v1?[parameters]

每个搜索请求都需要以下三个必需参数：

API Key (key): 标识您的应用。
可编程搜索引擎 ID (cx): 标识特定的搜索引擎。此 ID 需要从 Google Programmable Search Engine 控制台中获取。
搜索查询 (q): 指定您要搜索的表达式。

其他查询参数是可选的，并可用于自定义搜索结果。

API 请求

基本请求格式

GET https://www.googleapis.com/customsearch/v1?key=YOUR_API_KEY&cx=SEARCH_ENGINE_ID&q=SEARCH_QUERY

key: 您的 API 密钥。
cx: 搜索引擎 ID。
q: 搜索查询关键词。

可选查询参数

c2coff: 启用或停用简体中文和繁体中文搜索。
支持的值：1（停用）或 0（启用，默认）。
cr: 限制搜索结果来自指定国家/地区。
使用国家/地区代码，例如 cr=countryDE。
dateRestrict: 根据日期范围限制搜索结果。
格式示例：d[number]（指定天数），w[number]（指定周数），m[number]（指定月数），y[number]（指定年数）。
exactTerms: 强制搜索结果包含的词组。
excludeTerms: 排除搜索结果中不应包含的词组。
fileType: 将搜索结果限制为特定类型的文件（例如 pdf, doc）。
filter: 启用或停用重复内容过滤器。
支持的值：0（关闭），1（开启，默认）。
gl: 设置用户的地理位置，使用两字母国家代码。
imgSize: 图片搜索时限制图片大小。
支持的值：icon, small, medium, large, xlarge, xxlarge, huge。
imgColorType: 限制图片颜色类型。
支持的值：color, gray, mono, trans（透明背景）。
rights: 根据许可类型过滤搜索结果，支持如 cc_publicdomain, cc_attribute, cc_noncommercial 等值。
safe: 启用或禁用安全搜索。
支持的值：off（禁用），active（启用）。
searchType: 设置搜索类型，支持 image（图片搜索）或默认的网页搜索。
start: 设置返回结果的起始位置，默认是从第一个结果开始。

API 响应

成功的响应为 JSON 格式，包含以下主要字段：

kind: 结果类型（固定为 customsearch#search）。
queries: 包含当前请求和可能的下一页、上一页的元数据。
items: 实际的搜索结果，包括 title、link、snippet 等。

示例响应：

{
  "kind": "customsearch#search",
  "items": [
    {
      "title": "Example Title",
      "link": "https://www.example.com",
      "snippet": "This is a sample description for a search result."
    }
  ],
  "queries": {
    "nextPage": [
      {
        "startIndex": 11
      }
    ]
  }
}

搜索结果字段

title: 搜索结果的标题。
link: 结果指向的 URL。
snippet: 结果的文本摘要。
formattedUrl: 格式化显示的 URL。

在使用 Google Custom Search JSON API 进行分页查询时，您需要通过 start 参数来控制结果的分页。每次请求默认返回 10 条结果，您可以使用 start 参数指定从第几条记录开始返回结果，从而实现分页。

分页查询步骤

首次请求：发送请求时，不指定 start 参数，API 将返回第一页结果（即从第1条记录开始的前10条结果）。
获取下一页结果：通过解析 API 的响应数据中的 queries.nextPage.startIndex 来获取下一页的起始索引，将这个索引作为下一次请求的 start 参数。

示例

1. 第一次请求（获取第一页结果）

GET https://www.googleapis.com/customsearch/v1?key=YOUR_API_KEY&cx=YOUR_CX&q=YOUR_QUERY&num=10

这将返回第一页的搜索结果，默认返回前10个结果。

2. 下一页请求（获取第二页结果）

在第一次请求返回的响应中，您会找到类似这样的内容：

"queries": {
    "nextPage": [
        {
            "startIndex": 11
        }
    ]
}

这表示下一页的搜索结果从第11条开始。

因此，获取下一页结果时，您可以将 start 参数设置为 11，例如：

GET https://www.googleapis.com/customsearch/v1?key=YOUR_API_KEY&cx=YOUR_CX&q=YOUR_QUERY&start=11&num=10

这将返回第11到第20条搜索结果。

3. 处理分页的逻辑

重复步骤2，通过 queries.nextPage.startIndex 获取每次的下一页起始索引，直到没有 nextPage 为止。

示例代码（使用 JavaScript）

<html>
  <head>
    <title>Search Example with Pagination</title>
  </head>
  <body>
    <div id="content"></div>
    <button onclick="getNextPage()">Next Page</button>
    <script>
      var nextPageIndex = 1;

      function getResults(startIndex) {
        var apiKey = 'YOUR_API_KEY';
        var cx = 'YOUR_CX';
        var query = 'YOUR_QUERY';

        var url = `https://www.googleapis.com/customsearch/v1?key=${apiKey}&cx=${cx}&q=${query}&start=${startIndex}&num=10`;
        
        fetch(url)
          .then(response => response.json())
          .then(data => {
            displayResults(data.items);
            if (data.queries.nextPage) {
              nextPageIndex = data.queries.nextPage[0].startIndex;
            } else {
              document.getElementById("nextPageButton").disabled = true;
            }
          });
      }

      function displayResults(items) {
        var content = document.getElementById('content');
        content.innerHTML = '';
        items.forEach(item => {
          content.innerHTML += `<p>${item.title} - <a href="${item.link}">${item.link}</a></p>`;
        });
      }

      function getNextPage() {
        getResults(nextPageIndex);
      }

      // Initial load
      getResults(nextPageIndex);
    </script>
  </body>
</html>

这个示例展示了如何通过点击按钮获取下一页的搜索结果。

重要注意事项

start 参数的限制：最多只能获取前100条结果，因此 start 的值加上 num 的值不能超过100。
结果集大小：可以通过 num 参数指定每页返回结果的数量，范围是1到10。例如 num=10 表示每页返回10条记录。

授权

API 需要使用 Google API 密钥，密钥可通过 Google Cloud Console 获取。

注意事项

搜索结果长度限制为最多 100 个结果。
每个查询的 URI 长度不能超过 2048 个字符。

参考链接

Custom Search JSON API 官方文档