All Articles

Google Books APIsを使って本の情報を取得する

Google Books APIsは、Googleが本や雑誌の情報をAPIで提供しているサービスです。 また、ログインして使うことで、自分の本棚を作ったりすることもできます。

Books APIのコンセプト

  • ボリューム(Volume): ボリュームは、本や雑誌についてGoogle Booksがホストしているデータを表します。Books APIの主要なリソースです。

  • 本棚(Bookshelf): ユーザーは、複数のボリュームが含まれた本棚を持つことができます。本棚には下記の種類があります。本棚は公開・非公開を選択できます。

    • ユーザーが任意の本を集めた本棚
    • ユーザーの行動に基づいて自動的に更新される本棚
    • 上記が混在している本棚
  • レビュー(Review): ボリュームには、星とテキストでレビューが設定できます。ユーザーはボリューム一つに対して、一つのレビューが設定できます。
  • 読書位置(Reading Position): ボリュームには、読書位置(最後に読んだ位置)が設定できます。ユーザーはボリューム一つに対して、一つの読書位置が設定できます。

Books APIのデータリソース

Books APIが扱うデータモデルは下記の2つです。

  • ボリューム
  • 本棚 また、上記のデータモデルは、APIではコレクションで返却されます。
  • ボリュームコレクション: Google Booksが管理しているボリュームのコレクションです。全てを一度に取得することはできませんが、検索して一部を検索結果として取得することができます。

  • 本棚コレクション: Google Booksが管理するすべての本棚リソースから構成されます。本棚は、常に特定のユーザーのライブラリのコンテキストで参照されなければなりません。本棚には、0冊以上のボリュームを含めることができます。すべてのユーザーに対して下記の本棚が事前に定義されています。

    • Favorites: お気に入り本棚
    • Purchased: ユーザーが購入したボリュームで構成される本棚です。この本棚は手動で、ボリュームを追加・削除することはできません。
    • To Read: 読もうとしている本
    • Reading Now: 読んでいる本
    • Have Read: 読んだ本
    • Reviewed: ユーザーがレビューしたボリュームで構成される本棚です。この本棚は手動で、ボリュームを追加・削除することはできません。
    • Recently Viewed: ユーザーが最近ウェブリーダーで開いたボリュームで構成される本棚です。この本棚は手動で、ボリュームを追加することはできません。
    • My eBooks: ユーザーが購入したeBooksボリュームで構成される本棚です。購入したボリュームは自動で追加されます。また、手動でボリュームを削除することができます。
    • Books For You: パーソナライズされレコメンドされたボリュームの本棚です。おすすめがない場合はこの本棚は存在しません。

Books APIのオペレーション

Books APIはRESTなAPIとなっています。

  • list: コレクションに対する任意のサブセットを取得します。HTTP-GETメソッドでURIにアクセスすることで利用できます。
  • insert: コレクションに対して、新しいリソースを追加します。HTTP-POSTメソッドでURIにアクセスすることで利用できます。
  • get: 任意のリソースの詳細情報を取得します。HTTP-GETメソッドでURIにアクセスすることで利用できます。
  • update: 任意のリソースを更新し、更新後のリソースデータを取得ます。HTTP-PUTメソッドでURIにアクセスすることで利用できます。
  • delete: 任意のリソースを削除し、削除されたリソースデータを取得ます。HTTP-DELETEメソッドでURIにアクセスすることで利用できます。

また、リソースごとに上記の操作(list, insert, get, update, delete)のどれが使えるかどうかが決まっています。

  • Volumes(/volumes/volumeId, /volumes?q={search terms})

    • list: リクエストしたユーザーに依存しない、公開されたボリュームのリストを取得します。
    • list(AUTHENTICATED): リクエストしたユーザーに依存した、ボリュームのリストを取得します。
    • get: ボリュームの詳細情報を取得します。

  • Bookshelves(/users/userId/bookshelves, /users/userId/bookshelves/shelf, /users/userId/bookshelves/shelf/volumes, /mylibrary/bookshelves, /mylibrary/bookshelves/shelf, /mylibrary/bookshelves/shelf/volumes)

    • list: リクエストしたユーザーに依存しない、公開された本棚のリストを取得します。
    • list(AUTHENTICATED): リクエストしたユーザーに依存した、本棚のリストを取得します。
    • insert: 指定した本棚にボリュームを追加します。使用するには認証が必要になります。
    • get: リクエストしたユーザーに依存しない、公開された本棚詳細を取得します。
    • get(AUTHENTICATED): リクエストしたユーザーに依存した、本棚詳細を取得します。
    • update: 本棚の情報を更新します。使用するには認証が必要になります。
    • delete: 本棚を削除します。使用するには認証が必要になります。

  • Reading Positions

    • insert: 読書位置を追加します。使用するには認証が必要になります。
    • get: 読書位置の詳細を取得します。使用するには認証が必要になります。
    • update: 読書位置の詳細を更新します。使用するには認証が必要になります。
    • delete: 読書位置の詳細を削除します。使用するには認証が必要になります。

クエリストリングス

q

レスポンスのコレクションに含まれるボリュームに対して、検索するクエリを設定します。 クエリには下記のルールが適用されます。

  • クエリ内に複数の検索用語を含める場合、ふたつの方法があります。

    • q=term1+term2_term3のように'+'で区切って検索語をリストアップします。
    • 検索用語間をスペースで区切ることもできます。しかし、この方法はすべてのクエリパラメータの値と同様に、スペースをURLエンコードする必要があります。
  • APIは、(用語間のANDを使用するように)検索用語にすべて一致するすべてのエントリを返します。
  • Google のウェブ検索と同様に、APIは部分文字列ではなく、完全な単語(および同じシステムを持つ関連単語)を検索します。
  • 正確なフレーズを検索するには、フレーズを引用符で囲みます。q="exact phrase".
  • 指定された語句に一致するエントリを除外するには、q=-termという形式を使用します。
  • 検索語は大文字小文字を区別しません。

例: "Elizabeth Bennet" と "Darcy" という単語を含むが、"Austen" という単語を含まないすべてのエントリを検索するには、以下のクエリ・パラメータ値を使用します。 q="Elizabeth+Bennet "+Darcy-Austen

qで使うことができるキーワード

検索語には、特定のフィールドを検索するために指定できる特別な（大文字と小文字を区別する）キーワードがあります。

  • intitle: このキーワードに続くテキストがタイトルに含まれている場合の結果を返します。
  • inauthor: このキーワードに続くテキストが著者にある場合の結果を返します。
  • inpublisher: このキーワードに続くテキストが出版社にある場合の結果を返します。
  • subject: このキーワードに続くテキストが、そのボリュームのカテゴリリストに含まれているかどうかを返します。
  • isbn: このキーワードに続くテキストがISBN番号である場合に検索結果を返します。
  • lccn: このキーワードに続くテキストが米国議会図書館管理番号である場合に結果を返します。
  • oclc: このキーワードに続くテキストがOnline Computer Library Center番号である場合、結果を返します。

startIndex

レスポンス対象コレクションに含まれるボリュームの開始位置を設定します。 このボリューム数には制限があるため、一度のリクエスト&レスポンスでは欲しい情報を全て取得することはできません。 そのため、startIndexとmaxResultsを使ってページングする必要があります。 インデックスは0から始まります。

maxResults

レスポンスのコレクションに含まれるボリューム数を設定します。 このボリューム数には制限があるため、一度のリクエスト&レスポンスでは欲しい情報を全て取得することはできません。 そのため、startIndexとmaxResultsを使ってページングする必要があります。

  • デフォルトは10になっています。
  • 設定できる最大値は40です、これを超えた値を設定するとリクエストは失敗します。

orderBy

レスポンスのコレクションに含まれるボリュームの並び順を指定します。 下記の値が指定できます。

  • relevance: 検索結果を、関連性の高い順から低い順に返します。これが既定値
  • newest: 検索結果を、公開日の新しい順から古い順に返します。

projection

レスポンスのコレクションに含まれるボリュームの情報量の多少を指定します。

  • full: 全てのメタデータが含まれます。こちらがデフォルトになっています。
  • lite: 一部のメタデータ(saleInfo,volumeInfo)に制限します。

download

レスポンスのコレクションに含まれるボリュームをダウンロード可能かどうかで絞り込むことができます。

  • Currently, the only supported value is epub.
  • Purchase may be required for download access.

filter

レスポンスのコレクションに含まれるボリュームを下記の内容で絞り込むことができます。

  • filter=partial: レスポンスのコレクションに含まれるボリュームをテキストの一部がプレビュー可能なものに制限することができます。
  • filter=full: レスポンスのコレクションに含まれるボリュームをテキストの全量がプレビュー可能なものに制限することができます。
  • filter=free-ebooks: レスポンスのコレクションに含まれるボリュームを無料のGoogle eBooksに制限することができます。
  • filter=paid-ebooks: レスポンスのコレクションに含まれるボリュームを有料のGoogle eBooksに制限することができます。
  • filter=ebooks: レスポンスのコレクションに含まれるボリュームをGoogle eBooksに制限することができます。

langRestrict

レスポンスのコレクションに含まれるボリュームを言語で絞り込むことができます。"en "や "fr "のような2文字のISO-639-1コードを指定することで、検索結果を特定の言語に限定します。

printType

印刷タイプを指定します。 下記の値が指定できます。

  • all: すべてのボリューム・コンテンツ・タイプを返します。これが既定値です
  • books: 書籍のみを返します。
  • magazines: 雑誌のみを返します。

volumeId

操作したいボリュームのIDを指定します。 対象のボリュームを本棚へ追加または本棚から削除します。

Published 16 Dec 2020

Yona .Yona on Twitter