Endpoint

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

*JSONP format available when callBack specified with JSON format

The [value] corresponds to the field name keyword/sort should be URL encoded with UTF-8
(The whole request does not need to be encoded, only the individual value portions of it)
For example, a keyword search for '本' that has been ordered with the cheapest item first (sort=+itemPrice) will look like the URL below. (Don't add line breaks when actually making the request. Instead the pieces of the request should be connected together.)

Input Parameters

Rakuten Books Total Search API Input Parameters version:2017-04-04

ID	Parameter name	Parameter	Type (maximum bytes in parentheses)	Required	Default	Comment
Division: Shared parameters
1	App ID	applicationId	String		-	Check here
2	Affiliate ID	affiliateId	String	-	-	Check here
3	Response format	format	String	-	json	Either JSON or XML When JSON is specified the callback parameter can also be set in order to use JSONP.
4	Callback function name	callback	String	-	-	Function name to be used with the JSONP output (UTF-8 URL encoded string) Alphanumeric characters, periods, or underscores
5	Choosing output fields	elements	String	-	-	By default, API response all of the fields. You can change response fields by this parameter. This parameter's data is separated by comma(,). For example, following request will response only itemName, itemPrice and itemUrl. elements=itemName,itemPrice,itemUrl
6	Format version	formatVersion	int	-	1	Response format version. If formatVersion=2 is set, the response format (JSON) will be improved. In case of formatVersion=1 : Our API response will be returned in Array format as the followings. You would need to use notation items[0].item.itemName To access itemName parameter. {"items": [ {"item": { "itemName": "a", "itemPrice": 10 }}, {"item": { "itemName": "b", "itemPrice": 20 }} ]} In case of formatVersion=2 : Our API response will be returned in Array format as the followings. You can use notation items[0].itemName To access itemName parameter. {"items": [ { "itemName": "a", "itemPrice": 10 }, { "itemName": "b", "itemPrice": 20 } ]}
Division:service specific parameters
1	Search keywords	keyword	String	(*1)	-	UTF-8 URL encoded string The keyword parameter can have a maximum length of 128 single byte characters The keyword parameter is delimited with single byte space characters. This defaults to an AND operation including all the keywords. To use OR instead set the orFlag to 1. Each search keyword must be at least two single byte characters or one double byte character. An exception is a minimum of two characters if the search keywords are using hiragana, katakana, or symbols. (*1)One of the following is required: search keyword, Rakuten Books genre ID, ISBN/JAN code.
2	Rakuten Books genre ID	booksGenreId	String	(*1)	000	ID to specify the genre in Rakuten Books. (different from Rakuten Ichiba genre ID) Please use the Rakuten Books Genre Search API to look up genre names and genre relations.(*1)One of the following is required: search keyword, Rakuten Books genre ID, ISBN/JAN code.
3	ISBN code/JANcode	isbnjan	String	(*1) (*2)	-	*Request should be numeric 13 character without hyphen, etc. (*1)OOne of the following is required: search keyword, Rakuten Books genre ID, ISBN/JAN code. (*2)If ISBN/JAN code is specified, search keyword and Rakuten books genre ID inpus are ignored.
4	Number of results per page	hits	int	-	30	An integer between 1 and 30
5	Result page	page	int	-	1	An integer between 1 and 100
6	Availability	availability	int(1)	-	0	0：All items 1：Available items 2：Usually shipped within 3 to 7 days 3：Usually shipped within 3 to 9 days 4：Backorder 5：Now accepting reservations 6：Inventory check with manufacturer needed
7	Item unavailable Flag(out of stock, etc.)	outOfStockFlag	int(1)	-	0	0：Exclude unavailable items, such as out of stock/end of sale 1：Include unavailable items, such as out of stock/end of sale
8	Chirayomi flag	chirayomiFlag	int(1)	-	0	0：All items 1：Chirayomi item only
9	Sort	sort	String	-	standard	standard:Standard sales:By most sold +releaseDate:Release date (older) -releaseDate:Release date (newer) +itemPrice:Item price (cheaper) -itemPrice:Item price (expensive) reviewCount:Higher number of reviews reviewAverage:Higher average review ratings *should be UTF-8 URL encoded
10	Limited item flag	limitedFlag	int(1)	-	0	0:All items 1:Limited item only *Limited items include items sold for limited period, items with limited number, items sold for pre-order only, etc.
11	Search field	field	int(1)	-	0	0:Broad search field (more results with same keyword) 1:Narrow search field (less results with same keyword)
12	Carrier	carrier	int(1)	-	0	For PC or mobile PC: 0 mobile: 1
13	OR search flag	orFlag	int(1)	-	0	AND/OR search available with multiple search keywords 0:AND search 1:OR search *complex search condition not available such as (A and B) or C
14	Excluded keywords(*3)	NGKeyword	String	-	not specified	Words to be excluded from search results UTF-8 URL encoded string Format is the same as of keyword (*3)Search keyword should be provided
15	Genre information flag【NEW】	genreInformationFlag	int(1)	-	0	0 :Do not get number of items for each genre. 1 :Get number of items for each genre.

Output Parameters

Rakuten Books Total Search API Output Parameters version:2017-04-04

ID	General description	Specific description	Parameter name	Parameter	Comment
Division:service specific parameters
1	Overall information		Search count	count	Total number of items in the search results
2			Page number	page	Current page number
3			First page	first	Result number to display from
4			Last page	last	Result number to display until
5			Search hits	hits	Number of results to return
6			Platform	carrier	PC=0 or mobile=1
7			Total page count	pageCount	Maximum of 100
8	Item information （All items：<Items> ～ </Items> 、 Individual item：<Item> ～ </Item>）	Item detail	Item title	title
9			Author	author	Returned if the item is a book or a foreign book
10			Artist name	artistName	Returns Artist/composer/staff/director if the item is a CD or a DVD/Blu-ray
11			Publisher	publisherName	Returns if the item is a book, a foreign book or a magazine
12			Sales agency	label	Returns if the item is a CD, a DVD/Blu-ray, a game or a software
13			ISBN code	isbn
14			JANcode	jan
15			Supported models	hardware	Returns if the item is a game
16			Supported OS	os	Returns if the item is software
17			Item description	itemCaption
18			Release date/publish year	salesDate	Example：「YYYY年」「YYYY年MM月」「YYYY年MM月DD日」 *if release date is not available, following description added: early/mid/late, around, after, etc.
19			Tax included price	itemPrice
20			List price	listPrice	*Because of the specification change in Rakuten Books, always return 0 from 2013/11/28. Please refrain from using this value.
21			Discount rate	discountRate	*Because of the specification change in Rakuten Books, always return 0 from 2013/11/28. Please refrain from using this value.
22			Discount amount	discountPrice	*Because of the specification change in Rakuten Books, always return 0 from 2013/11/28. Please refrain from using this value.
23			Item URL	itemUrl	Item url starting with https
24			Affiliate URL	affiliateUrl	(only if input parameter includes affiliate ID) *always returns https URL which can be used in both PC/mobile regardless of carrier parameter specification
25			Item image 64x64URL	smallImageUrl	item image(64x64 pixel) url starting with https
26			Item image 128x128URL	mediumImageUrl	item image(128x128 pixel) url starting with https
27			Item image 200x200URL	largeImageUrl	item image(200x200 pixel) url starting with https
28			Chirayomi URL	chirayomiUrl	Returned if the item is available in chirayomi service, chirayomi service url starting with https
29			Availability	availability	1：Available items 2：Usually shipped within 3 to 7 days 3：Usually shipped within 3 to 9 days 4：Backorder 5：Now accepting reservations 6：Inventory check with manufacturer needed
30			Shipping cost flag	postageFlag	0:Shipping cost not included 1:Free shipping 2:Shipping cost included (including shipping to convenience store) *due to campaign/etc, actual shipping fee may be different from actual the returned value
31			Limited item flag	limitedFlag	0:All items 1:Limited item *Limited items include items sold for limited period, items with limited number, items sold for pre-order only, etc.
32			Number of reviews	reviewCount
33			Average point of reviews	reviewAverage
34		Genre information	Rakuten Books genre ID	booksGenreId	Display the lowest genre ID that it belongs to *if the item belongs to multiple genres, display each genre ID, separated by a '/'
35	Number of items per genre （All genre：<GenreInformation> ～ </GenreInformation> 、 Individual genre：<parent> ～ </parent> Or<current> ～ </current> Or<children> ～ </children>）【NEW】	Parent genre	-	parent	Parent genre of the genre ID input by the user
36			Rakuten Books genre ID	booksGenreId
37			Rakuten Books genre name	booksGenreName
38			Genre hierarchy	genreLevel
39		Current genre	-	current	Genre ID input by the user
40			Rakuten Books genre ID	booksGenreId
41			Rakuten Books genre name	booksGenreName
42			Number of items by genre	itemCount
43			Genre hierarchy	genreLevel
44		Child genre	-	children	Child genre of genre ID input by the user if there are multiple genres, multiple <children> ～</children> are generated if the input is 'booksGenreId=000', genre of genreLevel=1 is displayed in ～
45			Rakuten Books genre ID	booksGenreId
46			Rakuten Books genre name	booksGenreName
47			Number of items by genre	itemCount
48			Genre hierarchy	genreLevel

About the Affiliate System

Developers can use the Rakuten Books Total Search API to make affiliate links from the returned item information. It's possible to receive affiliate commission from Rakuten Affiliate when the affiliate URL is used as the link. There are two ways to make affiliate link.
（1） When the affiliateId input parameter is included in the request the response from the API will include the affiliate URL.

（2） If developers wants to create 'Affiliate URL' from 'itemURL' and 'affiliateId (beta version)' (obtained from API) by themselves, it can be generated using following rule. However, the 'itemURL' part must be URL encoded.

https://hb.afl.rakuten.co.jp/hgc/[Affiliate]/?pc=[Item URL(PC)]&m=[Item URL(mobile)]

Error

Error messages are displayed in the form of HTTP status code and its response body

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

Response body format is display in 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>