このページは Cloud Translation API によって翻訳されました。

REST を使用して API を呼び出す

このドキュメントでは、Custom Search JSON API の使用方法について説明します。

リクエストの実行

Custom Search JSON API の REST（Representational State Transfer）は、従来の REST とは若干異なります。この API では、リソースへのアクセス権を付与する代わりに、サービスへのアクセスを提供します。その結果、API はサービスエンドポイントとして機能する単一の URI を提供します。

特定の検索の結果を取得するには、その URI に HTTP GET リクエストを送信します。検索リクエストの詳細をクエリパラメータとして渡します。Custom Search JSON API URI の形式は次のとおりです。

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

検索リクエストごとに 3 つのクエリ [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

クエリパラメータ

リクエストで渡すことができるパラメータには 2 つのタイプがあります。

API 固有のパラメータ - 検索式、結果の数、言語など、検索のプロパティを定義します。
標準のクエリパラメータ - API キーなど、リクエストの技術的な側面を定義します。

パラメータの値はすべて URL エンコードする必要があります。

API 固有のクエリパラメータ

Custom Search JSON API に特に適用され、検索リクエストを定義するリクエストパラメータについては、リファレンスをご覧ください。

標準のクエリパラメータ

すべての Custom Search JSON API オペレーションに適用されるクエリパラメータは、システムパラメータに記載されています。

Response data

リクエストが成功すると、サーバーは 200 OK HTTP ステータスコードと JSON 形式のレスポンスデータを返します。レスポンスのデータ構造については、リファレンスをご覧ください。

レスポンスデータは、次の 3 種類のプロパティを含む JSON オブジェクトです。

リクエストされた検索（および場合によっては関連する検索リクエスト）を記述するメタデータ
プログラム可能検索エンジンを記述するメタデータ
検索結果

各プロパティの詳細については、リファレンスをご覧ください。

検索リクエストのメタデータ

検索メタデータには次のものが含まれます。

url プロパティ。このリクエストで返された結果に使用される OpenSearch テンプレートに関する情報が含まれます。
queries プロパティ。これは、可能な検索の特性を記述するオブジェクトの配列です。配列内の各オブジェクトの名前は、OpenSearch クエリロールの名前か、この API で定義された 2 つのカスタムロール（previousPage と nextPage）のいずれかです。有効なクエリロールオブジェクトは次のとおりです。
- request: 現在の結果セットのクエリを記述するメタデータ。
  - このロールはレスポンスに常に存在します。
  - 常に 1 つの要素のみを含む配列です。
  - nextPage: 結果の次のページに使用するクエリを記述するメタデータ。
    - 現在の結果が最後のページである場合、このロールは存在しません。注: この API は、最初の 100 件の結果のみを返します。
    - 存在する場合、常に 1 つの要素のみを持つ配列になります。
- previousPage: 結果の前のページに使用するクエリを記述するメタデータ。
  - 現在の結果が最初のページである場合に存在しません。
  - 存在する場合、常に 1 つの要素のみを持つ配列になります。

検索エンジンのメタデータ

context プロパティには、検索クエリを実行した検索エンジンを記述するメタデータが含まれます。これには、検索エンジンの名前と、検索を絞り込むために指定するファセットオブジェクトが含まれます。

検索結果

items 配列には実際の検索結果が含まれます。検索結果には、URL、タイトル、結果を説明するテキストスニペットが含まれます。必要に応じて、リッチスニペット情報を含めることもできます。

検索結果に promotions プロパティが含まれている場合は、一連のプロモーションが含まれます。

JavaScript からの REST

JavaScript から REST で Custom Search JSON API を呼び出すには、callback クエリパラメータとコールバック関数を使用します。これにより、サーバーサイドのコードを記述することなく、プログラム可能検索エンジンのデータを表示するリッチアプリケーションを作成できます。

次の例では、この方法で「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>