本文件說明如何使用 Custom Search JSON API。
提出請求
Custom Search JSON API 中的 REST (或稱 Representational State Transfer) 與傳統 REST 有些許不同，API 並未提供資源的存取權，而是提供服務的存取權。因此，這個 API 提供了單一 URI，用來當做服務端點。
您可以將 HTTP GET 要求傳送至其 URI，藉此擷取特定搜尋的結果。您傳入搜尋要求的詳細資料做為查詢參數。Custom Search JSON API URI 的格式如下：
https://www.googleapis.com/customsearch/v1?[parameters]
每個搜尋要求都必須提供三個查詢 [parameters]：
- API 金鑰 - 使用
key查詢參數來識別應用程式。 程式化搜尋引擎 ID：使用
cx指定要用來執行此搜尋的程式化搜尋引擎。 您必須使用控制台建立搜尋引擎。 注意：搜尋引擎 ID (cx) 可以是不同格式 (例如 8ac1ab64606d234f1)搜尋查詢：使用
q查詢參數指定搜尋運算式。
所有其他查詢參數均為選填。
以下是搜尋程式程式搜尋引擎中「演講」的測試要求範例：
GET https://www.googleapis.com/customsearch/v1?key=INSERT_YOUR_API_KEY&cx=017576662512468239146:omuauf_lfve&q=lectures
查詢參數
您可以在要求中傳遞兩種參數類型：
- API 專屬參數 - 定義搜尋的屬性，例如搜尋運算式、結果數量、語言等。
- 標準查詢參數：定義要求的技術層面，例如 API 金鑰。
所有參數值均須採用網址編碼。
API 專屬查詢參數
如要瞭解 Custom Search JSON API 專用的要求參數，並定義搜尋要求，請參閱參考資料。
標準查詢參數
如要瞭解所有 Custom Search JSON API 作業的查詢參數，請參閱系統參數。
回應資料
如果要求成功，伺服器會以 200 OK HTTP 狀態碼回應，以及 JSON 格式的回應資料。您可以在參考資料中查詢回應資料結構。
回應資料為 JSON 物件，其中包含三種屬性：
- 描述所要求搜尋的中繼資料 (可能包括相關搜尋要求)
- 說明程式化搜尋引擎的中繼資料
- 搜尋結果
如需每個屬性的詳細說明，請參閱參考資料。
搜尋要求中繼資料
搜尋中繼資料包括：
url屬性，其具有此要求所傳回結果所用 OpenSearch 範本的相關資訊。queries屬性，這是描述可能搜尋特性的物件陣列。陣列中每個物件的名稱可能是 OpenSearch 查詢角色名稱，或此 API 定義的兩種自訂角色名稱之一：previousPage和nextPage。可能的查詢角色物件包括：request：說明目前結果集查詢的中繼資料。- 回應中永遠會顯示這個角色。
- 一律是只包含一個元素的陣列。
nextPage：說明要在下一頁結果使用查詢的中繼資料。- 如果目前的結果為最後一頁，就不會顯示這個角色。 注意： 這個 API 最多只會傳回前 100 筆結果。
- 此標記時，一律為只包含一個元素的陣列。
previousPage：說明要在上一頁結果中使用查詢的中繼資料。- 如果目前的結果位於第一頁，則不會顯示。
- 此標記時，一律為只包含一個元素的陣列。
搜尋引擎中繼資料
context 屬性包含描述執行搜尋查詢的搜尋引擎的中繼資料。其中包含搜尋引擎名稱，以及其所提供用於縮小搜尋範圍的任何facet 物件。
搜尋結果
items 陣列包含實際搜尋結果。搜尋結果包括描述搜尋結果的網址、標題和文字片段。此外，也可能包含程式碼片段資訊 (如果有的話)。
如果搜尋結果包含 promotions 屬性，則表示該屬性包含一組促銷活動。
JavaScript 提供的 REST
您可以使用 callback 查詢參數和回呼函式，透過 JavaScript 的 REST 叫用 Custom Search JSON API。這可讓您編寫豐富的應用程式，顯示程式化搜尋引擎資料，而無須編寫任何伺服器端程式碼。
以下範例使用這個方法顯示查詢「cars」的第一頁搜尋結果：
<html>
<head>
<title>Custom Search JSON 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];
// Make sure HTML in item.htmlTitle is escaped.
document.getElementById("content").append(
document.createElement("br"),
document.createTextNode(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>