Custom Search JSON API：簡介
透過集合功能整理內容
你可以依據偏好儲存及分類內容。
本文件可協助您熟悉 Custom Search JSON API 及其用途。
事前準備
建立程式化搜尋引擎
透過呼叫 API 使用者，針對程式化搜尋引擎的現有執行個體發出要求。因此，您必須先在控制台中建立 API，才能使用這個 API。請參閱教學課程，進一步瞭解不同的設定選項。建立完畢後，您可以在「Overview」(總覽) 頁面的「Basic」(基本) 區段中找到搜尋引擎 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：程式化搜尋引擎的 ID。safe：安全搜尋篩選傳回結果的安全搜尋層級說明。
- 自訂查詢角色
nextPage：這個角色表示查詢可用於存取下一個結果邏輯頁面 (如有)。previousPage：這個角色表示查詢可用於存取上一個結果邏輯頁面 (如有)。
立即體驗
如想試試看 API 可發揮哪些實用功能，但不想編寫任何程式碼，請造訪「Try this API」(試用這個 API) 工具。
如需參數的完整說明，請參閱 cse.list 參考資料。
如要瞭解如何透過 HTTP 要求使用 API，請繼續參閱使用 REST。
除非另有註明，否則本頁面中的內容是採用創用 CC 姓名標示 4.0 授權，程式碼範例則為阿帕契 2.0 授權。詳情請參閱《Google Developers 網站政策》。Java 是 Oracle 和/或其關聯企業的註冊商標。
上次更新時間：2025-08-31 (世界標準時間)。
[null,null,["上次更新時間：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)."]]
