Google Books APIの使い方~その４~

前回からの続きです。

今回は「リソースの操作とクエリパラメータ」についてです。

本記事はGoogle Books APIの開発者向けサイトを翻訳して簡潔にまとめたものです。

各操作のURIにあるkeyパラメータにはご自身が取得したAPIキーをセットしてください。
APIキーを取得していない場合でもkeyパラメータをつけずにリクエストを送れば、
認証が不要なリソース（パブリックデータ）は取得できます。

リソースの操作

ボリュームの検索

リクエスト
https://www.googleapis.com/books/v1/volumes?q=search+terms

qパラメータは必須です。
認証は不要ですが、認証付きでリクエストした場合は、
レスポンスのボリュームに購入状況などのユーザー固有情報が付加されます。

例）ダニエル・キーズの「アルジャーノンの花」を検索
https://www.googleapis.com/books/v1/volumes?q=flowers+inauthor:keyes&key=yourAPIKey

レスポンス
　条件に該当するボリュームのリスト

JSON

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"
    ],
    ...
  },
  "totalItems": 2
}

ボリュームの取得

リクエスト
https://www.googleapis.com/books/v1/volumes/{volumeId}
　{volumeId}に取得したいボリュームのVolume IDをセットします。

認証は不要ですが、認証付きでリクエストした場合は、
レスポンスのボリュームに購入状況などのユーザー固有情報が付加されます。

例）Volume IDが「zyTCAlFPjgYC」のボリュームを取得
https://www.googleapis.com/books/v1/volumes/zyTCAlFPjgYC?key=yourAPIKey

レスポンス
　ボリュームリソース

JSON

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"
 }
}

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

リクエスト
https://www.googleapis.com/books/v1/users/{userId}/bookshelves
　{userId}に取得したいユーザーのUser IDをセットします。

認証は不要です。

例）User IDが「1112223334445556677」のユーザの公開本棚リストを取得
https://www.googleapis.com/books/v1/users/1112223334445556677/bookshelves&key=yourAPIKey

レスポンス
　本棚リソースのリスト

JSON

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"
  },
  ...
 ]
}

ユーザーの公開本棚を取得

リクエスト
https://www.googleapis.com/books/v1/users/{userId}/bookshelves/{shelf}
　{userId}に取得したいユーザーのUser ID、{shelf}に取得したい本棚のBookshelf IDをセットします。

認証は不要です。

例）User IDが「1112223334445556677」のユーザのBookshelf IDが「3」の本棚を取得
https://www.googleapis.com/books/v1/users/1112223334445556677/bookshelves/3?key=yourAPIKey

レスポンス
　本棚リソース

JSON

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"
}

公開本棚にあるボリュームリストを取得

リクエスト
https://www.googleapis.com/books/v1/user/{userId}/bookshelves/{shelf}/volumes
　{userId}に取得したいユーザーのUser ID、{shelf}に取得したい本棚のBookshelf IDをセットします。

認証は不要です。

例）User IDが「1112223334445556677」のユーザのBookshelf IDが「3」の本棚のボリュームリストを取得
https://www.googleapis.com/books/v1/users/1112223334445556677/bookshelves/3/volumes?key=yourAPIKey

レスポンス
　ユーザーの本棚のボリュームリスト

JSON

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",
    ...
  },
 "totalItems": 2
}

マイライブラリの本棚リストを取得

リクエスト
https://www.googleapis.com/books/v1/mylibrary/bookshelves

ユーザ認証が必要になるため、Authorization HTTPヘッダーが必要です。

例）マイライブラリの本棚リストを取得
https://www.googleapis.com/books/v1/mylibrary/bookshelves?key=yourAPIKey
Authorization: /* auth token here */

レスポンス
　ユーザーのすべての本棚のリスト

JSON

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"
  }
 ]
}

マイライブラリの本棚のボリュームリストを取得

リクエスト
https://www.googleapis.com/books/v1/mylibrary/bookshelves/{shelf}/volumes
　{shelf}に取得したい本棚のBookshelf IDをセットします。

ユーザ認証が必要になるため、Authorization HTTPヘッダーが必要です。

例）Bookshelf IDが「7」の本棚のボリュームリストを取得
https://www.googleapis.com/books/v1/mylibrary/bookshelves/7/volumes?key=yourAPIKey
Authorization: /* auth token here */

レスポンス
　本棚のボリュームリスト

JSON

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",
    ...
  },
 "totalItems": 2
}

マイライブラリの本棚にボリュームを追加

リクエスト
https://www.googleapis.com/books/v1/mylibrary/bookshelves/{shelf}/addVolume
　{shelf}に取得したい本棚のBookshelf IDをセットします。

volumeIdパラメータは必須です。
ユーザ認証が必要になるため、Authorization HTTPヘッダーが必要です。

例）「お気に入り」の本棚にVolume IDが「NRWlitmahXkC」のボリュームを追加
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

レスポンス
　HTTPステータスコード：204(No Content)

マイライブラリの本棚からボリュームを削除

リクエスト
https://www.googleapis.com/books/v1/mylibrary/bookshelves/{shelf}/removeVolume
　{shelf}にBookshelf IDをセットします。

volumeIdパラメータは必須です。
ユーザ認証が必要になるため、Authorization HTTPヘッダーが必要です。

例）「お気に入り」の本棚にVolume IDが「NRWlitmahXkC」のボリュームを削除
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

レスポンス
　HTTPステータスコード：204(No Content)

マイライブラリの本棚からすべてのボリュームを削除

リクエスト
https://www.googleapis.com/books/v1/mylibrary/bookshelves/{shelf}/clearVolumes
　{shelf}に取得したい本棚のBookshelf IDをセットします。

ユーザ認証が必要になるため、Authorization HTTPヘッダーが必要です。

例）「お気に入り」の本棚のすべてのボリュームを削除
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

レスポンス
　HTTPステータスコード：204(No Content)

クエリパラメータ

標準クエリパラメータとAPI固有のクエリパラメータの２種類がありますが、
ここではAPI固有のクエリパラメータのみ記載します。

標準クエリパラメータはこちらを参考にしてください。

なお、パラメーター値はURLエンコードする必要があります。

パラメータ	説明	適用できる操作
download	ダウンロード形式の指定。「epub」のみ指定できます。	・ボリュームの検索
filter	ボリュームタイプの指定。 ・partial：テキストの少なくとも一部がプレビュー可能なボリュームのみ ・full：すべてのテキストが表示可能なボリュームのみ ・free-ebooks：無料のGoogle eブックのみ ・paid-ebooks：有料のGoogle eブックのみ ・ebooks：有料または無料のGoogle eBooksのみ。eBook以外の例としては、限定プレビューで販売されているが販売されていない出版社のコンテンツや雑誌があります。	・ボリュームの検索
langRestrict	言語の指定。「en」や「fr」などの2文字のISO-639-1コード。	・ボリュームの検索
maxResults	リクエストで取得する最大リソース数。デフォルトは10、最大値は40です。	・ボリュームの検索 ・本棚リストの取得 ・ボリュームリストの取得
orderBy	ボリューム検索結果の順序。 ・relevance：最も関連性の高い順（デフォルト） ・newest：最新の公開日から古い順	・ボリュームの検索
printType	本または雑誌の指定。 ・all：すべて（デフォルト） ・books：本のみ ・magazines：雑誌のみ	・ボリュームの検索
projection	ボリューム情報の指定。 ・full：すべてのボリュームメタデータ（デフォルト） ・lite：ボリュームとアクセスメタデータのサブジェクトのみ	・ボリュームの検索 ・ボリュームの取得 ・ボリュームリストの取得
q	検索用語を「+」またはスペースで区切って指定します。スペースで区切る場合は、スペースもURLエンコードが必要です。大文字/小文字の区別はされません。 完全に一致する語句を検索する場合 　q = "abcdef" 特定の用語に一致するエントリを除外する場合 　q = -term 特定のフィールドで検索をする場合は以下のキーワードをつけます。 intitle：タイトル inauthor：著者 inpublisher：出版社 subject：カテゴリ（Fictionなど） isbn：ISBN番号 lccn：米国議会図書館管理番号 oclc：Online Computer Library Center番号	・ボリュームの検索
startIndex	取得するリストの開始位置。０から始まります。	・ボリュームの検索 ・本棚リストの取得 ・ボリュームリストの取得
volumeId	操作するボリュームの指定。	・本棚へのボリュームの追加 ・本棚からボリュームを削除

クエリパラメータを使った検索例

・qを使って「夏目漱石」に関する書籍を取得
「%E5%A4%8F%E7%9B%AE%E6%BC%B1%E7%9F%B3」はURLエンコードされた「夏目漱石」です。

https://www.googleapis.com/books/v1/volumes?q=%E5%A4%8F%E7%9B%AE%E6%BC%B1%E7%9F%B3&key=yourAPIKey

・qを使って著者が「夏目漱石」の書籍を取得

https://www.googleapis.com/books/v1/volumes?q=inauthor:%E5%A4%8F%E7%9B%AE%E6%BC%B1%E7%9F%B3&key=yourAPIKey

・downloadを使ってダウンロード形式をepubに限定

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

・filterを使って無料の電子書籍に絞り込み

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

・printTypeを使って雑誌に限定

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

・projectionを使ってボリューム情報が制限された検索結果を取得

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

・orderByを使って発行日の昇順で取得

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

・maxResultsを使って取得ボリューム数を40に変更

https://www.googleapis.com/books/v1/volumes?q=flowers&maxResults=40&key=yourAPIKey

・startIndexを使って取得ボリューム数の開始位置を設定

https://www.googleapis.com/books/v1/volumes?q=flowers&startIndex=2&key=yourAPIKey

最後に

以上、「リソースの操作とクエリパラメータ」でした。

Google Books APIを使えば、簡単に書籍情報が取得できるのは良かったのですが、
著者名や出版社名が空欄になっているデータもあり、データの質があまり良くないかなという印象がありました。
今後改善されることを期待します。