Custom Search JSON API: 概要
コレクションでコンテンツを整理
必要に応じて、コンテンツの保存と分類を行います。
このドキュメントは、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 の使用をご覧ください。
特に記載のない限り、このページのコンテンツはクリエイティブ・コモンズの表示 4.0 ライセンスにより使用許諾されます。コードサンプルは Apache 2.0 ライセンスにより使用許諾されます。詳しくは、Google Developers サイトのポリシーをご覧ください。Java は Oracle および関連会社の登録商標です。
最終更新日 2025-08-31 UTC。
[null,null,["最終更新日 2025-08-31 UTC。"],[[["\u003cp\u003eThis guide introduces the Custom Search JSON API and provides instructions for its use.\u003c/p\u003e\n"],["\u003cp\u003eBefore using the API, you need to create a Programmable Search Engine and obtain an API key.\u003c/p\u003e\n"],["\u003cp\u003eThe API allows you to retrieve search results from your Programmable Search Engine using a single \u003ccode\u003elist\u003c/code\u003e operation.\u003c/p\u003e\n"],["\u003cp\u003eThe API returns results in JSON format containing search metadata, engine details, and the search results themselves.\u003c/p\u003e\n"],["\u003cp\u003eYou can experiment with the API using the provided "Try this API" tool or learn more through detailed documentation and examples.\u003c/p\u003e\n"]]],[],null,["# Custom Search JSON API: Introduction\n\nThis document will help you to get familiar with Custom Search JSON API and its usage.\n\nBefore you start\n----------------\n\n### Create Programmable Search Engine\n\nBy calling the API user issues requests against an existing instance of\nProgrammable Search Engine.\nTherefore, before using the API, you need to create one in the\n[Control Panel](https://programmablesearchengine.google.com/controlpanel/create)\n. Follow the [tutorial](/custom-search/docs/tutorial/creatingcse)\nto learn more about different configuration options.\nOnce it is created, you can find the **Search Engine ID** in the **Overview**\npage's **Basic** section. This is the `cx` parameter used by the API.\n\n### Identify your application to Google with API key\n\nCustom Search JSON API requires the use of an API key. An API key is a way to identify your client to Google.\n\n- [Programmable Search Engine](https://cse.google.com/) (free edition) users: Get a Key\n\nAfter you have an API key, your application can append the query parameter\n`key=yourAPIKey` to all request URLs. The API key is safe for embedding in URLs,\nit doesn't need any encoding.\n\nAPI overview\n------------\n\n### API operations\n\nThere is only one method to invoke in the Custom Search JSON API:\n\n| Operation | Description | REST HTTP mapping |\n|------------------------------------------------------|-------------------------------------------------------------------------|-------------------|\n| [list](/custom-search/v1/reference/rest/v1/cse/list) | Returns the requested search results from a Programmable Search Engine. | `GET` |\n\n### API data model\n\nThe result of a search query to the Custom Search JSON API is a JSON object that includes three types of data:\n\n- Metadata describing the requested search (and, possibly, related search requests)\n- Metadata describing the Programmable Search Engine\n- Search results\n\nSee the Response data section of [Using REST](/custom-search/v1/using_rest#response_data) for more details.\n\nThe data model is based on the OpenSearch 1.1 Specification. In addition to the standard OpenSearch properties, the Custom Search JSON API defines two custom properties and two custom query roles:\n\n- Custom properties\n - `cx`: The identifier of the Programmable Search Engine.\n - `safe`: A description of the safe search level for filtering the returned results.\n- Custom query roles\n - `nextPage`: A role that indicates the query can be used to access the next logical page of results, if any.\n - `previousPage`: A role that indicates the query can be used to access the previous logical page of results, if any.\n\nTry it\n------\n\nTo play around and see what the API can do, without writing any code, visit the\n[\"Try this API\" tool](/custom-search/v1/reference/rest/v1/cse/list?apix=true).\n\nFor a full description of parameters visit the\n[cse.list reference](/custom-search/v1/reference/rest/v1/cse/list).\n\nTo learn how to use the API via HTTP requests, continue to\n[Using REST](/custom-search/v1/using_rest)."]]
