書籍情報をAPIで検索してみよう【楽天ブックス系API】

連載第12回の目的

連載第12回と第13回では、Excel VBAにおける「楽天ウェブサービス」の活用について紹介します。楽天グループ株式会社の提供するこのWebサービスは、同社の運営するさまざまなサービスの情報を外部から取得できる機能を無償で提供します。今回はこれに含まれる「楽天ブックス系API」を使用して、キーワードを自由に指定して書籍情報を検索して一覧表にするExcelワークシートを作成します（図1）。
今回は、「楽天ウェブサービス」「楽天ブックス系API」の概要を紹介し、アプリケーションIDの取得、API呼び出しのテストまでを取り上げます。

• 

  図1：完成サンプル

▼完成サンプルのExcelファイル
https://github.com/wateryinhare62/mynavi_excelvba_webservice

なお、本連載では動作確認をWindows 10 Pro（64bit）、Microsoft 365（Excel 16.0、VBA 7.1）で行っています。旧バージョンや単体のExcelで試す場合にはご注意ください。

楽天ブックス系APIについて

楽天ブックス系APIは、楽天グループ株式会社が提供するWebサービスのひとつです。同社のWebサービスは、「楽天ウェブサービス」として楽天市場系APIをはじめとして7種類のAPI群から構成されますが、このうち楽天ブックス系APIは書籍、雑誌、メディア、ゲームなどをさまざまな形で検索できる機能を提供します。検索の対象は、同社の「楽天ブックス」となります。

楽天ウェブサービス
・楽天市場系API…楽天市場を対象としたAPI
・楽天トラベル系API…楽天トラベルを対象としたAPI
・楽天ブックマーク系API…楽天ブックマークを対象としたAPI
・楽天レシピ系API…楽天レシピを対象としたAPI
・楽天Kobo系API…楽天Kobo（電子書籍）を対象としたAPI
・楽天GORA系API…楽天GORA（ゴルフ場予約）を対象としたAPI
・楽天ブックス系API…楽天ブックスを対象としたAPI
　　楽天ブックス総合検索API…楽天ブックスの商品を総合的に検索
　　楽天ブックス書籍検索API…楽天ブックスの商品を書籍を対象に検索
　　楽天ブックスCD検索API…楽天ブックスの商品を音楽メディアを対象に検索
　　楽天ブックスCD/Blu-ray検索API…楽天ブックスの商品を映像メディアを対象に検索
　　楽天ブックス洋書検索API…楽天ブックスの商品を洋書を対象に検索
　　楽天ブックス雑誌検索API…楽天ブックスの商品を雑誌を対象に検索
　　楽天ブックスゲーム検索API…楽天ブックスの商品をゲームを対象に検索
　　楽天ブックスソフトウェア検索API…楽天ブックスの商品をソフトウェアを対象に検索
　　楽天ブックスジャンル検索API…楽天ブックスの商品のジャンル分け情報を検索

今回は書籍検索を行いたいので、その機能を持つ「楽天ブックス書籍検索API」を使っていくことになります。また、書籍をジャンル指定して検索したいので、ジャンル分け情報を取得できる「楽天ブックスジャンル検索API」も使っていきます。楽天ブックス系APIの各APIは基本的な使い方が共通なので、書籍ではなくメディアを検索したいという場合にも、サンプルが参考になると思います。
APIは、無償で利用できます。ただし、利用には一定の約束ごとと制限がありますので、事前に以下URLにある「ご利用ガイド」に目を通しておいてください（初期ページが英語であることがあるので、その場合には日本語に切り替えてください）。基本的には、楽天IDが必要、アプリケーションの登録が必要、クレジット表記が必要といったことなどです。これらについては、必要なときに都度触れていきます。

▼楽天ウェブサービス(RAKUTEN WEBSERVICE)
https://webservice.rakuten.co.jp/

楽天ブックス系APIを使う準備

楽天ブックス系APIの利用には、楽天IDとアプリケーションIDが必要です。まずはこれらを取得しておきます。

楽天IDの取得

楽天IDを持っていない方は、以下のページの［楽天会員登録(無料)］から登録（無料）を行ってください。登録には、メールアドレスが必要です。以降は、ログインしての作業になります。

▼楽天市場
https://www.rakuten.co.jp/

アプリケーションの登録（アプリケーションIDの取得）

アプリケーションを登録すると、アプリIDが発行されます。このIDは今回作成するアプリケーションにおいて、各自がプログラム中に設定する必要があります。アプリケーションの登録は、「楽天ウェブサービス」のトップ画面にある［アプリID発行］から行います。なお、アプリケーションの登録は楽天ブックス系APIに限ったものではなく、その他のAPIも含めた楽天ウェブサービス全体に適用されます。
［アプリID発行］をクリックすると、楽天IDを楽天ウェブサービスに連携する確認画面となります（図2）。「利用規約」と「プライバシーポリシー」を一読の上同意できれば、［続ける］をクリックします。これで先に進むことができます。

• 

  図2：楽天IDを楽天ウェブサービスに連携

アプリケーション情報の入力ページが表示されます（図3）。表1の要領で、必要な項目を入力してください。OAuth認可方式を必要とするAPIの利用に必要な詳細情報など、今回において入力/選択の必要のない項目は省略しています。

• 

  図3：新規アプリ登録

表1：アプリケーション登録で入力する内容

項目	内容
アプリ名	アプリケーションの名称。30文字以内で好きな名称を指定。ここでは「楽天ブックス活用アプリ」とした
アプリURL	アプリケーションのURL。255文字以内でアプリケーションのURLを指定。今回作成するアプリケーションはWebアプリケーションではないので、ホームページやブログのURLを記入
楽天ウェブサービス・楽天APIを知ったきっかけは何ですか？	一つ以上、どれかにチェックを入れる
認証	画像に表示される英数字を入力

入力したら、最後の項目の「規約に同意して新規アプリを作成」をクリックします。「創作成功」と薄いブルーの地に表示されれば登録は成功です。「403 Method Not Found」などのエラーページとなる場合、必須項目が埋められていない可能性があります。
ページに表示されるアプリID/デベロッパーIDを控えておいてください。「楽天ウェブサービス」のトップ画面にある［アプリ情報の確認］からも確認できます。このアプリIDは、API呼び出しの際に必要となります。application secret、アフィリエイトIDは今回は不要です。

• 

  図4：創作成功

これで、アプリケーションの登録ができました。

APIの呼び出しをテストする

アプリケーションIDの取得ができたので、APIの呼び出しを始めることができます。スクリプトを書く前に、APIが正しく呼び出せるかテストして、APIについての理解も深めておきましょう。
今回使用する楽天ブックス系APIはGETメソッドでアクセスするので、API呼び出しのテストはWebブラウザで実行できます。なお、WebブラウザがJSONデータを見やすく表示してくれるようになっていると便利です。Google Chromeでは、第3回で紹介した拡張機能「JSON Viewer」を利用できます。 今回のサンプルは、①書籍のジャンル分け情報をあらかじめ取得しておき、②書名、著者名、出版社名からジャンルや並び替え順序を指定して検索し、③検索結果が複数ページにわたる場合にはページの切り替えもできるようにしていきます。この①②で使用するAPIをテストします。返されるJSONデータの理解はスクリプトの読みこなしに必要なので、基本的な構成を理解しておいてください。

ジャンル分け情報を検索する―楽天ブックスジャンル検索API

楽天ブックスジャンル検索APIは、書籍などの検索時に指定できるジャンル分け情報を検索するAPIです。楽天ブックスジャンル検索APIについては、下記にドキュメントがありますので、全容を知りたい場合には参照してください。

▼楽天ウェブサービス: 楽天ブックスジャンル検索API(version:2012-11-28) | API一覧
https://webservice.rakuten.co.jp/documentation/books-genre-search

リクエストURL（エンドポイント）は以下のようになります。検索に必要な情報はクエリパラメータで与えます。

（GET）https://app.rakuten.co.jp/services/api/BooksGenre/Search/20121128?[parameter]=[value]…

パラメータに、検索したいジャンルの情報などを指定していきます。他のAPIとも共通となるものを表2に、楽天ブックスジャンル検索API独自のものを表3に挙げます（※は必須パラメータ）。

表2：楽天ブックス系APIの共通パラメータ

パラメータ	概要
applicationId※	アプリケーションID
affiliateId	アフィリエイトID（デフォルトはなし）
format	レスポンスのフォーマット（jsonまたはxml。デフォルトはjson）
callback	レスポンスをJSONPとするときのコールバック関数（デフォルトはなし）
elements	レスポンスに含めたい要素をカンマ区切りで列挙（デフォルトはすべて）
formatVersion	レスポンスのフォーマットのバージョン（1または2。デフォルトは1）

表3：楽天ブックスジャンル検索APIのパラメータ

パラメータ	概要
booksGenreId※	ジャンルID（3桁の数字の繰り返し。ルートは000）
genrePath	レスポンスに親階層より上を含めるか（0で含めない、1で含める。デフォルトは0）

共通パラメータで必須なのはアプリケーションID（applicationId）のみですが、elementsやformatVersionを指定することで、レスポンスを絞り込んだり、形式を切り替えたりすることができます。
また、ジャンル分け情報は階層構造をなしており、ルート（000）をbooksGenreIdに指定すると、ルート直下のジャンル分け情報を検索することができます。さらに、そのレスポンスのいずれかをbooksGenreIdに指定すると、その下の階層が検索できます。ちなみに書籍のジャンルIDは001となっているので、これをbooksGenreIdに指定すると書籍の細かなジャンル分け情報が得られます。
ここでは、formatVersionに「2」、booksGenreIdに「001」を指定してAPIを呼び出してみます。アプリケーションIDの指定を忘れないでください（以下では途中から省略しています）。

https://app.rakuten.co.jp/services/api/BooksGenre/Search/20121128?booksGenreId=001&formatVersion=2&applicationId=1007…

このURLをWebブラウザのアドレス欄に入力して呼び出すと、問題なければ以下のようなレスポンスが返ってきます。レスポンスで返ってきたJSONデータの構造を見てみましょう。その概略をリスト1に示します。

［リスト1］ジャンル検索結果のJSONデータの構造

{
  "children": [ … 子階層の配列
    { … 個々の子階層のデータ
      "booksGenreId": "001001", … ジャンルID
      "booksGenreName": "漫画（コミック）", … ジャンル名称
      "genreLevel": 2 … ジャンルの階層
    },
    {
      "booksGenreId": "001002",
      "booksGenreName": "語学・学習参考書",
      "genreLevel": 2
    },
    …
  ],
  "current": { … 基準の階層
    "booksGenreId": "001",
    "booksGenreName": "本",
    "genreLevel": 1
  },
  "parents": [ … 親階層の配列（この場合は空）

  ]
}

データが正しく取得できている場合、childrenというキーを含んだJSONが返されます。正常終了した場合の結果は、基本的に配列childrenにまとめられます。なお、formatVersionを省略するか「1」を指定した場合、childrenの各要素はchildというキーの下に配置されます。つまり、children[]⇒child⇒booksGenreIdというようになります。しかし、各要素はchildキーのみを含むだけになり冗長なので、これを省略できるformatVersion=2を指定しています。以降のサンプルはすべて、この指定に基づきますので注意してください。
エラーが発生しているときには、エラーを表すステータスコード（400など）とともに、errorキーとerror_descriptionキーのみからなるJSONが返されます。ですので、エラーが発生しているかはステータスコードのチェックと、これらのキーの存在で判定します。今回のサンプルでは、errorキーの有無で判定しています。

書籍情報を検索する―楽天ブックス書籍検索API

楽天ブックス書籍検索APIは、書籍を書名や著者名といったキーワードなどを用いて検索するAPIです。楽天ブックス書籍検索APIについては、下記にドキュメントがありますので、全容を知りたい場合には参照してください。

▼楽天ウェブサービス: 楽天ブックス書籍検索API(version:2017-04-04) | API一覧
https://webservice.rakuten.co.jp/documentation/books-book-search

リクエストURL（エンドポイント）は以下のようになります。検索に必要な情報はクエリパラメータで与えます。

（GET）https://app.rakuten.co.jp/services/api/BooksBook/Search/20170404?[parameter]=[value]…

パラメータに、検索したいジャンルの情報などを指定していきます。主なパラメータを表4に挙げます（※は必須パラメータ）。

▲表4：楽天ブックス書籍検索APIのパラメータ

パラメータ	概要
title※	書籍タイトル（要URLエンコード）
author※	著者名（要URLエンコード）
publisherName※	出版社名（要URLエンコード）
size※	書籍サイズ（0：全て、1：単行本、2：文庫、3：新書、4：全集・双書、5：事・辞典、6：図鑑、7：絵本、8：カセット・CDなど、9：コミック、10：ムックその他。デフォルトは0）
isbn※	ISBNコード
booksGenreId※	ジャンルID（デフォルトは001）
hits	1ページあたりの件数（デフォルトは30）
page	取得対象ページ（デフォルトは1）
availability	在庫状況（0：すべての商品、1：在庫あり、2：通常3～7日程度で発送、3：通常3～9日程度で発送、4：メーカー取り寄せ、5：予約受付中、6：メーカーに在庫確認。デフォルトは0）
outOfStockFlag	購入できない商品の表示（0：しない、1:する。デフォルトは0）
chirayomiFlag	チラ読み対象商品のみの表示（0：しない、1:する。デフォルトは0）
sort	並び換えの指定（standard：標準、sales：売れている順、+releaseDate：発売日の古い順、-releaseDate：発売日の新しい順、+itemPrice：価格が安い順、-itemPrice：価格が高い順、reviewCount：レビューの件数が多い順、reviewAverage：レビューの平均評価が高い順。デフォルトはstandard、要URLエンコード）
limitedFlag	限定版のみの表示（0：全商品を表示、1：限定版のみ表示。デフォルトは0）
carrier	モバイル用の情報を返すか（0：PC用の情報、1：モバイル用の情報。デフォルトは0）
genreInformationFlag	ジャンルごとの商品数の情報を取得するか（0：しない、1：する。デフォルトは0）

※の付いたパラメータは必須ですが、これらのどれかが最低1個指定されていれば問題ありません。また、書名など日本語を含む可能性のあるものは、すべてURLエンコードが必要なことに注意してください。意外と忘れがちですがsortも記号を含むのでURLエンコードが必要です。 ここでは、タイトル（title）が「太陽」を含み、ジャンル（booksGenreId）は「小説」（001004）、ソート順（sort）は価格の昇順（+ItemPrice)を指定してAPIを呼び出してみます。記述の通り、日本語や記号を含む可能性のあるパラメータはURLエンコードしておく必要があります。アプリケーションIDの指定を忘れないでください（以下では途中から省略しています）。

https://app.rakuten.co.jp/services/api/BooksBook/Search/20170404?title=%E5%A4%AA%E9%99%BD&booksGenreId=001004&sort=%2BitemPrice&formatVersion=2&applicationId=1007…

このURLをWebブラウザのアドレス欄に入力して呼び出すと、問題なければ以下のようなレスポンスが返ってきます。レスポンスで返ってきたJSONデータの構造を見てみましょう。その概略をリスト2に示します。

［リスト2］書籍検索結果のJSONデータの構造

{
  "GenreInformation": [ … ジャンルの情報（この場合は空）

  ],
  "Items": [ … (1)一致項目のリスト（配列）
    {
      "affiliateUrl": "", … （あれば）アフィリエイトURL
      "author": "宮木あや子", … (3)著者名
      "authorKana": "ミヤギ,アヤコ", … (3)著者名カナ
      "availability": "1", … 在庫のある商品か
      "booksGenreId": "001004008007/001019001", … ジャンルID
      "chirayomiUrl": "", … 「チラ読み」のURL
      "contents": "", … 目次情報
      "discountPrice": 0, … 割引価格
      "discountRate": 0, … 割引率
      "isbn": "9784087450408", … (4)ISBNコード
      "itemCaption": "一般人には存在を知られず、…幻想的な物語。", … (5)説明
      "itemPrice": 550, … (6)税込み価格
      "itemUrl": "https://books.rakuten.co.jp/rb/12192333/", … 商品URL
      "largeImageUrl": "https://thumbnail.image.rakuten.co.jp/@0_mall/book/cabinet/0408/9784087450408.jpg?_ex=200x200", … イメージURL（大）
      "limitedFlag": 0, … 限定品か
      "listPrice": 0,
      "mediumImageUrl": "https://thumbnail.image.rakuten.co.jp/@0_mall/book/cabinet/0408/9784087450408.jpg?_ex=120x120", … イメージURL（中）
      "postageFlag": 2,
      "publisherName": "集英社", … (7)出版社
      "reviewAverage": "3.67", … 平均評価
      "reviewCount": 16, … レビュー数
      "salesDate": "2013年02月", … (8)発売日
      "seriesName": "集英社文庫", … シリーズ名
      "seriesNameKana": "シュウエイシャ ブンコ", … シリーズ名カナ
      "size": "文庫", … (9)サイズ
      "smallImageUrl": "https://thumbnail.image.rakuten.co.jp/@0_mall/book/cabinet/0408/9784087450408.jpg?_ex=64x64", … イメージURL（小）
      "subTitle": "", … サブタイトル
      "subTitleKana": "", … サブタイトルカナ
      "title": "太陽の庭", … (10)タイトル（書名）
      "titleKana": "タイヨウ ノ ニワ" … (10)タイトル（書名）カナ
    },
    …
  ],
  "carrier": 0, … PC用の情報である
  "count": 100, … 検索で合致した全件数
  "first": 1, … ページに含まれる範囲の先頭
  "hits": 30, … ページに含まれる件数
  "last": 30, … ページに含まれる範囲の末尾
  "page": 1, … 現在のページ
  "pageCount": 4 … 総ページ数
}

エラーが発生しているときにはerrorキーがあることは、ジャンル検索と同じです。
トップレベルにはGenreInformationをはじめとしたいくつかのキーがありますが、検索結果として得られる商品はすべて配列Itemsに格納されています（1）。そして、配列の各要素に個別の書籍情報が格納されています（2）。
書籍の情報として一般的なのは、（3）の著者名、（4）のISBNコード、（5）の説明文、（6）の価格、（7）の出版社、（8）の発売日、（9）のサイズ、そして（10）の書名（タイトル）でしょう。これらがあまねく網羅されていることで、書籍検索で必要な情報はほぼ取得できると言えます。

まとめ

今回は、楽天グループ提供の楽天ウェブサービスの概要と、そのひとつである楽天ブックス系APIの呼び出し方法やJSONデータの見方について紹介しました。次回は、今回の続きとして、ワークシートの準備とVBAのスクリプトを紹介していきます。

WINGSプロジェクト 山内直著/山田祥寛監修
＜WINGSプロジェクトについて＞テクニカル執筆プロジェクト(代表山田祥寛)。海外記事の翻訳から、主にWeb開発分野の書籍・雑誌/Web記事の執筆、講演等を幅広く手がける。一緒に執筆をできる有志を募集中