google custom search使用（一）

关注

原创最新推荐文章于 2026-09-03 09:21:23 发布 1.5w 阅读 AI 写同款· GEO 优化 ›

Google Custom Search API 实战指南：从申请CX Key到高级搜索参数解析本文提供了一份详尽的Google Custom Search API实战指南，从申请CX Key和API Key开始，逐步讲解基础调用与高级参数配置。文章深入解析了如何利用参数实现结果过滤、分页、时间限定、文件类型搜索及图像搜索等高级功能，并分享了配额管理、性能优化与密钥安全等实战经验，帮助开发者快速构建精准、高效的定制搜索引擎。阅读详情

本系列主要讲述Google Custom Search API，主要内容来自于google官方文档。

功能介绍

google提供了一个非常cool的功能，允许你添加自定义的google搜索功能到你的网站中，这样网站的访问者就可以很方便的获得他们期望搜索的结果。

准备工作

得到一个google账号

首先，你要有一个google账号，如果没有，需要去https://accounts.google.com/NewAccount创建一个；

创建一个自定义的搜索引擎

其次，你需要创建一个google custom search，可以去http://www.google.com/cse/manage/create这里创建，创建时需要提供包含在搜索引擎中的站点等信息；

创建完毕你可以去Control Panel，其中的搜索引擎唯一标示符之后将用来做你的cx参数；

或者，你也可以创建一个链接的搜索引擎，这种搜索引擎指定类型的URL可以作为API中的cref参数使用；

得到应用的ID

最后，我们为了对google标识你的app，我们需要访问https://code.google.com/apis/console，并在Services面板中打开JSON/Atom Custom Search API选项；接着我们去API Access面板，得到我们的API key，之后我们可以在请求参数中使用key=yourAPIKey，这个key对于嵌入的URL是安全的，不需要重新编码；

开始之前

如果你对于自定义搜索引擎并不熟悉，建议您阅读前导章节，这两篇文章描述了你可以使用不同的方法，通过XML来配置来和自定义的搜索引擎互动：

Developer Guide

Programmers Guide

还有两个外部的文档资源对于使用这个API有帮助：

Google WebSearch Protocal(XML)：google custom search API提供了一个可编程的XML API子集，但是返回值为JSON或Atom格式；

OpenSearch 1.1 Specification：该API使用了OpenSearch标准来描述搜索引擎和返回值。因为这个你可以编写支持OpenSearch引擎的代码，而不仅仅是google提供的自定义搜索引擎。由于目前OpenSearch没有JSON实现，所以所有的例子都是使用XML描述。

API操作

API仅支持HTTP的GET方法。

API数据模型

搜索返回的内容是JSON或者Atom对象并且包含三种类型的数据：

描述请求及请求相关的元数据；
描述自定义搜索的元数据；
返回值；

数据模型基于OpenSearch 1.1标准，并且添加了一些标准的OpenSearch属性。Google Custom Search API定义了3个自定义属性和2个自定义查询角色：

自定义属性

cx：自定义引擎的id；

cref：自定义引擎的url；

safe：返回结果安全搜索级别的过滤描述；

自定义查询角色

nextPage：定义查询结果下一逻辑页面；

previousPage：定义查询结果上一逻辑页面；

调用形式

有两种方式可以调用API：

REST方式

REST，全称是Representation State Transfer，Google Custom Search API和传统的REST有些不太一样。区别于传统方式提供的是资源的调用，GCS API提供的是对于服务的调用。API提供了一个URI作为服务节点调用来获取结果。

你可以使用标准的GET REST HTTP动作来获取Google Custom Search API服务节点，并且将你需要搜索的内容作为参数传入：

标准的搜索形式如下：

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

其中{parameters}参数可以接收任何参数，以下是一个典型的例子：

GET https://www.googleapis.com/customsearch/v1?key=INSERT-YOUR-KEY&cx=017576662512468239146:omuauf_lfve&q=lectures

JavaScript下的REST

你可以在JavaScript中使用REST方式调用GCS API，使用callback查询参数指定一个回调函数，这样可以避免你编写server端代码，而且仍然可以得到你想要的结果。

典型的例子如下：

<html>
  <head>
    <title>JSON/Atom Custom Search API Example</title>
  </head>
  <body>
    <div id="content"></div>
    <script>
      function hndlr(response) {
      for (var i = 0; i < response.items.length; i++) {
        var item = response.items[i];
        // in production code, item.htmlTitle should have the HTML entities escaped.
        document.getElementById("content").innerHTML += "<br>" + item.htmlTitle;
      }
    }
    </script>
    <script src="https://www.googleapis.com/customsearch/v1?key=YOUR-KEY&cx=017576662512468239146:omuauf_lfve&q=cars&callback=hndlr">
    </script>
  </body>
</html>

数据格式

GCS API可以返回两种数据格式的结果：JSON格式是默认数据格式，同样你也可以在请求参数中指定alt=atom返回Atom格式结果。

其他

目前google提供的custom search API版本为1的最新版，使用GCS API，你需要做的仅仅是发出一个请求，之后等着处理google返回的搜索结果吧。

google给免费用户提供了每天100次的搜索请求，如果你的应用程序需要更大的请求访问量，需要您付费。

google提供了几份文档：起步教程、使用REST、参考手册。