Home      API一覧     楽天ブックス総合検索API

楽天ブックス総合検索APIは、楽天ブックスの商品情報を取得することが可能なAPIです。デベロッパーはキーワードでの商品検索をはじめ、ジャンル別や在庫状態などでの絞り込み検索も可能となります。

リクエスト


https://app.rakuten.co.jp/services/api/BooksTotal/Search/20170404?[parameter]=[value]…

※JSONP形式は、JSON形式で入力パラメーターにcallBackを指定することで出力されます。

フィールド名keyword, sortに対応する[value]はUTF-8でURLエンコードされている必要があります。
(リクエストURL全体をエンコードするのではなく、[value]部分を個別にエンコードしてください。)
たとえば、「本」という検索キーワードで検索し、「予約」というキーワードを除外し、結果を価格の安い順に並べたい(sort=+itemPrice)場合のリクエストURLは下記になります。(実際には改行せず1行につなげてリクエストしてください。)

https://app.rakuten.co.jp/services/api/BooksTotal/Search/20170404?
        applicationId=[アプリID]
        &keyword=%E6%9C%AC
        &NGKeyword=%E4%BA%88%E7%B4%84
        &sort=%2BitemPrice

※短い時間の間に大量に、同一のリクエストURLへアクセスすると、一定時間利用できなくなる場合がございます。テストの際にはご注意ください。

入力パラメーター


楽天ブックス総合検索API 入力パラメーター version:2017-04-04

ID 項目名 パラメーター 型(括弧内は最大バイト数) 必須 デフォルト 備考
区分:共通パラメーター
1 アプリID applicationId String 必須 - こちらで確認できます
2 アフィリエイトID affiliateId String - 指定無し こちらで確認できます
3 レスポンス形式 format String - json json か xml を選択することができます。
json を選択した場合、 callback パラメーター指定により jsonp 形式にすることもできます。
4 コールバック関数名 callback String - 指定無し JSONPとして出力する際のコールバック関数名
(UTF-8でURLエンコードした文字列)
英数字、「.(ドット)」、「_(アンダーバー)」、「[(中括弧)」、「](中括弧)」のいずれか1文字以上
5 出力パラメーター指定 elements String - ALL カンマ区切りで、必要な出力パラメータを指定した場合、
指定された出力パラメータのみを返却します。
(例)elements=reviewCount,reviewAverage
6 出力フォーマットバージョン formatVersion int - 1

出力フォーマットのバージョン指定です。

2 を指定すると、JSONの出力方法が改善され以下のようになります。

formatVersion=1 の場合:
配列データに関して、以下の様にデータが返ります。
したがって、最初の itemName にアクセスするためにitems[0].item.itemNameとたどる必要があります。

{"items": [
    {"item": {
        "itemName": "a",
        "itemPrice": 10
    }},
    {"item": {
        "itemName": "b",
        "itemPrice": 20
    }}
]}

formatVersion=2 の場合:
下記のように、配列中の重複するオブジェクトが省略されます。
最初の itemName にアクセスするためにitems[0].itemNameでアクセスできます。

{"items": [
    {
        "itemName": "a",
        "itemPrice": 10
    },
    {
        "itemName": "b",
        "itemPrice": 20
    }
]}
区分:サービス固有パラメーター
1 検索キーワード keyword String Affiliate対応あり
(*1)
-

UTF-8でURLエンコードした文字列

  • 検索キーワード全体は半角で128文字以内で指定する必要があります。
  • 検索キーワードは半角スペースで区切ることができ、デフォルトではAND条件 (すべてのキーワードが含まれるものを検索 ) になります。 もし、OR条件 (いずれかのキーワードが含まれるものを検索) を利用したい場合は、 orFlag1 に設定してください。
  • 各検索キーワードは半角2文字 もしくは 全角1文字 以上で指定する必要があります。
  • また例外として、各検索キーワードがひらがな・カタカナ・記号の場合は2文字以上で指定する必要があります。

(*1)検索キーワード、楽天ブックスジャンルID、ISBNコード/JANコードのいずれかが指定されていることが必須です。

2 楽天ブックスジャンルID booksGenreId String Affiliate対応あり
(*1)
000 楽天ブックスにおけるジャンルを特定するためのID
(楽天市場のジャンルIDとは違うので注意してください)
ジャンルのIDやジャンル名、ジャンルの親子関係を調べたい場合は、「楽天ブックスジャンル検索API(BooksGenre/Search)」をご利用ください。
(*1)検索キーワード、楽天ブックスジャンルID、ISBNコード/JANコードのいずれかが指定されていることが必須です。
3 ISBNコード/JANコード isbnjan String Affiliate対応あり
(*1)
(*2)
- ※「-」ハイフンなどを取り除いた数字のみ13桁でリクエストしてください
(*1)検索キーワード、楽天ブックスジャンルID、ISBNコード/JANコードのいずれかが指定されていることが必須です。
(*2)ISBNコード/JANコードの入力があった場合、検索キーワードと楽天ブックスジャンルIDへの入力は無効となります
4 1ページあたりの取得件数 hits int - 30 1から30までの整数
5 取得ページ page int - 1 1から100までの整数
6 在庫状況 availability int(1) - 0 0:すべての商品
1:在庫あり
2:通常3~7日程度で発送
3:通常3~9日程度で発送
4:メーカー取り寄せ
5:予約受付中
6:メーカーに在庫確認
7 品切れ等購入不可商品表示フラグ outOfStockFlag int(1) - 0 0:品切れや販売終了など購入不可の商品は結果に表示させない
1:品切れや販売終了など購入不可の商品を結果に表示させる
8 チラよみフラグ chirayomiFlag int(1) - 0 0:すべての商品
1:チラよみ対象商品で絞り込む
9 ソート sort String - standard standard:標準
sales:売れている
+releaseDate:発売日(古い)
-releaseDate:発売日(新しい)
+itemPrice:価格が安い
-itemPrice:価格が高い
reviewCount:レビューの件数が多い
reviewAverage:レビューの評価(平均)が高い
※UTF-8でURLエンコードされている必要があります。
10 限定フラグ limitedFlag int(1) - 0 0:すべての商品
1:限定版商品のみ
※限定版商品には期間限定・数量限定・予約限定などの商品が含まれます。
11 検索フィールド field int(1) - 1 0:検索対象が広い(同じ検索キーワードでも多くの検索結果が得られる)
1:検索対象範囲が限定される(同じ検索キーワードでも少ない検索結果が得られる)
12 キャリア carrier int(1) - 0 PC用の情報を返すのか、モバイル用の情報を返すのかを選択
PC: 0
mobile: 1
13 OR検索フラグ orFlag int(1) - 0 複数キーワードが設定された場合に、AND検索、OR検索のいずれかが選択可能。
0:AND検索
1:OR検索
※ただし、(A and B) or Cといった複雑な検索条件設定は指定不可。
14 除外キーワード(*3) NGKeyword String - 指定無し

検索結果から除外したいキーワード

UTF-8でURLエンコードした文字列

形式については keyword と同様

(*3)使用するには検索キーワードの入力が必須

15 ジャンルごとの商品数取得フラグ【NEW】 genreInformationFlag int(1) - 0 0 :ジャンルごとの商品数の情報を取得しない
1 :ジャンルごとの商品数の情報を取得する

出力パラメーター


楽天ブックス総合検索API 出力パラメーター version:2017-04-04

ID 大分類 分類 項目名 パラメーター 備考
区分:サービス固有パラメーター
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 著者名 author 商品が書籍や洋書の場合に出力
10 アーティスト名 artistName 商品がCDやDVD/Blu-rayの場合で、アーティスト名/作曲者名/出演者名/監督名等を出力
11 出版社名 publisherName 商品が書籍や洋書、雑誌の場合に出力
12 発売元名 label 商品がCDやDVD/Blu-ray、ゲーム、ソフトウェアの場合に出力
13 ISBNコード isbn  
14 JANコード jan  
15 対応機種 hardware 商品がゲームの場合に出力
16 対応OS os 商品がソフトウェアの場合に出力
17 商品説明文 itemCaption  
18 発売日/出版年度 salesDate 表示例:「YYYY年」「YYYY年MM月」「YYYY年MM月DD日」
※発売日が確定されていない商品については、「上旬/中旬/下旬」や「頃」「以降」などが付加
19 税込み販売価格 itemPrice  
20 定価 listPrice ※楽天ブックスの仕様変更により、2013/11/28から一律で0を返却しております。
こちらの値のご利用をお控えいただけますようお願いいたします。
21 割引率 discountRate ※楽天ブックスの仕様変更により、2013/11/28から一律で0を返却しております。
こちらの値のご利用をお控えいただけますようお願いいたします。
22 割引額 discountPrice ※楽天ブックスの仕様変更により、2013/11/28から一律で0を返却しております。
こちらの値のご利用をお控えいただけますようお願いいたします。
23 商品URL itemUrl httpsではじまる商品ごとのURL
24 アフィリエイトURL affiliateUrl (入力パラメーターにアフィリエイトIDが含まれていた時のみ)
※carrierパラメーターの指定に関わらずPC/mobile両対応のhttpsではじまるURLを返却
25 商品画像 64x64URL smallImageUrl httpsではじまる商品画像(64x64ピクセル)のURL
26 商品画像 128x128URL mediumImageUrl httpsではじまる商品画像(128x128ピクセル)のURL
27 商品画像 200x200URL largeImageUrl httpsではじまる商品画像(200x200ピクセル)のURL
28 チラよみURL chirayomiUrl チラよみ対象商品の場合は表示,httpsではじまるチラよみ対象商品URL
29 在庫状況 availability 1:在庫あり
2:通常3~7日程度で発送
3:通常3~9日程度で発送
4:メーカー取り寄せ
5:予約受付中
6:メーカーに在庫確認
30 送料フラグ postageFlag 0:送料別
1:宅配送料無料
2:送料無料(コンビニ送料含む)
※キャンペーンなどで実際の送料の扱いは、出力内容と異なることがあります
31 限定フラグ limitedFlag 0:通常商品
1:限定版商品
※限定版商品には期間限定・数量限定・予約限定などの商品が含まれます。
32 レビュー件数 reviewCount  
33 レビュー平均 reviewAverage  
34 ジャンル情報 楽天ブックスジャンルID booksGenreId 所属する最下位のジャンルIDを表示
該当商品が複数ジャンルに所属している場合は、「/」で区切ってそれぞれのジャンルIDを表示
35 ジャンルごとの商品数
(全体:<GenreInformation>
~ </GenreInformation> 、
個別ジャンル:<parent> ~ </parent>
もしくは<current> ~ </current>
もしくは<children> ~ </children>)【NEW】
親ジャンル - parent 入力したジャンルIDの親ジャンル
36 楽天ブックスジャンルID booksGenreId  
37 楽天ブックスジャンル名 booksGenreName  
38 ジャンル階層 genreLevel  
39 自ジャンル - current ユーザの入力したジャンルID
40 楽天ブックスジャンルID booksGenreId  
41 楽天ブックスジャンル名 booksGenreName  
42 ジャンルに紐づく商品数 itemCount  
43 ジャンル階層 genreLevel  
44 子ジャンル - children ユーザの入力したジャンルIDの子ジャンル
複数の子ジャンルがある場合は<children> ~ </children>が複数生成される
入力が「booksGenreId=000」の時はgenreLevel=1のジャンルが<children> ~ </children>に表示される
45 楽天ブックスジャンルID booksGenreId  
46 楽天ブックスジャンル名 booksGenreName  
47 ジャンルに紐づく商品数 itemCount  
48 ジャンル階層 genreLevel  

アフィリエイトに関して


デベロッパーは、楽天ブックス総合検索APIから取得した商品情報からアフィリエイトURLを作成することが可能です。リンク先にそのアフィリエイトURLを指定することで、楽天アフィリエイト経由の成果報酬を獲得することができます。 アフィリエイトURLの作り方は2通りあります。入力パラメーターcarrierでPCが指定された場合でもモバイルが指定された場合でも同様の方法でアフィリエイトURLを作成することができます。
(1) APIの入力パラメーターに「アフィリエイトID」を含める場合: APIの出力に「アフィリエイトURL」が含まれます。

(2) デベロッパーが自ら、(APIから取得した)「商品URL」と「アフィリエイトID(β版)」から「アフィリエイトURL」を作成する場合: 「アフィリエイトURL」は以下のルールで生成可能です。ただし、「商品URL」の部分はURLエンコードされている必要があります。

https://hb.afl.rakuten.co.jp/hgc/[アフィリエイトID]/?pc=[商品URL(PC)]&m=[商品URL(モバイル)]

エラー

エラー内容はHTTPステータスコードとレスポンスボディから判断できます。

HTTPステータスコード 意味 レスポンスボディ例 (JSON)
400 パラメーターエラー (必須パラメータ不足)

applicationId を指定しなかった場合

{
    "error": "wrong_parameter",
    "error_description": "specify valid applicationId"
}

keyword が正しい値でなかった時。(半角1文字のみ指定など)

{
    "error": "wrong_parameter",
    "error_description": "keyword parameter is not valid"
}
404 対象のデータが存在しなかった場合
{
    "error": "not_found",
    "error_description": "not found"
}
429 リクエスト過多 (各ユーザ制限値超過)

APIリクエスト数が上限に達した場合のエラーです。しばらく時間を空けてから、ご利用ください。

{
    "error": "too_many_requests",
    "error_description": "number of allowed requests has been exceeded for this API. please try again soon."
}
500 楽天ウェブサービス内のエラー

システムエラー。長時間続くようであれば、こちらよりごお問い合わせください。

{
    "error": "system_error",
    "error_description": "api logic error"
}
503 メンテナンス・リクエスト過多 (全ユーザ制限値超過)

メンテナンス (XXX/XXX にはAPI名が入る)

{
    "error": "service_unavailable",
    "error_description": "XXX/XXX is under maintenance"
}

レスポンスボディの形式は format に従います。

format エラー出力例
json
{
    "error": "wrong_parameter",
    "error_description": "page must be a number"
}
xml
<?xml version="1.0" encoding="UTF-8"?>
<root>
    <error>wrong_parameter</error>
    <error_description>page must be a number</error_description>
</root>