本文件說明如何使用 Custom Search JSON API。
提出請求
REST 或表徵狀態移轉 (Custom Search JSON API 中的說明與傳統 REST 稍有不同)。API 可讓您存取服務，而非提供資源的存取權。因此，該 API 提供了單一的 URI，用來當做服務端點。
您可以將 HTTP GET 要求傳送至其 URI，以便擷取特定搜尋的結果。您需將搜尋要求的詳細資料做為查詢參數傳入。Custom Search JSON API URI 的格式如下：
https://www.googleapis.com/customsearch/v1?[parameters]
每個搜尋要求都包含三個查詢 [parameters]：
- 「API key」：使用
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
您可以透過 JavaScript 中的 REST，使用 callback 查詢參數和回呼函式叫用 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>