Custom Search JSON API：简介
使用集合让一切井井有条
根据您的偏好保存内容并对其进行分类。
本文档可帮助您熟悉 Custom Search JSON API 及其用法。
前期准备
创建可编程搜索引擎
通过调用 API，用户可针对可编程搜索引擎的现有实例发出请求。因此，在使用 API 之前，您需要在控制台中创建一个。按照教程中的说明详细了解不同的配置选项。创建之后，您可以在概览页的基本部分找到搜索引擎 ID。这是 API 使用的 cx 参数。
使用 API 密钥向 Google 标识您的应用
Custom Search JSON API 需要使用 API 密钥。API 密钥是向 Google 标识客户端的一种方式。
在您获得 API 密钥后，您的应用便可将查询参数 key=yourAPIKey 附加到所有请求网址中。API 密钥可以安全地嵌入到网址中，无需任何编码。
API 概览
API 操作
在 Custom Search JSON API 中，只有一种可以调用的方法：
| 操作 |
说明 |
REST HTTP 映射 |
| list |
返回从可编程搜索引擎请求的搜索结果。 |
GET |
API 数据模型
Custom Search JSON API 的搜索查询结果是一个 JSON 对象，其中包含以下三种类型的数据：
- 描述请求的搜索（也可能是相关的搜索请求）的元数据
- 描述可编程搜索引擎的元数据
- 搜索结果
如需了解详情，请参阅使用 REST 的“响应数据”部分。
该数据模型以 OpenSearch 1.1 规范为基础。除了标准的 OpenSearch 属性之外，Custom Search JSON API 还定义了两个自定义属性和两个自定义查询角色：
- 自定义属性
cx：可编程搜索引擎的标识符。safe：过滤返回结果的安全搜索级别的说明。
- 自定义查询角色
nextPage：一个角色，指示查询可用于访问结果的下一个逻辑页面（如果有）。previousPage：该角色表示可以使用查询来访问结果的上一个逻辑页面（如果有）。
试试看
如需在不编写任何代码的情况下尝试使用此 API 并了解其功能，请访问“试用此 API”工具。
如需查看参数的完整说明，请访问 cse.list 参考文档。
如需了解如何通过 HTTP 请求使用 API，请继续学习使用 REST。
如未另行说明，那么本页面中的内容已根据知识共享署名 4.0 许可获得了许可，并且代码示例已根据 Apache 2.0 许可获得了许可。有关详情，请参阅 Google 开发者网站政策。Java 是 Oracle 和/或其关联公司的注册商标。
最后更新时间 (UTC)：2025-08-31。
[null,null,["最后更新时间 (UTC)：2025-08-31。"],[[["\u003cp\u003eThis guide introduces the Custom Search JSON API and provides instructions for its use.\u003c/p\u003e\n"],["\u003cp\u003eBefore using the API, you need to create a Programmable Search Engine and obtain an API key.\u003c/p\u003e\n"],["\u003cp\u003eThe API allows you to retrieve search results from your Programmable Search Engine using a single \u003ccode\u003elist\u003c/code\u003e operation.\u003c/p\u003e\n"],["\u003cp\u003eThe API returns results in JSON format containing search metadata, engine details, and the search results themselves.\u003c/p\u003e\n"],["\u003cp\u003eYou can experiment with the API using the provided "Try this API" tool or learn more through detailed documentation and examples.\u003c/p\u003e\n"]]],[],null,["# Custom Search JSON API: Introduction\n\nThis document will help you to get familiar with Custom Search JSON API and its usage.\n\nBefore you start\n----------------\n\n### Create Programmable Search Engine\n\nBy calling the API user issues requests against an existing instance of\nProgrammable Search Engine.\nTherefore, before using the API, you need to create one in the\n[Control Panel](https://programmablesearchengine.google.com/controlpanel/create)\n. Follow the [tutorial](/custom-search/docs/tutorial/creatingcse)\nto learn more about different configuration options.\nOnce it is created, you can find the **Search Engine ID** in the **Overview**\npage's **Basic** section. This is the `cx` parameter used by the API.\n\n### Identify your application to Google with API key\n\nCustom Search JSON API requires the use of an API key. An API key is a way to identify your client to Google.\n\n- [Programmable Search Engine](https://cse.google.com/) (free edition) users: Get a Key\n\nAfter you have an API key, your application can append the query parameter\n`key=yourAPIKey` to all request URLs. The API key is safe for embedding in URLs,\nit doesn't need any encoding.\n\nAPI overview\n------------\n\n### API operations\n\nThere is only one method to invoke in the Custom Search JSON API:\n\n| Operation | Description | REST HTTP mapping |\n|------------------------------------------------------|-------------------------------------------------------------------------|-------------------|\n| [list](/custom-search/v1/reference/rest/v1/cse/list) | Returns the requested search results from a Programmable Search Engine. | `GET` |\n\n### API data model\n\nThe result of a search query to the Custom Search JSON API is a JSON object that includes three types of data:\n\n- Metadata describing the requested search (and, possibly, related search requests)\n- Metadata describing the Programmable Search Engine\n- Search results\n\nSee the Response data section of [Using REST](/custom-search/v1/using_rest#response_data) for more details.\n\nThe data model is based on the OpenSearch 1.1 Specification. In addition to the standard OpenSearch properties, the Custom Search JSON API defines two custom properties and two custom query roles:\n\n- Custom properties\n - `cx`: The identifier of the Programmable Search Engine.\n - `safe`: A description of the safe search level for filtering the returned results.\n- Custom query roles\n - `nextPage`: A role that indicates the query can be used to access the next logical page of results, if any.\n - `previousPage`: A role that indicates the query can be used to access the previous logical page of results, if any.\n\nTry it\n------\n\nTo play around and see what the API can do, without writing any code, visit the\n[\"Try this API\" tool](/custom-search/v1/reference/rest/v1/cse/list?apix=true).\n\nFor a full description of parameters visit the\n[cse.list reference](/custom-search/v1/reference/rest/v1/cse/list).\n\nTo learn how to use the API via HTTP requests, continue to\n[Using REST](/custom-search/v1/using_rest)."]]
