Custom Search JSON API: 概要

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

始める前に

プログラム可能検索エンジンを作成する

API を呼び出すことで、ユーザーはプログラム可能検索エンジンの既存のインスタンスに対してリクエストを発行します。そのため、API を使用する前に、コントロール パネルで作成する必要があります。さまざまな構成オプションの詳細については、チュートリアルをご覧ください。作成すると、[概要] ページの [基本] セクションに検索エンジン ID が表示されます。これは、API で使用される cx パラメータです。

API キーを使用して Google にアプリケーションを識別する

Custom Search JSON API を使用するには、API キーが必要です。API キーは、Google に対してクライアントを識別する方法です。

API キーを取得したら、アプリケーションはクエリ パラメータ key=yourAPIKey をすべてのリクエスト URL に追加できます。API キーは URL に埋め込んでも安全であり、エンコードは必要ありません。

API の概要

API オペレーション

Custom Search JSON API で呼び出すメソッドは 1 つだけです。

オペレーション 説明 REST HTTP マッピング
list プログラム可能検索エンジンからリクエストされた検索結果を返します。 GET

API データモデル

Custom Search JSON API への検索クエリの結果は、次の 3 種類のデータを含む JSON オブジェクトです。

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

詳細については、REST の使用の「レスポンス データ」セクションをご覧ください。

データモデルは OpenSearch 1.1 仕様に基づいています。Custom Search JSON API では、標準の OpenSearch プロパティに加えて、2 つのカスタム プロパティと 2 つのカスタム クエリロールが定義されています。

  • カスタム プロパティ
    • cx: プログラム可能検索エンジンの ID。
    • safe: 返された結果をフィルタリングするためのセーフサーチ レベルの説明。
  • カスタムクエリのロール
    • nextPage: クエリを使用して、結果の次の論理ページ(存在する場合)にアクセスできることを示すロール。
    • previousPage: クエリを使用して、結果の前の論理ページ(存在する場合)にアクセスできることを示すロール。

試してみる

コードを記述せずに API の機能を試すには、「この API を試す」ツールにアクセスしてください。

パラメータの詳細については、cse.list リファレンスをご覧ください。

HTTP リクエストを介して API を使用する方法については、REST の使用をご覧ください。