このドキュメントでは、Custom Search JSON API とその使用方法について説明します。
始める前に
プログラム可能検索エンジンを作成する
API を呼び出すことで、ユーザーはプログラマブル検索エンジンの既存のインスタンスに対してリクエストを発行します。そのため、API を使用する前に、コントロール パネルで作成する必要があります。さまざまな構成オプションの詳細については、チュートリアルをご覧ください。作成した検索エンジン ID は、[概要] ページの [基本] セクションで確認できます。これは、API で使用される cx パラメータです。
API キーを使用して Google にアプリケーションを識別する
Custom Search JSON API では、API キーを使用する必要があります。API キーは、クライアントを Google に識別するための方法です。
API キーを作成したら、アプリケーションですべてのリクエスト URL の末尾にクエリ パラメータ key=yourAPIKey を追加できます。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 の使用に進んでください。