リクエストURL（REST／JSON形式の場合）

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

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

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

入力パラメーター

楽天ブックスDVD/Blu-ray検索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	DVD/Blu-rayタイトル	title	String	(*1)	-	DVD/Blu-rayのタイトルから検索 UTF-8でURLエンコードした文字列 複数キーワードから検索したい場合は、半角スペースで区切って下さい (*1)タイトル、出演者名/監督名等、発売元名、JANコード、楽天ブックスジャンルIDのいずれかが指定されていることが必須です
2	出演者名/監督名等	artistName	String	(*1)	-	出演者名や監督名から検索 UTF-8でURLエンコードした文字列 複数キーワードから検索したい場合は、半角スペースで区切って下さい (*1)タイトル、出演者名/監督名等、発売元名、JANコード、楽天ブックスジャンルIDのいずれかが指定されていることが必須です
3	発売元名	label	String	(*1)	-	発売元名から検索 UTF-8でURLエンコードした文字列 複数キーワードから検索したい場合は、半角スペースで区切って下さい (*1)タイトル、出演者名/監督名等、発売元名、JANコード、楽天ブックスジャンルIDのいずれかが指定されていることが必須です
4	DVD/Blu-rayのJANコード	jan	long	(*1)	-	DVD/Blu-rayに付与されているJANコードから検索 (*1)タイトル、出演者名/監督名等、発売元名、JANコード、楽天ブックスジャンルIDのいずれかが指定されていることが必須です
5	楽天ブックスジャンルID	booksGenreId	String	(*1)	003	楽天ブックスにおけるジャンルを特定するためのID （楽天市場のジャンルIDとは違うので注意してください） booksGenreId=003（DVD/Blu-ray）に所属するジャンルのみが指定できます。 ジャンルのIDやジャンル名、ジャンルの親子関係を調べたい場合は、「楽天ブックスジャンル検索API(BooksGenre/Search)」をご利用ください。 (*1)タイトル、出演者名/監督名等、発売元名、JANコード、楽天ブックスジャンルIDのいずれかが指定されていることが必須です
6	1ページあたりの取得件数	hits	int	-	30	1から30までの整数
7	取得ページ	page	int	-	1	1から100までの整数
8	在庫状況	availability	int(1)	-	0	0：すべての商品 1：在庫あり 2：通常3～7日程度で発送 3：通常3～9日程度で発送 4：メーカー取り寄せ 5：予約受付中 6：メーカーに在庫確認
9	品切れ等購入不可商品表示フラグ	outOfStockFlag	int(1)	-	0	0：品切れや販売終了など購入不可の商品は結果に表示させない 1：品切れや販売終了など購入不可の商品を結果に表示させる
10	ソート	sort	String	-	standard	standard:標準 sales:売れている +releaseDate:発売日(古い) -releaseDate:発売日(新しい) +itemPrice:価格が安い -itemPrice:価格が高い reviewCount:レビューの件数が多い reviewAverage:レビューの評価(平均)が高い ※UTF-8でURLエンコードされている必要があります。
11	限定フラグ	limitedFlag	int(1)	-	0	0:すべての商品 1:限定版商品のみ ※限定版商品には期間限定・数量限定・予約限定などの商品が含まれます。
12	キャリア	carrier	int(1)	-	0	PC用の情報を返すのか、モバイル用の情報を返すのかを選択 PC: 0 mobile: 1
13	ジャンルごとの商品数取得フラグ【NEW】	genreInformationFlag	int(1)	-	0	0 :ジャンルごとの商品数の情報を取得しない 1 :ジャンルごとの商品数の情報を取得する

出力パラメーター

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

アフィリエイトに関して

デベロッパーは、楽天ブックスDVD/Blu-ray検索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ステータスコードとレスポンスボディから判断できます。

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

{
    "error": "wrong_parameter",
    "error_description": "keyword parameter is not valid"
}

{
    "error": "not_found",
    "error_description": "not found"
}

{
    "error": "too_many_requests",
    "error_description": "number of allowed requests has been exceeded for this API. please try again soon."
}

{
    "error": "system_error",
    "error_description": "api logic error"
}

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

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

{
    "error": "wrong_parameter",
    "error_description": "page must be a number"
}

<?xml version="1.0" encoding="UTF-8"?>
<root>
    <error>wrong_parameter</error>
    <error_description>page must be a number</error_description>
</root>