このドキュメントは、Custom Search JSON API とその使用方法を理解するのに役立ちます。
始める前に
プログラム可能検索エンジンの作成
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 仕様に基づいています。標準の OpenSearch プロパティに加えて、Custom Search JSON API では 2 つのカスタム プロパティと 2 つのカスタムクエリ ロールが定義されています。
- カスタム プロパティ
cx: プログラム可能検索エンジンの識別子。safe: 返された結果のフィルタリングに使用するセーフサーチ レベルの説明。
- カスタムクエリのロール
nextPage: 結果の次の論理ページが存在する場合に、そのクエリを使用してアクセスできることを示すロール。previousPage: 結果の前の論理ページが存在する場合に、そのページへのアクセスにクエリを使用できることを示すロール。
試してみる
コードを記述せずに API を試してみるには、「Try this API」ツールにアクセスしてください。
パラメータの詳細については、cse.list のリファレンスをご覧ください。
HTTP リクエストで API を使用する方法については、REST の使用をご覧ください。