このページは Cloud Translation API によって翻訳されました。

API の使用

はじめに

このドキュメントは、Books API とやり取りできるアプリケーションを作成するデベロッパーを対象としています。Google ブックスは、世界中の書籍のコンテンツをデジタル化してウェブで見つけやすくするという使命を掲げています。Books API は、コンテンツを検索してアクセスし、コンテンツのパーソナライズを作成して表示するための手段です。

Google ブックスのコンセプトになじみがない場合は、コーディングを開始する前にスタートガイドをお読みください。

リクエストの承認とアプリケーションの識別

アプリケーションが Books API に送信するリクエストごとに、Google に対してアプリケーションを識別する必要があります。アプリケーションを識別する方法には、OAuth 2.0 トークンを使用する（リクエストの承認も行う）方法と、アプリケーションの API キーを使用する方法があります（この 2 つは併用できます）。これらのオプションのどちらを使用するかを決定する方法は次のとおりです。

リクエストを承認（個人のプライベートデータのリクエストなど）する場合、アプリケーションはリクエストとともに OAuth 2.0 トークンを提供する必要があります。API キーを提供することもできますが、その場合は不要です。
リクエストに承認が必要でない場合（一般公開データについてのリクエストなど）、アプリケーションは API キーまたは OAuth 2.0 トークンのいずれか、または両方を提供する必要があります。

認証プロトコルについて

アプリケーションは OAuth 2.0 を使用してリクエストを承認する必要があります。これ以外の承認プロトコルはサポートされていません。アプリケーションで「Google でログイン」を使用している場合、承認手続きの一部が自動化されます。

OAuth 2.0 によるリクエストの承認

非公開ユーザーデータに関する Books API へのリクエストは、認証済みのユーザーによって承認される必要があります。

OAuth 2.0 の承認プロセス、つまり「フロー」の詳細は、開発するアプリケーションの種類によって多少異なりますが、次の一般的なプロセスはすべての種類のアプリケーションに当てはまります。

アプリケーションの作成時に、Google API Console を使用してアプリケーションを登録します。後で必要になるクライアント ID やクライアントシークレットなどの情報が Google から提供されます。
Google API Console で Books API を有効にする（Indexing API が API Console に表示されない場合は、この手順をスキップしてください）。
アプリケーションでユーザーデータにアクセスする必要がある場合は、特定のアクセスのスコープを Google にリクエストします。
データをリクエストするアプリケーションの承認を求める Google の同意画面がユーザーに表示されます。
ユーザーが承認すると、Google はアプリケーションに有効期間が短いアクセストークンを付与します。
アプリケーションはリクエストにそのアクセストークンを付けて、ユーザーデータをリクエストします。
Google によりリクエストとトークンが有効であると判断されると、リクエストしたデータが返されます。

新しいアクセストークンを取得するためにリフレッシュトークンを使用するなど、承認フローには追加のステップがあります。各種アプリケーションのフローについて詳しくは、Google の OAuth 2.0 ドキュメントをご覧ください。

Books API の OAuth 2.0 スコープ情報は次のとおりです。

https://www.googleapis.com/auth/books

OAuth 2.0 を使用してアクセスをリクエストするには、アプリケーションの登録時に Google より提供される情報（クライアント ID やクライアントシークレットなど）の他に、スコープ情報が必要です。

ヒント: Google API クライアントライブラリによって、承認プロセスの一部が処理されることがあります。さまざまなプログラミング言語で利用できます。詳細についてはライブラリとサンプルのページをご覧ください。

API キーの取得と使用

一般公開データに対する Books API へのリクエストには、識別子（API キーまたはアクセストークン）を付ける必要があります。

API キーを取得するには:

API コンソールで [認証情報] ページを開きます。
この API は、2 種類の認証情報をサポートしています。プロジェクトに適した認証情報を作成します。
- OAuth 2.0: アプリケーションからユーザーの限定公開データをリクエストする場合は、リクエストとともに OAuth 2.0 トークンを送信する必要があります。アプリケーションは、トークンを取得するためにまずクライアント ID を送信します。場合によってはクライアントシークレットも送信します。ウェブアプリケーション、サービスアカウント、インストールしたアプリケーションについて OAuth 2.0 認証情報を生成できます。
  
  詳細については、OAuth 2.0 ドキュメントをご覧ください。
- API キー: OAuth 2.0 トークンを提供しない場合は、API キーを送信する必要があります。キーによりプロジェクトが識別され、API アクセス、割り当て、レポートが提供されます。
  
  API は、いくつかのタイプの API キーをサポートします。必要とする API キーのタイプが存在しない場合は、[認証情報作成] > [API キー] をクリックして、コンソールで API キーを作成します。本番環境でそれを使用する前にキーを制限するには、[キーを制限] をクリックして、いずれかの制限を選択します。

API キーの安全性を保つには、API キーを安全に使用するためのおすすめの方法に従ってください。

API キーを作成したら、アプリケーションですべてのリクエスト URL の末尾にクエリパラメータ key=yourAPIKey を追加できます。

API キーは URL に埋め込んでも安全です。エンコーディングの必要はありません。

Google ブックス ID

特定の API メソッド呼び出しで ID フィールドを指定する必要があります。Google ブックスで使用する ID は 3 種類あります。

ボリューム ID - Google ブックスが認識している各ボリュームに固有の文字列。ボリューム ID の例は _LettPDhwR0C です。API を使用すると、Volume リソースを返すリクエストを行うことで、Volume ID を取得できます。Volume ID は、id フィールドで確認できます。
ブックシェルフ ID - ユーザーのライブラリ内のブックシェルフに付与される数値。Google では、次の ID を持つすべてのユーザー向けに、いくつかのセクションが事前定義されています。
- お気に入り: 0
- 購入済み: 1
- 読む: 2
- 読書: 3
- 既読: 4
- 確認済み: 5 件
- 最近表示した項目: 6 件
- マイ電子書籍: 7
- Books For You: 8 Google がユーザーに推奨する本棚がなかった場合、この本棚は存在しません。
カスタムシェルフの ID は 1,000 を超えています。本棚 ID は、ユーザーごとに一意です。つまり、2 人のユーザーが、同じ ID の本棚が別の本棚を参照する場合があります。Bookshelf ID を取得するには、API を使用して Bookshelf リソースを返すリクエストを実行します。bookshelf ID は、id フィールドで確認できます。
ユーザー ID - 各ユーザーに割り当てられる一意の数値。これらの値は、他の Google サービスで使用される ID 値と同じとは限りません。現在、ユーザー ID を取得する唯一の方法は、認証済みリクエストで取得した Bookshelf リソースの selfLink からユーザー ID を抽出することです。ユーザーは、ブックスサイトから自分のユーザー ID を取得することもできます。あるユーザーが、API またはブックスサイトから別のユーザーのユーザー ID を取得することはできません。そのようなユーザーは、たとえばメールを介して、その情報を明示的に共有する必要があります。

Google ブックスサイトの ID

Books API で使用する ID は、Google ブックスサイトで使用する ID と同じです。

ボリューム ID

サイトで特定のボリュームを表示すると、id URL パラメータでボリューム ID を確認できます。次に例を示します。
```
https://books.google.com/ebooks?id=buc0AAAAMAAJ&dq=holmes&as_brr=4&source=webstore_bookcard
```
Bookshelf ID（本棚 ID）
サイトで特定の本棚を表示している場合は、as_coll URL パラメータで本棚 ID を確認できます。次に例を示します。
```
https://books.google.com/books?hl=en&as_coll=0&num=10&uid=11122233344455566778&source=gbs_slider_cls_metadata_0_mylibrary
```
ユーザー ID

サイトでライブラリを表示すると、uid URL パラメータでユーザー ID を確認できます。次に例を示します。
```
https://books.google.com/books?uid=11122233344455566778&source=gbs_lp_bookshelf_list
```

ユーザーの所在地の設定

Google ブックスは、エンドユーザーの地域に関連する著作権、契約、その他の法的制限を尊重します。その結果、一部の国のユーザーが、書籍のコンテンツにアクセスできない場合があります。たとえば、一部の書籍は「プレビュー可能」であり、米国でのみ有効です。その他の国では、このようなプレビューリンクを省略します。そのため、API の結果はサーバーまたはクライアントアプリケーションの IP アドレスに基づいて制限されます。

ボリュームの操作

検索の実行

ボリューム検索を実行するには、HTTP GET リクエストを次の URI に送信します。

https://www.googleapis.com/books/v1/volumes?q=search+terms

このリクエストにはパラメータが 1 つあります。

q - このテキスト文字列を含むボリュームを検索します。検索キーワードで特別なフィールドを指定できます。次のようなフィールドを検索できます。
- intitle:: キーワードの後に続くテキストがタイトル内で見つかった結果を返します。
- inauthor:: キーワードの後に続くテキストが作成者内で見つかった結果を返します。
- inpublisher: キーワードに続くテキストがパブリッシャー内で見つかった結果を返します。
- subject: このキーワードの後のテキストがボリュームのカテゴリリストに含まれている結果を返します。
- isbn:: キーワードの後のテキストが ISBN 番号である結果を返します。
- lccn: キーワードの後のテキストが米国議会図書館管理番号である結果を返します。
- oclc:: キーワードに続くテキストが Online Computer Library Center 番号である結果を返します。

リクエスト

Daniel Keyes' "Flowers for Algernon" を検索した例を次に示します。

GET https://www.googleapis.com/books/v1/volumes?q=flowers+inauthor:keyes&key=yourAPIKey

注: 検索の実行には認証は不要なため、GET リクエストに Authorization HTTP ヘッダーを含める必要はありません。ただし、認証を使用して呼び出しが行われる場合、各 Volume には、購入ステータスなど、ユーザー固有の情報が含まれます。

レスポンス

リクエストが成功すると、サーバーは 200 OK HTTP ステータスコードとボリュームの結果を返します。

200 OK

{
 "kind": "books#volumes",
 "items": [
  {
   "kind": "books#volume",
   "id": "_ojXNuzgHRcC",
   "etag": "OTD2tB19qn4",
   "selfLink": "https://www.googleapis.com/books/v1/volumes/_ojXNuzgHRcC",
   "volumeInfo": {
    "title": "Flowers",
    "authors": [
     "Vijaya Khisty Bodach"
    ],
   ...
  },
  {
   "kind": "books#volume",
   "id": "RJxWIQOvoZUC",
   "etag": "NsxMT6kCCVs",
   "selfLink": "https://www.googleapis.com/books/v1/volumes/RJxWIQOvoZUC",
   "volumeInfo": {
    "title": "Flowers",
    "authors": [
     "Gail Saunders-Smith"
    ],
    ...
  },
  {
   "kind": "books#volume",
   "id": "zaRoX10_UsMC",
   "etag": "pm1sLMgKfMA",
   "selfLink": "https://www.googleapis.com/books/v1/volumes/zaRoX10_UsMC",
   "volumeInfo": {
    "title": "Flowers",
    "authors": [
     "Paul McEvoy"
    ],
    ...
  },
  "totalItems": 3
}

省略可能なクエリパラメータ

ボリューム検索を実行する場合は、標準クエリパラメータに加えて、次のクエリパラメータを使用できます。

ダウンロード形式

download パラメータを使用して、の値を epub に設定することにより、利用可能なダウンロード形式が epub のボリュームのみを返します。

次の例では、epub をダウンロードできる書籍を検索します。

GET https://www.googleapis.com/books/v1/volumes?q=pride+prejudice&download=epub&key=yourAPIKey

フィルタ処理

filter パラメータを使用して、次のいずれかの値に設定することで、返される結果をさらに制限できます。

partial - テキストの少なくとも一部がプレビュー可能な結果を返します。
full - すべてのテキストを表示できる結果のみを返します。
free-ebooks - 無料の Google 電子書籍の検索結果のみを返します。
paid-ebooks - 価格が設定された Google 電子書籍の結果のみを返します。
ebooks - Google 電子書籍（有料または無料）の結果のみを返します。電子書籍以外の例としては、限定プレビューで提供され、販売対象外の出版社のコンテンツや雑誌などがあります。

次の例では、検索結果を無料で提供するものとして検索結果を限定しています。

GET https://www.googleapis.com/books/v1/volumes?q=flowers&filter=free-ebooks&key=yourAPIKey

ページ分け

ボリュームのデータをページ分けするには、リクエストのパラメータに 2 つの値を指定します。

startIndex - コレクション内で開始する位置。最初の項目のインデックスは 0 です。
maxResults - 返される結果の最大数。デフォルトは 10 で、最大許容値は 40 です。

印刷の種類

printType パラメータで次のいずれかの値に設定すると、返される結果を特定の印刷タイプまたはパブリケーションタイプに制限できます。

all - 印刷タイプで制限しません（デフォルト）。
books - 書籍である結果のみを返します。
magazines - 雑誌の検索結果を返します。

次の例では、検索結果を雑誌に限定しています。

GET https://www.googleapis.com/books/v1/volumes?q=time&printType=magazines&key=yourAPIKey

予測

projection パラメータに次のいずれかの値を指定して、返す事前定義された Volume フィールドのセットを指定できます。

full - すべての Volume フィールドを返します。
lite - 特定のフィールドのみを返します。二重アスタリスクの付いたフィールドの説明については、ボリュームのリファレンスで該当するフィールドを確認してください。

次の例では、検索結果が限定的なボリューム情報を返します。

GET https://www.googleapis.com/books/v1/volumes?q=flowers&projection=lite&key=yourAPIKey

並べ替え

デフォルトでは、ボリューム検索リクエストは maxResults の結果を返します。maxResults は、ページ分けで使用されるパラメータ（上記）が検索キーワードとの関連性の高い順です。

順序を変更するには、orderBy パラメータを次のいずれかの値に設定します。

relevance - 検索キーワードの関連性の順に検索結果を返します（デフォルトはデフォルト）。
newest - 最近の結果から最近のものの順に結果を返します。

次の例では、結果を最新の日付から新しい日付の順にリストしています。

GET https://www.googleapis.com/books/v1/volumes?q=flowers&orderBy=newest&key=yourAPIKey

特定のボリュームを取得する

特定のボリュームの情報を取得するには、HTTP GET リクエストを Volume リソース URI に送信します。

https://www.googleapis.com/books/v1/volumes/volumeId

volumeId パスパラメータを、取得するボリュームの ID に置き換えます。ボリューム ID について詳しくは、Google ブックス ID をご覧ください。

リクエスト

以下に、単一のボリュームを取得する GET リクエストの例を示します。

GET https://www.googleapis.com/books/v1/volumes/zyTCAlFPjgYC?key=yourAPIKey

注: ボリューム情報の取得には認証は不要であるため、GET リクエストで Authorization HTTP ヘッダーを指定する必要はありません。ただし、認証によって呼び出しが行われると、Volume には購入ステータスなどのユーザー固有の情報が含まれます。

レスポンス

リクエストが成功すると、サーバーは 200 OK HTTP ステータスコードとリクエストされた Volume リソースを返します。

200 OK

{
 "kind": "books#volume",
 "id": "zyTCAlFPjgYC",
 "etag": "f0zKg75Mx/I",
 "selfLink": "https://www.googleapis.com/books/v1/volumes/zyTCAlFPjgYC",
 "volumeInfo": {
  "title": "The Google story",
  "authors": [
   "David A. Vise",
   "Mark Malseed"
  ],
  "publisher": "Random House Digital, Inc.",
  "publishedDate": "2005-11-15",
  "description": "\"Here is the story behind one of the most remarkable Internet
  successes of our time. Based on scrupulous research and extraordinary access
  to Google, ...",
  "industryIdentifiers": [
   {
    "type": "ISBN_10",
    "identifier": "055380457X"
   },
   {
    "type": "ISBN_13",
    "identifier": "9780553804577"
   }
  ],
  "pageCount": 207,
  "dimensions": {
   "height": "24.00 cm",
   "width": "16.03 cm",
   "thickness": "2.74 cm"
  },
  "printType": "BOOK",
  "mainCategory": "Business & Economics / Entrepreneurship",
  "categories": [
   "Browsers (Computer programs)",
   ...
  ],
  "averageRating": 3.5,
  "ratingsCount": 136,
  "contentVersion": "1.1.0.0.preview.2",
  "imageLinks": {
   "smallThumbnail": "https://books.google.com/books?id=zyTCAlFPjgYC&printsec=frontcover&img=1&zoom=5&edge=curl&source=gbs_api",
   "thumbnail": "https://books.google.com/books?id=zyTCAlFPjgYC&printsec=frontcover&img=1&zoom=1&edge=curl&source=gbs_api",
   "small": "https://books.google.com/books?id=zyTCAlFPjgYC&printsec=frontcover&img=1&zoom=2&edge=curl&source=gbs_api",
   "medium": "https://books.google.com/books?id=zyTCAlFPjgYC&printsec=frontcover&img=1&zoom=3&edge=curl&source=gbs_api",
   "large": "https://books.google.com/books?id=zyTCAlFPjgYC&printsec=frontcover&img=1&zoom=4&edge=curl&source=gbs_api",
   "extraLarge": "https://books.google.com/books?id=zyTCAlFPjgYC&printsec=frontcover&img=1&zoom=6&edge=curl&source=gbs_api"
  },
  "language": "en",
  "infoLink": "https://books.google.com/books?id=zyTCAlFPjgYC&ie=ISO-8859-1&source=gbs_api",
  "canonicalVolumeLink": "https://books.google.com/books/about/The_Google_story.html?id=zyTCAlFPjgYC"
 },
 "saleInfo": {
  "country": "US",
  "saleability": "FOR_SALE",
  "isEbook": true,
  "listPrice": {
   "amount": 11.99,
   "currencyCode": "USD"
  },
  "retailPrice": {
   "amount": 11.99,
   "currencyCode": "USD"
  },
  "buyLink": "https://books.google.com/books?id=zyTCAlFPjgYC&ie=ISO-8859-1&buy=&source=gbs_api"
 },
 "accessInfo": {
  "country": "US",
  "viewability": "PARTIAL",
  "embeddable": true,
  "publicDomain": false,
  "textToSpeechPermission": "ALLOWED_FOR_ACCESSIBILITY",
  "epub": {
   "isAvailable": true,
   "acsTokenLink": "https://books.google.com/books/download/The_Google_story-sample-epub.acsm?id=zyTCAlFPjgYC&format=epub&output=acs4_fulfillment_token&dl_type=sample&source=gbs_api"
  },
  "pdf": {
   "isAvailable": false
  },
  "accessViewStatus": "SAMPLE"
 }
}

情報にアクセス

accessInfo セクションは、電子書籍で使用できる機能を判断するうえで特に重要です。epub はフローテキスト形式の電子書籍です。epub セクションには、このタイプの電子書籍が使用可能かどうかを示す isAvailable プロパティがあります。書籍のサンプルがあるか、ユーザーが購入したか、ユーザーの所在地でパブリックドメインだったために書籍を読める場合、ダウンロードリンクが表示されます。Google ブックスの pdf は、電子書籍のスキャン済みページバージョンを示します。バージョンやダウンロードリンクなどの詳細情報も表示されます。電子書籍リーダーやスマートフォンには、epub ファイルを使用することをおすすめします。スキャンされたページは、デバイス上で読みにくい可能性があるためです。accessInfo セクションがない場合、ボリュームは Google 電子書籍として利用できません。

省略可能なクエリパラメータ

特定のボリュームを取得する場合は、標準クエリパラメータに加えて、次のクエリパラメータを使用できます。

予測

projection パラメータに次のいずれかの値を指定して、返す事前定義された Volume フィールドのセットを指定できます。

full - すべての Volume フィールドを返します。
lite - 特定のフィールドのみを返します。二重アスタリスクの付いたフィールドの説明については、ボリュームのリファレンスで該当するフィールドを確認してください。

次の例では、1 つのボリュームのボリューム情報を限定して返します。

GET https://www.googleapis.com/books/v1/volumes/zyTCAlFPjgYC?projection=lite&key=yourAPIKey

本棚の操作

ユーザーの公開本棚のリストを取得する

ユーザーの公開本棚のリストを取得するには、次の形式で HTTP GET リクエストを URI に送信します。

https://www.googleapis.com/books/v1/users/userId/bookshelves

userId パスパラメータを、本棚を取得するユーザーの ID に置き換えます。ユーザー ID について詳しくは、Google ブックス ID をご覧ください。

リクエスト

次に例を示します。

GET https://www.googleapis.com/books/v1/users/1112223334445556677/bookshelves&key=yourAPIKey

公開の本棚に関する情報を取得するためにユーザーを認証する必要がないため、GET リクエストで Authorization HTTP ヘッダーを指定する必要はありません。

レスポンス

リクエストが成功すると、サーバーは 200 OK HTTP ステータスコードと本棚のリストを返します。

200 OK

{
 "kind": "books#bookshelves",
 "items": [
  {
   ...
  },
  {
   "kind": "books#bookshelf",
   "id": 3,
   "selfLink": "https://www.googleapis.com/books/v1/users/1112223334445556677/bookshelves/3",
   "title": "Reading now",
   "description": "",
   "access": "PUBLIC",
   "updated": "2011-02-02T20:34:20.146Z",
   "created": "2011-02-02T20:34:20.146Z",
   "volumeCount": 2,
   "volumesLastUpdated": "2011-02-02T20:34:20.110Z"
  },
  ...
 ]
}

省略可能なクエリパラメータ

ユーザーの公開本棚のリストを取得する場合は、標準のクエリパラメータを使用できます。

特定の一般公開の本棚を取得する

特定の公開ブックシェルフを取得するには、次の形式で HTTP GET リクエストを URI に送信します。

https://www.googleapis.com/books/v1/users/userId/bookshelves/shelf

userId と shelf のパスパラメータを、取得するユーザーと本棚を指定する ID に置き換えます。詳しくは、Google ブックス ID をご覧ください。

リクエスト

次に例を示します。

GET https://www.googleapis.com/books/v1/users/1112223334445556677/bookshelves/3?key=yourAPIKey

レスポンス

リクエストが成功すると、サーバーは 200 OK HTTP ステータスコードとブックシェルフリソースで応答します。

200 OK

{
  "kind": "books#bookshelf",
  "id": 3,
  "selfLink": "https://www.googleapis.com/books/v1/users/1112223334445556677/bookshelves/3",
  "title": "Reading now",
  "description": "",
  "access": "PUBLIC",
  "updated": "2011-02-02T20:34:20.146Z",
  "created": "2011-02-02T20:34:20.146Z",
  "volumeCount": 2,
  "volumesLastUpdated": "2011-02-02T20:34:20.110Z"
}

省略可能なクエリパラメータ

特定の公開ブックシェルフを取得する場合は、標準クエリパラメータを使用できます。

公開されている本棚のボリュームの一覧を取得する

ユーザーの公開本棚にあるボリュームのリストを取得するには、HTTP GET リクエストを次の形式の URI で送信します。

https://www.googleapis.com/books/v1/user/userId/bookshelves/shelf/volumes

リクエスト

次に例を示します。

GET https://www.googleapis.com/books/v1/users/1112223334445556677/bookshelves/3/volumes?key=yourAPIKey

userId と shelf のパスパラメータを、取得するユーザーと本棚を指定する ID に置き換えます。詳しくは、Google ブックス ID をご覧ください。

レスポンス

リクエストが成功すると、サーバーは 200 OK HTTP ステータスコードとユーザーの本棚のリストを返します。

200 OK

{
 "kind": "books#volumes",
 "items": [
  {
   "kind": "books#volume",
   "id": "AZ5J6B1-4BoC",
   "etag": "kIzQA7IUObk",
   "selfLink": "https://www.googleapis.com/books/v1/volumes/AZ5J6B1-4BoC",
   "volumeInfo": {
    "title": "The Girl Who Kicked the Hornet's Nest",
    "authors": [
     "Stieg Larsson"
    ],
    "publisher": "Knopf",
    "publishedDate": "2010-05-25",
    ...
  },
  {
   "kind": "books#volume",
   "id": "UvK1Slvkz3MC",
   "etag": "otKmdbRgdFQ",
   "selfLink": "https://www.googleapis.com/books/v1/volumes/UvK1Slvkz3MC",
   "volumeInfo": {
    "title": "The Girl who Played with Fire",
    "authors": [
     "Stieg Larsson"
    ],
    "publisher": "Knopf",
    "publishedDate": "2009-07-28",
    ...
  },
  {
   "kind": "books#volume",
   "id": "OBM3AAAAIAAJ",
   "etag": "xb47kTr8HsQ",
   "selfLink": "https://www.googleapis.com/books/v1/volumes/OBM3AAAAIAAJ",
   "volumeInfo": {
    "title": "The Sign of Four",
    "authors": [
     "Sir Arthur Conan Doyle"
    ],
    "publishedDate": "1890",
    ...
  }
 ],
 "totalItems": 3
}

省略可能なクエリパラメータ

一般公開の本棚でボリュームのリストを取得する場合は、標準クエリパラメータに加えて、次のクエリパラメータを使用できます。

ページ分け

ボリュームのデータをページ分けするには、リクエストのパラメータに 2 つの値を指定します。

startIndex - コレクション内で開始する位置。最初の項目のインデックスは 0 です。
maxResults - 返される結果の最大数。デフォルトは 10 で、最大許容値は 40 です。

マイライブラリの本棚の扱い

すべてのマイライブラリのリクエストは、認証済みユーザーのデータに適用されます。

本棚のリストの取得

次の形式で HTTP GET リクエストを URI に送信することで、認証済みユーザーのすべての本棚のリストを取得できます。

https://www.googleapis.com/books/v1/mylibrary/bookshelves

リクエスト

次に例を示します。

GET https://www.googleapis.com/books/v1/mylibrary/bookshelves?key=yourAPIKey
Authorization: /* auth token here */

注: 「本棚」のリストを取得するには、ユーザーを認証する必要があります。したがって、GET リクエストで Authorization HTTP ヘッダーを指定する必要があります。

レスポンス

リクエストが成功すると、サーバーは 200 OK HTTP ステータスコードと、現在の認証済みユーザーのすべての本棚のリストを返します。

200 OK

{
 "kind": "books#bookshelves",
 "items": [
  {
   "kind": "books#bookshelf",
   "id": 0,
   "selfLink": "https://www.googleapis.com/books/v1/users/1112223334445556677/bookshelves/0",
   "title": "Favorites",
   "access": "PRIVATE",
   "updated": "2011-04-22T04:03:15.416Z",
   "created": "2011-04-22T04:03:15.416Z",
   "volumeCount": 0,
   "volumesLastUpdated": "2011-04-22T04:03:17.000Z"
  },
  {
   "kind": "books#bookshelf",
   "id": 3,
   "selfLink": "https://www.googleapis.com/books/v1/users/1112223334445556677/bookshelves/3",
   "title": "Reading now",
   "access": "PUBLIC",
   "updated": "2010-11-11T19:44:22.377Z",
   "created": "2010-11-11T19:44:22.377Z",
   "volumeCount": 1,
   "volumesLastUpdated": "2010-11-11T19:44:22.341Z"
  }
 ]
}

省略可能なクエリパラメータ

認証済みのユーザーのリストを取得する場合は、標準クエリパラメータを使用できます。

本棚で本の一覧を取得する

次の形式で HTTP GET リクエストを URI に送信することで、認証済みユーザーの本棚にあるボリュームのリストを取得できます。

https://www.googleapis.com/books/v1/mylibrary/bookshelves/shelf/volumes

shelf パスパラメータをブックシェルフの ID に置き換えます。本棚の ID について詳しくは、Google ブックス ID をご覧ください。

リクエスト

次に例を示します。

GET https://www.googleapis.com/books/v1/mylibrary/bookshelves/7/volumes?key=yourAPIKey
Authorization: /* auth token here */

注: 「マイライブラリ」のボリュームのリストを取得するには、ユーザーを認証する必要があります。したがって、GET リクエストで Authorization HTTP ヘッダーを指定する必要があります。

レスポンス

リクエストが成功すると、サーバーは 200 OK HTTP ステータスコードと本棚のボリュームのリストを返します。

200 OK

{
 "kind": "books#volumes",
 "items": [
  {
   "kind": "books#volume",
   "id": "AZ5J6B1-4BoC",
   "etag": "kIzQA7IUObk",
   "selfLink": "https://www.googleapis.com/books/v1/volumes/AZ5J6B1-4BoC",
   "volumeInfo": {
    "title": "The Girl Who Kicked the Hornet's Nest",
    "authors": [
     "Stieg Larsson"
    ],
    "publisher": "Knopf",
    "publishedDate": "2010-05-25",
    ...
  },
  {
   "kind": "books#volume",
   "id": "UvK1Slvkz3MC",
   "etag": "otKmdbRgdFQ",
   "selfLink": "https://www.googleapis.com/books/v1/volumes/UvK1Slvkz3MC",
   "volumeInfo": {
    "title": "The Girl who Played with Fire",
    "authors": [
     "Stieg Larsson"
    ],
    "publisher": "Knopf",
    "publishedDate": "2009-07-28",
    ...
  },
  {
   "kind": "books#volume",
   "id": "OBM3AAAAIAAJ",
   "etag": "xb47kTr8HsQ",
   "selfLink": "https://www.googleapis.com/books/v1/volumes/OBM3AAAAIAAJ",
   "volumeInfo": {
    "title": "The Sign of Four",
    "authors": [
     "Sir Arthur Conan Doyle"
    ],
    "publishedDate": "1890",
    ...
  }
 ],
 "totalItems": 3
}

省略可能なクエリパラメータ

認証されたユーザーの本棚の 1 つのボリュームのリストを取得する場合は、標準クエリパラメータに加えて、次のクエリパラメータを使用できます。

ページ分け

ボリュームのデータをページ分けするには、リクエストのパラメータに 2 つの値を指定します。

startIndex - コレクション内で開始する位置。最初の項目のインデックスは 0 です。
maxResults - 返される結果の最大数。デフォルトは 10 です。

本棚に本を追加する

認証済みユーザーのブックシェルフにボリュームを追加するには、次の形式で HTTP POST リクエストを URI に送信します。

https://www.googleapis.com/books/v1/mylibrary/bookshelves/shelf/addVolume

shelf パスパラメータをブックシェルフの ID に置き換えます。本棚の ID について詳しくは、Google ブックス ID をご覧ください。

リクエストに 1 つの必須のクエリパラメータがある。

volumeId - ボリュームの ID。ボリューム ID について詳しくは、Google ブックス ID をご覧ください。

リクエスト

たとえば、「Flowers for Algernon」を「Favorites」に追加した場合は次のようになります。

POST https://www.googleapis.com/books/v1/mylibrary/bookshelves/0/addVolume?volumeId=NRWlitmahXkC&key=yourAPIKey
Authorization: /* auth token here */
Content-Type: application/json
Content-Length: CONTENT_LENGTH

注: 本棚を変更するには、ユーザーを認証する必要があります。そのため、POST リクエストで Authorization HTTP ヘッダーを指定する必要があります。ただし、この POST ではデータは必要ありません。

レスポンス

リクエストが成功すると、サーバーは 204 No Content HTTP ステータスコードを返します。

省略可能なクエリパラメータ

認証されたユーザーのシェルフのいずれかにボリュームを追加するときに、標準のクエリパラメータを使用できます。

本棚から本を削除する

認証済みユーザーのブックシェルフからボリュームを削除するには、HTTP POST を次の形式で URI に送信します。

https://www.googleapis.com/books/v1/mylibrary/bookshelves/shelf/removeVolume

shelf パスパラメータをブックシェルフの ID に置き換えます。本棚の ID について詳しくは、Google ブックス ID をご覧ください。

リクエストに 1 つの必須のクエリパラメータがある。

volumeId - ボリュームの ID。ボリューム ID について詳しくは、Google ブックス ID をご覧ください。

リクエスト

一例を挙げると、「Flowers for Algernon」を「Favorites」から削除します。

POST https://www.googleapis.com/books/v1/mylibrary/bookshelves/0/removeVolume?volumeId=NRWlitmahXkC&key=yourAPIKey
Authorization: /* auth token here */
Content-Type: application/json
Content-Length: CONTENT_LENGTH

レスポンス

リクエストが成功すると、サーバーは 204 No Content ステータスコードを返します。

省略可能なクエリパラメータ

認証済みのユーザーの本棚から Volume を削除するときに、標準クエリパラメータを使用できます。

本棚からすべての音量をクリアする

認証済みの本棚からすべてのボリュームを削除するには、次の形式の HTTP POST を URI に送信します。

https://www.googleapis.com/books/v1/mylibrary/bookshelves/shelf/clearVolumes

shelf パスパラメータをブックシェルフの ID に置き換えます。本棚の ID について詳しくは、Google ブックス ID をご覧ください。

リクエスト

以下は、「お気に入り」を消去する例です。

POST https://www.googleapis.com/books/v1/mylibrary/bookshelves/0/clearVolumes?key=yourAPIKey
Authorization: /* auth token here */
Content-Type: application/json
Content-Length: CONTENT_LENGTH

レスポンス

リクエストが成功すると、サーバーは 204 No Content ステータスコードを返します。

省略可能なクエリパラメータ

認証済みユーザーの本棚からすべてのボリュームを消去するには、標準クエリパラメータを使用します。

クエリパラメータリファレンス

Books API で使用できるクエリパラメータについて簡単に説明します。すべてのパラメータ値は URL エンコードする必要があります。

標準のクエリパラメータ

Books API のすべてのオペレーションに適用されるクエリパラメータは、システムパラメータに記載されています。

API 固有のクエリパラメータ

Books API の特定のオペレーションだけに適用されるリクエストパラメータの概要を次の表にまとめます。

パラメータ	意味	備考	適用性
`download`	ダウンロードの可用性に基づいてボリュームに制限します。	現在サポートされている値は、`epub` のみです。ダウンロードするにはアクセスが必要となる場合があります。	検索の実行
`filter`	検索結果をボリュームの種類と在庫状況でフィルタできます。	サポートされているフィルタは次のとおりです。 `filter=partial` - 結果を、テキストの少なくとも一部がプレビュー可能なボリュームに制限します。 `filter=full` - 結果をすべてのテキストを表示できるボリュームに制限します。 `filter=free-ebooks` - 結果を無料の Google 電子書籍に制限します。 `filter=paid-ebooks` - 結果を購入価格の Google 電子書籍に限定します。 `filter=ebooks` - 結果を Google 電子書籍（有料または無料）に限定します。電子書籍以外の例としては、限定プレビューで提供され、販売対象外の出版社のコンテンツや雑誌などがあります。	検索の実行
`langRestrict`	返されるボリュームを、指定した言語でタグ付けされたボリュームに制限します。	`langRestrict` を ISO 639-1 の 2 文字のコード（たとえば「en」または「fr」など）で指定して、検索結果を特定の言語に限定します。	検索の実行
`maxResults`	このリクエストで返される要素の最大数。	コレクション内のすべてのアイテムに対するリクエストでは、リクエストのパラメータに `startIndex` と `maxResults` を指定して、結果をページ分割できます。デフォルト: `maxResults=10` 最大許容値: `maxResults=40.`	検索の実行ユーザーの本棚を一覧表示するユーザーの本棚のボリュームを一覧表示する本棚を一覧表示する本棚のボリュームを一覧表示する
`orderBy`	ボリュームの検索結果の順序。	デフォルトでは、検索リクエストは `maxResults` の結果を返します。`maxResults` は、ページ分けに使用されるパラメータで、関連性の高い順に並べられます。順序を変更するには、`orderBy` パラメータを次のいずれかの値に設定します。 `orderBy=relevance` - 関連性の高い順（デフォルト）に検索結果を返します。 `orderBy=newest` - 検索結果を新しい日付から古い日付の順で返します。	検索の実行
`printType`	書籍または雑誌に限定します。	指定できる値は次のとおりです。 `printType=all` - すべてのボリュームコンテンツタイプを返します（制限なし）。グローバルウィンドウはデフォルト。 `printType=books` - 書籍のみを返します。 `printType=magazines` - 雑誌のみを返します。	検索の実行
`projection`	フィールドのサブセットに返されるボリューム情報を制限します。	サポートされている投影法は次のとおりです。 `projection=full` - すべてのボリュームメタデータが含まれます（デフォルト）。 `projection=lite` - ボリュームとアクセスメタデータのサブジェクトのみが含まれます。	検索の実行ボリュームの取得ユーザーの本棚のボリュームを一覧表示する本棚のボリュームを一覧表示する
`q`	全文クエリ文字列。	クエリの作成時に検索語句を '+' で区切って、`q=term1+term2_term3` の形式でリストします。（あるいは、スペースで区切ることもできますが、すべてのクエリパラメータ値と同様に、スペースは URL エンコードする必要があります）。API は、すべての検索語句に一致するエントリをすべて返します（AND 条件を使用など）。Google のウェブ検索と同様に、API では部分文字列ではなく、完全な単語（および同じ語幹の関連単語）に基づいて検索が行われます。完全に一致するフレーズを検索するには、フレーズを引用符で囲みます（`q="exact phrase"`）。特定の用語に一致するエントリを除外するには、`q=-term` の形式を使用します。検索語句では大文字と小文字が区別されません。例: 完全に一致するフレーズ「`"Elizabeth Bennet"`」と単語「`"Darcy"`」を含み、単語「`"Austen"`」を含まないすべてのエントリを検索するには、次のクエリパラメータ値を使用します。`q="Elizabeth+Bennet"+Darcy-Austen` 次のように、検索語句の中で特別な（大文字と小文字が区別される）キーワードを指定して特定のフィールドを検索できます。 `intitle`: キーワードに続くテキストがタイトル内で見つかった結果を返します。 `inauthor`: キーワードの後に続くテキストが作成者によって見つかった結果を返します。 `inpublisher`: キーワードに続くテキストがパブリッシャー内で見つかった結果を返します。 `subject`: このキーワードの後のテキストがボリュームのカテゴリリストに含まれている結果を返します。 `isbn`: キーワードの後のテキストが ISBN 番号である結果を返します。 `lccn`: このキーワードの後のテキストが米国議会図書館管理番号である結果を返します。 `oclc`: キーワードの後のテキストが Online Computer Library Center 番号である結果を返します。	検索の実行
`startIndex`	結果のリストを開始するコレクション内の位置。	コレクション内のすべてのアイテムのどのリクエストに対しても、リクエストのパラメータに `startIndex` と `maxResults` を指定して、結果をページ分割できます。最初の項目のインデックスは 0 です。	検索の実行ユーザーの本棚を一覧表示するユーザーの本棚のボリュームを一覧表示する本棚を一覧表示する本棚のボリュームを一覧表示する
`volumeId`	リクエストに関連付けられたボリュームを識別します。	本棚に追加または削除するボリュームを指定します。	本棚に本を追加する本棚から本を削除する

API の使用

目次

はじめに

リクエストの承認とアプリケーションの識別

認証プロトコルについて

OAuth 2.0 によるリクエストの承認

API キーの取得と使用

Google ブックス ID

Google ブックス サイトの ID

ユーザーの所在地の設定

ボリュームの操作

検索の実行

リクエスト

レスポンス

省略可能なクエリ パラメータ

ダウンロード形式

フィルタ処理

ページ分け

印刷の種類

予測

並べ替え

特定のボリュームを取得する

リクエスト

レスポンス

情報にアクセス

省略可能なクエリ パラメータ

予測

本棚の操作

ユーザーの公開本棚のリストを取得する

リクエスト

レスポンス

省略可能なクエリ パラメータ

特定の一般公開の本棚を取得する

リクエスト

レスポンス

省略可能なクエリ パラメータ

公開されている本棚のボリュームの一覧を取得する

リクエスト

レスポンス

省略可能なクエリ パラメータ

ページ分け

マイライブラリの本棚の扱い

本棚のリストの取得

リクエスト

レスポンス

省略可能なクエリ パラメータ

本棚で本の一覧を取得する

リクエスト

レスポンス

省略可能なクエリ パラメータ

ページ分け

本棚に本を追加する

リクエスト

レスポンス

省略可能なクエリ パラメータ

本棚から本を削除する

リクエスト

レスポンス

省略可能なクエリ パラメータ

本棚からすべての音量をクリアする

リクエスト

レスポンス

省略可能なクエリ パラメータ

クエリ パラメータ リファレンス

標準のクエリ パラメータ

API 固有のクエリ パラメータ

Google ブックスサイトの ID

省略可能なクエリパラメータ

省略可能なクエリパラメータ

省略可能なクエリパラメータ

省略可能なクエリパラメータ

省略可能なクエリパラメータ

省略可能なクエリパラメータ

省略可能なクエリパラメータ

省略可能なクエリパラメータ

省略可能なクエリパラメータ

省略可能なクエリパラメータ

クエリパラメータリファレンス

標準のクエリパラメータ

API 固有のクエリパラメータ