楽天ブックスソフトウェア検索APIは、楽天ブックスで販売されているソフトウェアの情報を取得することが可能なAPIです。デベロッパーはソフトウェアのタイトルや発売元などでの商品検索をはじめ、ジャンル別や在庫状態などでの絞り込み検索も可能となります。
（楽天ブックス総合検索APIよりも詳細な検索が可能となっています。）
リクエストURL（REST／JSON形式の場合）
http://api.rakuten.co.jp/rws/3.0/rest?[parameter]=[value]… http://api.rakuten.co.jp/rws/3.0/json?[parameter]=[value]…
※JSONP形式は、JSON形式で入力パラメーターにcallBackを指定することで出力されます。
フィールド名title, label, sortに対応する[value]はUTF-8でURLエンコードされている必要があります。（リクエストURL全体をエンコードするのではなく、[value]部分を個別にエンコードしてください。）
たとえば、「会計」というタイトルで検索し、対応OSを「Mac」で絞込み、結果を価格の安い順に並べたい（sort=+itemPrice）場合のリクエストURLは下記になります。（実際には改行せず1行につなげてリクエストしてください。）
http://api.rakuten.co.jp/rws/3.0/rest?
developerId=[YOUR_developerID]
&operation=BooksSoftwareSearch
&version=2011-12-01
&title=%E4%BC%9A%E8%A8%88
&os=Mac
&sort=%2BitemPrice
※短い時間の間に大量に、同一のリクエストURLへアクセスすると、一定時間利用できなくなる場合がございます。テストの際にはご注意ください。
入力パラメーター
楽天ブックスソフトウェア検索API（BooksSoftwareSearch) 入力パラメーター version:2011-12-01
| ID | 項目名 | パラメーター | 型(括弧内は最大バイト数) | 必須 | デフォルト | 備考 |
|---|---|---|---|---|---|---|
| 区分:共通パラメーター | ||||||
| 1 | デベロッパーID | developerId | String |  |
- | デベロッパーID（こちらで確認できるアプリケーションIDのことです） |
| 2 | アフィリエイトID | affiliateId | String | - | 指定無し | アフィリエイトID |
| 3 | 操作 | operation | String | |
- | 使用するAPIの操作名：BooksSoftwareSearch |
| 4 | コールバック関数名 | callBack | String | - | 指定無し | JSONPとして出力する際のコールバック関数名 （UTF-8でURLエンコードした文字列） 英数字、「.(ドット)」、「_(アンダーバー)」、「[(中括弧)」、「](中括弧)」のいずれか1文字以上 |
| 区分:サービス固有パラメーター | ||||||
| 1 | ソフトウェアタイトル | title | String | (*1) |
- | ソフトウェアのタイトルから検索 UTF-8でURLエンコードした文字列 複数キーワードから検索したい場合は、半角スペースで区切って下さい (*1)タイトル、対応OS、メーカー品番、発売元名、JANコード、楽天ブックスジャンルIDのいずれかが指定されていることが必須です |
| 2 | 対応OS | os | String | (*1) |
- |
対応OSから検索 UTF-8でURLエンコードした文字列 (*1)タイトル、対応OS、メーカー品番、発売元名、JANコード、楽天ブックスジャンルIDのいずれかが指定されていることが必須です |
| 3 | メーカー品番 | makerCode | String | (*1) |
- | メーカー品番から検索 UTF-8でURLエンコードした文字列 (*1)タイトル、対応OS、メーカー品番、発売元名、JANコード、楽天ブックスジャンルIDのいずれかが指定されていることが必須です |
| 4 | 発売元名 | label | String | (*1) |
- |
発売元名から検索 UTF-8でURLエンコードした文字列 複数キーワードから検索したい場合は、半角スペースで区切って下さい (*1)タイトル、対応OS、メーカー品番、発売元名、JANコード、楽天ブックスジャンルIDのいずれかが指定されていることが必須です |
| 5 | ソフトウェアのJANコード | jan | long | (*1) |
- | ソフトウェアに付与されているJANコードから検索 (*1)タイトル、対応OS、メーカー品番、発売元名、JANコード、楽天ブックスジャンルIDのいずれかが指定されていることが必須です |
| 6 | 楽天ブックスジャンルID | booksGenreId | String | (*1) |
004 | 楽天ブックスにおけるジャンルを特定するためのID （楽天市場のジャンルIDとは違うので注意してください） booksGenreId=004（ソフトウェア）に所属するジャンルのみが指定できます。 ジャンルのIDやジャンル名、ジャンルの親子関係を調べたい場合は、「楽天ブックスジャンル検索API(BooksGenreSearch)」をご利用ください。 (*1)タイトル、対応OS、メーカー品番、発売元名、JANコード、楽天ブックスジャンルIDのいずれかが指定されていることが必須です |
| 7 | バージョン | version | String | |
- | 2011-12-01 |
| 8 | 1ページあたりの取得件数 | hits | int | - | 30 | 1から30までの整数 |
| 9 | 取得ページ | page | int | - | 1 | 1から100までの整数 |
| 10 | 在庫状況 | availability | int(1) | - | 0 |
0：すべての商品 1：在庫あり 2：3～5日以内に発送予定 3：3～7日以内に発送予定 4：メーカー取り寄せ 5：予約受付中 6：メーカーに在庫確認 |
| 11 | 品切れ等購入不可商品表示フラグ | outOfStockFlag | int(1) | - | 0 |
0：品切れや販売終了など購入不可の商品は結果に表示させない 1：品切れや販売終了など購入不可の商品を結果に表示させる |
| 12 | ソート | sort | String | - | standard |
standard:標準 sales:売れている +releaseDate:発売日(古い) -releaseDate:発売日(新しい) +itemPrice:価格が安い -itemPrice:価格が高い reviewCount:レビューの件数が多い reviewAverage:レビューの評価(平均)が高い ※UTF-8でURLエンコードされている必要があります。 |
| 13 | 限定フラグ | limitedFlag | int(1) | - | 0 |
0:すべての商品 1:限定版商品のみ ※限定版商品には期間限定・数量限定・予約限定などの商品が含まれます。 |
| 14 | キャリア | carrier | int(1) | - | 0 | PC用の情報を返すのか、モバイル用の情報を返すのかを選択 PC: 0 mobile: 1 |
| 15 | ジャンルごとの商品数取得フラグ | genreInformationFlag | int(1) | - | 0 | 0 :ジャンルごとの商品数の情報を取得しない 1 :ジャンルごとの商品数の情報を取得する |
出力パラメーター
楽天ブックスソフトウェア検索API（BooksSoftwareSearch) 出力パラメーター version:2011-12-01
| ID | 大分類 | 分類 | 項目名 | パラメーター | 備考 |
|---|---|---|---|---|---|
| 区分:共通パラメーター | |||||
| 1 | ARG | - | User-Agent | Valueにはユーザのユーザエージェントが表示される | |
| 2 | - | developerId | ValueにはデベロッパーIDが表示される | ||
| 3 | - | affiliateId | ValueにはアフィリエイトIDが表示される | ||
| 4 | - | operation | Valueにはユーザの指定した操作名が表示される | ||
| 5 | - | version | Valueにはユーザの指定したバージョンが表示される | ||
| 6 | Status | - | Status | Success / NotFound / ServerError / ClientError / Maintenance のいずれか | |
| 7 | StatusMsg | - | StatusMsg | Statusに特化したメッセージを出力 | |
| 区分:サービス固有パラメーター | |||||
| 1 | 全体情報 | 検索数 | count | 検索結果の総商品数 | |
| 2 | ページ番号 | page | 現在のページ番号 | ||
| 3 | ページ内商品始追番 | first | 検索結果の何件目からか | ||
| 4 | ページ内商品終追番 | last | 検索結果の何件目までか | ||
| 5 | ヒット件数 | hits | 1度に返却する商品数 | ||
| 6 | キャリア情報 | carrier | PC=0 or mobile=1 | ||
| 7 | 総ページ数 | pageCount | 最大100 | ||
| 8 | 商品情報 （全体：<Items> ～ </Items> 、 個別商品：<Item> ～ </Item>） |
商品情報詳細 | ソフトウェアタイトル | title | |
| 9 | ソフトウェアタイトル カナ | titleKana | |||
| 10 | 対応OS | os | |||
| 11 | 発売元名 | label | |||
| 12 | JANコード | jan | |||
| 13 | メーカー品番 | makerCode | |||
| 14 | 商品説明文 | itemCaption | |||
| 15 | 発売日 【NEW】 | salesDate |
表示例：「YYYY年」「YYYY年MM月」「YYYY年MM月DD日」 ※発売日が確定されていない商品については、「上旬/中旬/下旬」や「頃」「以降」などが付加 |
||
| 16 | 税込み販売価格 | itemPrice | |||
| 17 | 定価 | listPrice | 商品の元の値段 | ||
| 18 | 割引率 | discountRate | 通常価格から何パーセント割引きされたか | ||
| 19 | 割引額 | discountPrice | 通常価格からいくら値引きされたか | ||
| 20 | 商品URL | itemUrl | |||
| 21 | アフィリエイトURL | affiliateUrl |
（入力パラメーターにアフィリエイトIDが含まれていた時のみ） ※carrierパラメーターの指定に関わらずPC/mobile両対応のURLを返却 |
||
| 22 | 商品画像 64x64URL | smallImageUrl | (画像サイズ 64px*64px) | ||
| 23 | 商品画像 128x128URL | mediumImageUrl | (画像サイズ 128px*128px) | ||
| 24 | 商品画像 200x200URL | largeImageUrl | (画像サイズ 200px*200px) | ||
| 25 | 在庫状況 | availability |
1：在庫あり 2：3～5日以内に発送予定 3：3～7日以内に発送予定 4：メーカー取り寄せ 5：予約受付中 6：メーカーに在庫確認 |
||
| 26 | 送料フラグ | postageFlag |
0:送料別 1:宅配送料無料 2:送料無料(コンビニ送料含む) ※キャンペーンなどで実際の送料の扱いは、出力内容と異なることがあります |
||
| 27 | 限定フラグ | limitedFlag |
0:通常商品 1:限定版商品 ※限定版商品には期間限定・数量限定・予約限定などの商品が含まれます。 |
||
| 28 | レビュー件数 | reviewCount | |||
| 29 | レビュー平均 | reviewAverage | |||
| 30 | ジャンル情報 | 楽天ブックスジャンルID | booksGenreId |
所属する最下位のジャンルIDを表示 該当商品が複数ジャンルに所属している場合は、「/」で区切ってそれぞれのジャンルIDを表示 |
|
| 31 |
ジャンルごとの商品数 （全体：<GenreInformation> ～ </GenreInformation> 、 個別ジャンル：<parent> ～ </parent> もしくは<current> ～ </current> もしくは<child> ～ </child>） |
親ジャンル | - | parent | 入力したジャンルIDの親ジャンル |
| 32 | 楽天ブックスジャンルID | booksGenreId | |||
| 33 | 楽天ブックスジャンル名 | booksGenreName | |||
| 34 | ジャンル階層 | genreLevel | |||
| 35 | 自ジャンル | - | current | ユーザの入力したジャンルID | |
| 36 | 楽天ブックスジャンルID | booksGenreId | |||
| 37 | 楽天ブックスジャンル名 | booksGenreName | |||
| 38 | ジャンルに紐づく商品数 | itemCount | |||
| 39 | ジャンル階層 | genreLevel | |||
| 40 | 子ジャンル | - | child |
ユーザの入力したジャンルIDの子ジャンル 複数の子ジャンルがある場合は<child> ～ </child>が複数生成される 入力が「booksGenreId=000」の時はgenreLevel=1のジャンルが<child> ～ </child>に表示される |
|
| 41 | 楽天ブックスジャンルID | booksGenreId | |||
| 42 | 楽天ブックスジャンル名 | booksGenreName | |||
| 43 | ジャンルに紐づく商品数 | itemCount | |||
| 44 | ジャンル階層 | genreLevel | |||
アフィリエイトに関して
デベロッパーは、楽天ブックスソフトウェア検索APIから取得した商品情報からアフィリエイトURLを作成することが可能です。リンク先にそのアフィリエイトURLを指定することで、楽天アフィリエイト経由の成果報酬を獲得することができます。 アフィリエイトURLの作り方は2通りあります。入力パラメーターcarrierでPCが指定された場合でもモバイルが指定された場合でも同様の方法でアフィリエイトURLを作成することができます。
（1） APIの入力パラメーターに「アフィリエイトID」を含める場合：
APIの出力に「アフィリエイトURL」が含まれます。
（2） デベロッパーが自ら、（APIから取得した）「商品URL」と「アフィリエイトID（β版）」から「アフィリエイトURL」を作成する場合：
「アフィリエイトURL」は以下のルールで生成可能です。ただし、「商品URL」の部分はURLエンコードされている必要があります。
http://hb.afl.rakuten.co.jp/hgc/[アフィリエイトID]/?pc=[商品URL（PC）]
もしくは、
http://hb.afl.rakuten.co.jp/hgc/[アフィリエイトID]/?m=[商品URL（モバイル）]
エラー
エラーが起こった際は、出力中の「共通パラメーター」のStatusに下表に記載されたいずれかが表示されます。
| Statusでの表示 | 内容 |
|---|---|
| NotFound | 検索結果が存在しない。 |
| ServerError | 楽天ウェブサービス側のエラー。 |
| ClientError | デベロッパーの入力に起因するエラー。 |
| Maintenance | メンテナンス。 |
過去のバージョン
本APIの過去のバージョンは下記からご覧いただけます。