Home      API list     Rakuten Books Total Search API

The Rakuten Books Total Search API can retrieve data about items listed on Rakuten Books. Developers can search by keyword and then limit the results by genre/availability.

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

https://app.rakuten.co.jp/services/api/BooksTotal/Search/20170404?
        applicationId=[APPLICATION ID]
        &keyword=%E6%9C%AC
        &NGKeyword=%E4%BA%88%E7%B4%84
        &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


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 Affiliate available
(*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 Affiliate available
(*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 Affiliate available
(*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) - 1 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

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>