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

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

リクエストを作成する

Custom Search JSON API の REST(Representational State Transfer)は、通常の RESTful API とは多少異なります。この 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 クエリ パラメータを使用して検索式を指定します。

他のすべてのクエリ パラメータは省略可能です。

以下は、テスト用のプログラム可能検索エンジンで「lectures」を検索するリクエストの例です。

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 オペレーションに適用されるクエリ パラメータについては、システム パラメータをご覧ください。

レスポンス データ

リクエストが成功すると、サーバーは 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

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

次の例では、このアプローチを使用して、クエリ lecture の検索結果の最初のページを表示します。

<html>
<head>
<title>Custom Search JSON API Example</title>
</head>
<body>
    <div id="content"></div>
    <p id="demo"></p>
    <script>
    function hndlr(response) {
      if (response.items == null) {
        document.getElementById("demo").innerHTML +=`<h3> No Results Found </h3>`;
      } else {
        for (var i = 1; 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=lecture&callback=hndlr">
    </script>
  </body>
</html>