This website will be under maintenance from Friday August 23, 2:00 PM to Monday August 26, 2.00 PM JST. Only this website is impacted. The Rakuten APIs will continue to work. Sorry for the inconvenience. For more details please check our SNS announcement.
Home      API一覧     楽天Kobo電子書籍検索API

楽天Kobo電子書籍検索APIは、楽天Koboで販売されている電子書籍の情報を取得することが可能なAPIです。デベロッパーはキーワード、書籍のタイトルや著者名、出版社名などでの電子書籍検索をはじめ、ジャンル別などでの絞り込み検索も可能となります。

リクエストURL(REST/JSON形式の場合)


https://app.rakuten.co.jp/services/api/Kobo/EbookSearch/20170426?[parameter]=[value]…

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

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

https://app.rakuten.co.jp/services/api/Kobo/EbookSearch/20170426?
        applicationId=[アプリID]
        &keyword=%97%BF%97%9D
        &koboGenreId=101
        &sort=%2BitemPrice

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

入力パラメーター


楽天Kobo電子書籍検索API 入力パラメーター version:2017-04-26

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 必須
(*1)
- キーワードから検索
UTF-8でURLエンコードした文字列
複数キーワードから検索したい場合は、半角スペースで区切って下さい
(*1)キーワード、書籍タイトル、著者名、出版社名、商品番号、楽天KoboジャンルIDのいずれかが指定されていることが必須です
2 書籍タイトル title String 必須
(*1)
- 書籍のタイトルから検索
UTF-8でURLエンコードした文字列
複数キーワードから検索したい場合は、半角スペースで区切って下さい
(*1)キーワード、書籍タイトル、著者名、出版社名、商品番号、楽天KoboジャンルIDのいずれかが指定されていることが必須です
3 著者名 author String 必須
(*1)
- 著者名から検索
UTF-8でURLエンコードした文字列
複数キーワードから検索したい場合は、半角スペースで区切って下さい
(*1)キーワード、書籍タイトル、著者名、出版社名、商品番号、楽天KoboジャンルIDのいずれかが指定されていることが必須です
4 出版社名 publisherName String 必須
(*1)
- 出版社名から検索
UTF-8でURLエンコードした文字列
複数キーワードから検索したい場合は、半角スペースで区切って下さい
(*1)キーワード、書籍タイトル、著者名、出版社名、商品番号、楽天KoboジャンルIDのいずれかが指定されていることが必須です
5 商品番号 itemNumber String 必須
(*1)
- 商品番号から検索
(*1)キーワード、書籍タイトル、著者名、出版社名、商品番号、楽天KoboジャンルIDのいずれかが指定されていることが必須です
6 楽天KoboジャンルID koboGenreId String 必須
(*1)
101 楽天Koboにおけるジャンルを特定するためのID
(楽天市場のジャンルIDとは違うので注意してください)
KoboGenreId=101(電子書籍)に所属するジャンルのみが指定できます。 ジャンルのIDやジャンル名、ジャンルの親子関係を調べたい場合は、「楽天Koboジャンル検索API(Kobo/GenreSearch)」をご利用ください。
(*1)キーワード、書籍タイトル、著者名、出版社名、商品番号、楽天KoboジャンルIDのいずれかが指定されていることが必須です
7 言語 language String - 電子書籍の言語を指定することが可能です
「言語コード一覧」を参照してください
8 1ページあたりの取得件数 hits int - 30 1から30までの整数
9 取得ページ page int - 1 1から100までの整数
10 ソート sort String - standard standard:標準
+releaseDate:発売日(古い)
-releaseDate:発売日(新しい)
+itemPrice:価格が安い
-itemPrice:価格が高い
reviewCount:レビューの件数が多い
reviewAverage:レビューの評価(平均)が高い
※UTF-8でURLエンコードされている必要があります。
11 除外キーワード NGKeyword String - 検索結果から除外したいキーワード
UTF-8でURLエンコードした文字列
12 検索フィールド field int(1) - 1 0 :検索対象が広い(同じ検索キーワードでも多くの検索結果が得られる)
1 :検索対象範囲が限定される(同じ検索キーワードでも少ない検索結果が得られる)
13 OR検索フラグ orFlag int(1) - 0 複数キーワードが設定された場合に、AND検索、OR検索のいずれかが選択可能。
0 :AND検索
1 :OR検索
14 ジャンルごとの商品数取得フラグ genreInformationFlag int(1) - 0 0 :ジャンルごとの商品数の情報を取得しない
1 :ジャンルごとの商品数の情報を取得する
15 販売タイプ salesType int(1) - ALL 0:通常商品
1:予約商品

出力パラメーター


楽天Kobo電子書籍検索API 出力パラメーター version:2017-04-26

ID 大分類 分類 項目名 パラメーター 備考
区分:サービス固有パラメーター
1 全体情報 検索数 count 検索結果の総商品数
2 ページ番号 page 現在のページ番号
3 ページ内商品始追番 first 検索結果の何件目からか
4 ページ内商品終追番 last 検索結果の何件目までか
5 ヒット件数 hits 1度に返却する商品数
6 総ページ数 pageCount 最大100
7 商品情報
(全体:<Items> ~ </Items> 、
個別商品:<Item> ~ </Item>)
商品情報詳細 書籍タイトル title  
8 書籍タイトル カナ titleKana  
9 書籍サブタイトル subTitle (書籍によっては表示されない場合もあります)
10 叢書名 seriesName 本のシリーズ名
(書籍によっては表示されない場合もあります)
11 著者名 author  
12 著者名カナ authorKana  
13 出版社名 publisherName  
14 商品番号 itemNumber  
15 商品説明文 itemCaption  
16 発売日 salesDate 表示例:「YYYY年」「YYYY年MM月」「YYYY年MM月DD日」
※発売日が確定されていない商品については、「上旬/中旬/下旬」や「頃」「以降」などが付加
17 税込み販売価格 itemPrice  
18 商品URL itemUrl httpsではじまる商品ごとのURL
19 アフィリエイトURL affiliateUrl (入力パラメーターにアフィリエイトIDが含まれていた時のみ)
※carrierパラメーターの指定に関わらずPC/mobile両対応のhttpsではじまるURLを返却
20 商品画像 64x64URL smallImageUrl httpsではじまる商品画像(64x64ピクセル)のURL
21 商品画像 128x128URL mediumImageUrl httpsではじまる商品画像(128x128ピクセル)のURL
22 商品画像 200x200URL largeImageUrl httpsではじまる商品画像(200x200ピクセル)のURL
23 レビュー件数 reviewCount  
24 レビュー平均 reviewAverage  
25 ジャンル情報 楽天KoboジャンルID koboGenreId 所属する最下位のジャンルIDを表示
該当商品が複数ジャンルに所属している場合は、「/」で区切ってそれぞれのジャンルIDを表示
26 商品情報詳細 販売タイプ salesType 0:通常商品
1:予約商品
27 ジャンルごとの商品数
(全体:<GenreInformation>
~ </GenreInformation> 、
個別ジャンル:<parent> ~ </parent>
もしくは<current> ~ </current>
もしくは<children> ~ </children>)
親ジャンル - parent 入力したジャンルIDの親ジャンル
28 楽天KoboジャンルID koboGenreId  
29 楽天Koboジャンル名 koboGenreName  
30 ジャンル階層 genreLevel  
31 自ジャンル - current ユーザの入力した楽天KoboジャンルID
32 楽天KoboジャンルID koboGenreId  
33 楽天Koboジャンル名 koboGenreName  
34 ジャンルに紐づく商品数 itemCount  
35 ジャンル階層 genreLevel  
36 子ジャンル - children ユーザの入力した楽天KoboジャンルIDの子ジャンル
複数の子ジャンルがある場合は<children> ~ </children>が複数生成される
入力が「koboGenreId=101」の時はgenreLevel=1のジャンルが<children> ~ </children>に表示される
37 楽天KoboジャンルID koboGenreId  
38 楽天Koboジャンル名 koboGenreName  
39 ジャンルに紐づく商品数 itemCount  
40 ジャンル階層 genreLevel  

アフィリエイトに関して


デベロッパーは、楽天Kobo電子書籍検索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)]&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>