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

[前回](https://qiita.com/stella0270/items/5727cd7726aa19ae850b)からの続きです。

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

本記事はGoogle Books APIの[開発者向けサイト](https://developers.google.com/books)を翻訳して簡潔にまとめたものです。

各操作の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: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: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: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: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: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: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: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固有のクエリパラメータのみ記載します。

標準クエリパラメータは[こちら](https://cloud.google.com/apis/docs/system-parameters)を参考にしてください。

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

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


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

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