楽天Kobo電子書籍検索APIは、楽天Koboで販売されている電子書籍の情報を取得することが可能なAPIです。デベロッパーはキーワード、書籍のタイトルや著者名、出版社名などでの電子書籍検索をはじめ、ジャンル別などでの絞り込み検索も可能となります。
リクエストURL(REST/JSON形式の場合)
https://app.rakuten.co.jp/services/api/Kobo/EbookSearch/20140811?[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/20140811?
applicationId=[アプリID]
&keyword=%97%BF%97%9D
&koboGenreId=101
&sort=%2BitemPrice
※短い時間の間に大量に、同一のリクエストURLへアクセスすると、一定時間利用できなくなる場合がございます。テストの際にはご注意ください。
入力パラメーター
楽天Kobo電子書籍検索API 入力パラメーター version:2014-08-11
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の出力方法が改善され以下のようになります。
{"items": [ {"item": { "itemName": "a", "itemPrice": 10 }}, {"item": { "itemName": "b", "itemPrice": 20 }} ]}
{"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:2014-08-11
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 | |||
19 | アフィリエイトURL | affiliateUrl |
(入力パラメーターにアフィリエイトIDが含まれていた時のみ) ※carrierパラメーターの指定に関わらずPC/mobile両対応のURLを返却 |
||
20 | 商品画像 64x64URL | smallImageUrl | (画像サイズ 64px*64px) | ||
21 | 商品画像 128x128URL | mediumImageUrl | (画像サイズ 128px*128px) | ||
22 | 商品画像 200x200URL | largeImageUrl | (画像サイズ 200px*200px) | ||
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 を指定しなかった場合
keyword が正しい値でなかった時。(半角1文字のみ指定など)
|
404 | 対象のデータが存在しなかった場合 |
|
429 | リクエスト過多 (各ユーザ制限値超過) |
APIリクエスト数が上限に達した場合のエラーです。しばらく時間を空けてから、ご利用ください。
|
500 | 楽天ウェブサービス内のエラー | システムエラー。長時間続くようであれば、こちらよりごお問い合わせください。
|
503 | メンテナンス・リクエスト過多 (全ユーザ制限値超過) |
メンテナンス (XXX/XXX にはAPI名が入る)
|
レスポンスボディの形式は format に従います。
format | エラー出力例 |
---|---|
json |
|
xml |
|