リクエスト

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行につなげてリクエストしてください。）

入力パラメーター

楽天ブックス総合検索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	(*1)	-	UTF-8でURLエンコードした文字列 検索キーワード全体は半角で128文字以内で指定する必要があります。 検索キーワードは半角スペースで区切ることができ、デフォルトではAND条件 (すべてのキーワードが含まれるものを検索 ) になります。 もし、OR条件 (いずれかのキーワードが含まれるものを検索) を利用したい場合は、 orFlag を 1 に設定してください。 各検索キーワードは半角2文字 もしくは 全角1文字 以上で指定する必要があります。 また例外として、各検索キーワードがひらがな・カタカナ・記号の場合は2文字以上で指定する必要があります。 (*1)検索キーワード、楽天ブックスジャンルID、ISBNコード/JANコードのいずれかが指定されていることが必須です。
2	楽天ブックスジャンルID	booksGenreId	String	(*1)	000	楽天ブックスにおけるジャンルを特定するためのID （楽天市場のジャンルIDとは違うので注意してください） ジャンルのIDやジャンル名、ジャンルの親子関係を調べたい場合は、「楽天ブックスジャンル検索API(BooksGenre/Search)」をご利用ください。 (*1)検索キーワード、楽天ブックスジャンルID、ISBNコード/JANコードのいずれかが指定されていることが必須です。
3	ISBNコード/JANコード	isbnjan	String	(*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)	-	0	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ステータスコードとレスポンスボディから判断できます。

{
    "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>