EndpointURL（REST／JSON format）

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

*JSONP format available when callBack specified with JSON format

The values for the field names title, author, publisherName and sort must be URL encoded in UTF-8 style.
(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) in 'Japanese novel'(booksGenreId=001004008) Genre' 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

Books Book 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	Book title	title	String	(*1)	-	Search by Book title UTF-8 URL encoded string multiple keyword search available with multiple keywords delimited with single byte space characters (*1)One of the following is required: Title, Author name, Publisher, Size of the book, ISBN code, Rakuten Books Genre ID
2	Author	author	String	(*1)	-	Search by Author name UTF-8 URL encoded string multiple keyword search available with multiple keywords delimited with single byte space characters (*1)One of the following is required: Title, Author name, Publisher, Size of the book, ISBN code, Rakuten Books Genre ID
3	Publisher	publisherName	String	(*1)	-	Search by Publisher UTF-8 URL encoded string multiple keyword search available with multiple keywords delimited with single byte space characters (*1)One of the following is required: Title, Author name, Publisher, Size of the book, ISBN code, Rakuten Books Genre ID
4	Size of the book	size	int	(*1)	0	Search by Size of the book 0:All 1:Book 2:Paperback 3:New book 4:Complete set 5:Dictionary, Encyclopedia 6:Illustrated reference book 7:Picture book 8:Cassette tape, CD 9:Comic 10:Magazine book, other (*1)One of the following is required: Title, Author name, Publisher, Size of the book, ISBN code, Rakuten Books Genre ID
5	ISBN code	isbn	String	(*1)	-	Search by ISBN code (Book code) (*1)One of the following is required: Title, Author name, Publisher, Size of the book, ISBN code, Rakuten Books Genre ID
6	Rakuten Books genre ID	booksGenreId	String	(*1)	001	ID to specify the genre in Rakuten Books （different from Rakuten ichiba genre ID） Only able to specify the genre which belongs to booksGenreId=001(book) Please use the Rakuten Ichiba Genre Search API(BooksGenre/Search) to look up genre names and genre relations. (*1)One of the following is required: Title, Author name, Publisher, Size of the book, ISBN code, Rakuten Books Genre ID
7	Number of results per page	hits	int	-	30	An integer between 1 and 30
8	Result page	page	int	-	1	An integer between 1 and 100
9	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
10	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
11	Chirayomi flag	chirayomiFlag	int(1)	-	0	0：All items 1：Chirayomi item only
12	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
13	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.
14	Carrier	carrier	int(1)	-	0	For PC or mobile
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

Books Book 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	Book title	title
9			Book title in kana character	titleKana
10			Book subtitle	subTitle	（Not all book has this property）
11			Book subtitle in kana character	subTitleKana	（Not all book has this property）
12			Series name	seriesName	Name of series （Not all book has this property）
13			Series name in kana character	seriesNameKana	（Not all book has this property）
14			Multi volume contents	contents	multi volume books contents such as illustrated reference book, complete set （Not all book has this property）
15			Multi volume contents in kana character	contentsKana	（Not all book has this property）
16			Author	author
17			Author in kana character	authorKana
18			Publisher	publisherName
19			Size of the book	size	1:Book 2:Paperback 3:New book 4:Complete set 5:Dictionary, Encyclopedia 6:Illustrated reference book 7:Picture book 8:Cassette tape, CD 9:Comic 10:Magazine book, other
20			ISBN code (Book code)	isbn
21			Item description	itemCaption
22			Release date	salesDate	Example：「YYYY年」「YYYY年MM月」「YYYY年MM月DD日」 *if release date is not available, following description added: early/mid/late, around, after, etc.
23			Tax included price	itemPrice
24			List price	listPrice	*Because of the specification change in Rakuten Books, always return 0 from 2013/11/28. Please refrain from using this value.
25			Discount rate	discountRate	*Because of the specification change in Rakuten Books, always return 0 from 2013/11/28. Please refrain from using this value.
26			Discount amount	discountPrice	*Because of the specification change in Rakuten Books, always return 0 from 2013/11/28. Please refrain from using this value.
27			Item URL	itemUrl	Item url starting with https
28			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
29			Item image 64x64URL	smallImageUrl	item image(64x64 pixel) url starting with https
30			Item image 128x128URL	mediumImageUrl	item image(128x128 pixel) url starting with https
31			Item image 200x200URL	largeImageUrl	item image(200x200 pixel) url starting with https
32			Chirayomi URL	chirayomiUrl	Returned if the item is available in chirayomi service, chirayomi service url starting with https
33			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
34			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
35			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.
36			Number of reviews	reviewCount
37			Average point of reviews	reviewAverage
38		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 '/'
39	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
40			Rakuten Books genre ID	booksGenreId
41			Rakuten Books genre name	booksGenreName
42			Genre hierarchy	genreLevel
43		Current genre	-	current	Genre ID input by the user
44			Rakuten Books genre ID	booksGenreId
45			Rakuten Books genre name	booksGenreName
46			Number of items by genre	itemCount
47			Genre hierarchy	genreLevel
48		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 ～
49			Rakuten Books genre ID	booksGenreId
50			Rakuten Books genre name	booksGenreName
51			Number of items by genre	itemCount
52			Genre hierarchy	genreLevel

About the Affiliate System

Developers can use the Rakuten Books Book 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>