API の使用

Stay organized with collections Save and categorize content based on your preferences.

目次

はじめに

このドキュメントは、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 の承認プロセス、つまり「フロー」の詳細は、開発するアプリケーションの種類によって多少異なりますが、次の一般的なプロセスはすべての種類のアプリケーションに当てはまります。

  1. アプリケーションの作成時に、Google API Console を使用してアプリケーションを登録します。後で必要になるクライアント ID やクライアント シークレットなどの情報が Google から提供されます。
  2. Google API Console で Books API を有効にする(Indexing API が API Console に表示されない場合は、この手順をスキップしてください)。
  3. アプリケーションでユーザーデータにアクセスする必要がある場合は、特定のアクセスのスコープを Google にリクエストします。
  4. データをリクエストするアプリケーションの承認を求める Google の同意画面がユーザーに表示されます。
  5. ユーザーが承認すると、Google はアプリケーションに有効期間が短いアクセス トークンを付与します。
  6. アプリケーションはリクエストにそのアクセス トークンを付けて、ユーザーデータをリクエストします。
  7. 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 キーを取得するには:

  1. API コンソールで [認証情報] ページを開きます。
  2. この 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

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

リクエスト

次に例を示します。

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

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

レスポンス

リクエストが成功すると、サーバーは 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

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

公開の本棚に関する情報を取得するためにユーザーを認証する必要がないため、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
}

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

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

ページ分け

ボリュームのデータをページ分けするには、リクエストのパラメータに 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

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

レスポンス

リクエストが成功すると、サーバーは 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
  

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

レスポンス

リクエストが成功すると、サーバーは 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 このリクエストで返される要素の最大数。
  • コレクション内のすべてのアイテムに対するリクエストでは、リクエストのパラメータに startIndexmaxResults を指定して、結果をページ分割できます。
  • デフォルト: 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 結果のリストを開始するコレクション内の位置。
  • コレクション内のすべてのアイテムのどのリクエストに対しても、リクエストのパラメータに startIndexmaxResults を指定して、結果をページ分割できます。
  • 最初の項目のインデックスは 0 です。
volumeId リクエストに関連付けられたボリュームを識別します。
  • 本棚に追加または削除するボリュームを指定します。