Home      API list     Books Book Search API

Books Book Search API enables developers to retrieve information of selling books on Rakuten Books. Developers are allowed to obtain the book information by specifying Book Title, Author and Publisher as well as to filter the search with Genre, Inventory Status and so forth.
(This api allows more advanced search than Books Total Search API.)

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.)

https://app.rakuten.co.jp/services/api/BooksBook/Search/20170404?
        applicationId=[APPLICATION ID]
        &title=%E5%A4%AA%E9%99%BD
        &booksGenreId=001004008
        &sort=%2BitemPrice

*If many accesses to an identical URL are made in a short time, the URL may be become unresponsive for a fixed period of time. Please take care during testing.

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 Required
(*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 Required
(*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 Required
(*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 Required
(*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 Required
(*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 Required
(*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

HTTP Status Code Description Response body example (JSON)
400 Parameter error (or required parameters were insufficient)

If applicationId is not set

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

If keyword is not valid (only 1 character given, etc.)

{
    "error": "wrong_parameter",
    "error_description": "keyword parameter is not valid"
}
404 If data not found.
{
    "error": "not_found",
    "error_description": "not found"
}
429 Too many requests

This error will be displayed if the number of API requests has been exceeded.
Please try access again after an amount of time.

{
    "error": "too_many_requests",
    "error_description": "number of allowed requests has been exceeded for this API. please try again soon."
}
500 Internal error in Rakuten Web Service

An internal system error occured. If you continue seeing this message for a long period, please give your inquiry via this link

{
    "error": "system_error",
    "error_description": "api logic error"
}
503 Unavailable due to maintenance or overloaded

Maintenance (the API name will be displayed in XXX/XXX)

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

Response body format is display in format.

format Error output example
json
{
    "error": "wrong_parameter",
    "error_description": "page must be a number"
}
xml
<?xml version="1.0" encoding="UTF-8"?>
<root>
    <error>wrong_parameter</error>
    <error_description>page must be a number</error_description>
</root>