BooksTotal/Search

Description

Gets up to 30 media items by keywords, genre or ISBN/JAN.

Resource URL

https://app.rakuten.co.jp/services/api/BooksTotal/Search/20130522

Resource Information

Auth Type App Key
Affiliation Support Yes

Parameters

App ID (string)

The Application ID that identifies your application. You can get it from https://webservice.rakuten.co.jp/.

Search keywords (string)

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.

Book genre ID (string)

Book ID to specify a book genre.

Please use the Book Genre Search API to look up book genre names and genre relations.

Default Value: 000

ISBN/JAN code (string)

Use a 13 character code by removing all the hyphen symbols.

(*1) If ISBN/JAN code is specified, please do not set the search keywords and book genre ID parameters.

How many results to display on each page (integer)

An integer between 1 and 30

Default Value: 30

Result page (integer)

An integer between 1 and 100

Default Value: 1

Availability (integer)

Valid Values:

  • 0 all items
  • 1 In Stock
  • 2 Usually ships in about 3 to 7 days
  • 3 Usually ships in about 3 to 9 days
  • 4 Manufacturer stock
  • 5 Preorder
  • 6 Check stock with manufacturer

Default Value: 0

Out of Stock Flag (integer)

Valid Values:

  • 0 Do not include out of stock items.
  • 1 Include out of stock items.

Default Value: 0

Chira Yomi Flag (integer)

Valid Values:

  • 0 All items.
  • 1 Only chirayomi (free preview) items.

Default Value: 0

Sort (string)

*UTF-8 URL encoding is required.

Valid Values:

  • standard
  • sales
  • +releaseDate Release date (Ascending order)
  • -releaseDate Release date (Descending order)
  • +itemPrice Item price (Ascending order)
  • -itemPrice Item price (Descending order)
  • reviewCount
  • reviewAverage

Default Value: standard

Limited Flag (integer)

※ Limited Edition include products such as limited time, limited quantity or reservation limited.

Valid Values:

  • 0 All items
  • 1 Limited Edition only

Default Value: 0

Search field (integer)

Valid Values:

  • 0 Broad search (prefer more matches with the same keyword)
  • 1 Restricted search (prefer fewer matches with the same keyword)

Default Value: 0

Platform (integer)

Valid Values:

  • 0 PC
  • 1 Mobile

Default Value: 1

OR search flag (integer)

Choose between AND searches and OR searches when there are multiple keywords.

*It isn't possible to use a complex search condition like "(A and B) or C".

Valid Values:

  • 0 AND
  • 1 OR

Default Value: 0

Excluded keywords (*3) (string)

Words to exclude from search results

Strings encoded with UTF-8 URL encoding

Same format as keyword

(*3) This field can only be used if the search keywords field is set.

Genre information flag (integer)

Valid Values:

  • 0 Do not get number of item in each genre.
  • 1 Get number of item in each genre.

Default Value: 0

Affiliate ID (string)

If this endpoint supports affiliation, here you can enter your affiliate ID. If you do, the links in the API response will include your affiliate ID.

Response format (string)

Format for the response output.

You can set this parameter to json or xml. JSON is usually the best option.

If you choose JSON, you can also set the callback parameter in order to use JSONP.

Valid Values:

  • json
  • xml

Default Value: json

Callback function name (string)

Function name to be used with the JSONP output

Please make sure you enter a UTF-8 URL encoded string, containing only a combination of alphanumeric characters, periods and underscores.

Choosing output fields (string)

By default API will return all the fields. You can specify what fields should be returned by using this parameter.

If you want to specify more than one parameter, please use comma (,) as separator.

For example, following request will only return itemName, itemPrice and itemUrl.

elements=itemName,itemPrice,itemUrl

Format version (integer)

Response format version.

If formatVersion=2 is set, the response format (JSON) will be improved.

In case of formatVersion=1:

The API response will return an array using the following format.

For example, 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:

The API response will return an array using the following format.

For example, you would use the notation items[0].itemName to access the itemName parameter.

{"items": [

{

"itemName": "a",

"itemPrice": 10

},

{

"itemName": "b",

"itemPrice": 20

}

]}

Valid Values:

  • 1
  • 2

Default Value: 1

applicationId

App ID
string Required

The Application ID that identifies your application. You can get it from https://webservice.rakuten.co.jp/.

keyword

Search keywords
string At least one is required

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.

booksGenreId

Book genre ID
string At least one is required

Book ID to specify a book genre.

Please use the Book Genre Search API to look up book genre names and genre relations.

Default Value: 000

isbnjan

ISBN/JAN code
string At least one is required

Use a 13 character code by removing all the hyphen symbols.

(*1) If ISBN/JAN code is specified, please do not set the search keywords and book genre ID parameters.

hits

How many results to display on each page
integer Optional

An integer between 1 and 30

Default Value: 30

page

Result page
integer Optional

An integer between 1 and 100

Default Value: 1

availability

Availability
integer Optional

Valid Values:

  • 0 all items
  • 1 In Stock
  • 2 Usually ships in about 3 to 7 days
  • 3 Usually ships in about 3 to 9 days
  • 4 Manufacturer stock
  • 5 Preorder
  • 6 Check stock with manufacturer

Default Value: 0

outOfStockFlag

Out of Stock Flag
integer Optional

Valid Values:

  • 0 Do not include out of stock items.
  • 1 Include out of stock items.

Default Value: 0

chirayomiFlag

Chira Yomi Flag
integer Optional

Valid Values:

  • 0 All items.
  • 1 Only chirayomi (free preview) items.

Default Value: 0

sort

Sort
string Optional

*UTF-8 URL encoding is required.

Valid Values:

  • standard
  • sales
  • +releaseDate Release date (Ascending order)
  • -releaseDate Release date (Descending order)
  • +itemPrice Item price (Ascending order)
  • -itemPrice Item price (Descending order)
  • reviewCount
  • reviewAverage

Default Value: standard

limitedFlag

Limited Flag
integer Optional

※ Limited Edition include products such as limited time, limited quantity or reservation limited.

Valid Values:

  • 0 All items
  • 1 Limited Edition only

Default Value: 0

field

Search field
integer Optional

Valid Values:

  • 0 Broad search (prefer more matches with the same keyword)
  • 1 Restricted search (prefer fewer matches with the same keyword)

Default Value: 0

carrier

Platform
integer Optional

Valid Values:

  • 0 PC
  • 1 Mobile

Default Value: 1

orFlag

OR search flag
integer Optional

Choose between AND searches and OR searches when there are multiple keywords.

*It isn't possible to use a complex search condition like "(A and B) or C".

Valid Values:

  • 0 AND
  • 1 OR

Default Value: 0

NGKeyword

Excluded keywords (*3)
string Optional

Words to exclude from search results

Strings encoded with UTF-8 URL encoding

Same format as keyword

(*3) This field can only be used if the search keywords field is set.

genreInformationFlag

Genre information flag
integer Optional

Valid Values:

  • 0 Do not get number of item in each genre.
  • 1 Get number of item in each genre.

Default Value: 0

affiliateId

Affiliate ID
string Optional

If this endpoint supports affiliation, here you can enter your affiliate ID. If you do, the links in the API response will include your affiliate ID.

format

Response format
string Optional

Format for the response output.

You can set this parameter to json or xml. JSON is usually the best option.

If you choose JSON, you can also set the callback parameter in order to use JSONP.

Valid Values:

  • json
  • xml

Default Value: json

callback

Callback function name
string Optional

Function name to be used with the JSONP output

Please make sure you enter a UTF-8 URL encoded string, containing only a combination of alphanumeric characters, periods and underscores.

elements

Choosing output fields
string Optional

By default API will return all the fields. You can specify what fields should be returned by using this parameter.

If you want to specify more than one parameter, please use comma (,) as separator.

For example, following request will only return itemName, itemPrice and itemUrl.

elements=itemName,itemPrice,itemUrl

formatVersion

Format version
integer Optional

Response format version.

If formatVersion=2 is set, the response format (JSON) will be improved.

In case of formatVersion=1:

The API response will return an array using the following format.

For example, 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:

The API response will return an array using the following format.

For example, you would use the notation items[0].itemName to access the itemName parameter.

{"items": [

{

"itemName": "a",

"itemPrice": 10

},

{

"itemName": "b",

"itemPrice": 20

}

]}

Valid Values:

  • 1
  • 2

Default Value: 1

Response Example

Request

https://app.rakuten.co.jp/services/api/BooksTotal/Search/20130522?applicationId=REPLACE_WITH_YOUR_APP_ID&keyword=ドン・キホーテ&hits=3

Response
{
  "count": 119,
  "page": 1,
  "first": 1,
  "last": 3,
  "hits": 3,
  "carrier": 0,
  "pageCount": 40,
  "Items": [
    {
      "Item": {
        "title": "ドン・キホーテ 1-2巻セット",
        "author": "行徒/河田雄志",
        "artistName": "",
        "publisherName": "新潮社",
        "label": "",
        "isbn": "2100010283771",
        "jan": "",
        "hardware": "",
        "os": "",
        "itemCaption": "",
        "salesDate": "2015年03月",
        "itemPrice": 1210,
        "listPrice": 0,
        "discountRate": 0,
        "discountPrice": 0,
        "itemUrl": "http://books.rakuten.co.jp/rb/13144177/",
        "affiliateUrl": "",
        "smallImageUrl": "http://thumbnail.image.rakuten.co.jp/@0_mall/book/cabinet/3771/2100010283771.jpg?_ex=64x64",
        "mediumImageUrl": "http://thumbnail.image.rakuten.co.jp/@0_mall/book/cabinet/3771/2100010283771.jpg?_ex=120x120",
        "largeImageUrl": "http://thumbnail.image.rakuten.co.jp/@0_mall/book/cabinet/3771/2100010283771.jpg?_ex=200x200",
        "chirayomiUrl": "",
        "availability": "1",
        "postageFlag": 0,
        "limitedFlag": 0,
        "reviewCount": 0,
        "reviewAverage": "0.0",
        "booksGenreId": "001025"
      }
    },
    {
      "Item": {
        "title": "ドン・キホーテ(全6冊セット)",
        "author": "ミゲル・デ・セルバンテス・サアベドラ/牛島信明",
        "artistName": "",
        "publisherName": "岩波書店",
        "label": "",
        "isbn": "9784002010588",
        "jan": "",
        "hardware": "",
        "os": "",
        "itemCaption": "",
        "salesDate": "2001年07月",
        "itemPrice": 5875,
        "listPrice": 0,
        "discountRate": 0,
        "discountPrice": 0,
        "itemUrl": "http://books.rakuten.co.jp/rb/1362072/",
        "affiliateUrl": "",
        "smallImageUrl": "http://thumbnail.image.rakuten.co.jp/@0_mall/book/cabinet/0588/9784002010588.jpg?_ex=64x64",
        "mediumImageUrl": "http://thumbnail.image.rakuten.co.jp/@0_mall/book/cabinet/0588/9784002010588.jpg?_ex=120x120",
        "largeImageUrl": "http://thumbnail.image.rakuten.co.jp/@0_mall/book/cabinet/0588/9784002010588.jpg?_ex=200x200",
        "chirayomiUrl": "",
        "availability": "1",
        "postageFlag": 2,
        "limitedFlag": 0,
        "reviewCount": 3,
        "reviewAverage": "5.0",
        "booksGenreId": "001008022008"
      }
    },
    {
      "Item": {
        "title": "R.シュトラウス:交響詩≪ドン・キホーテ≫ 交響詩≪ティル・オイレンシュピーゲルの愉快ないたずら≫",
        "author": "",
        "artistName": "ヘルベルト・フォン・カラヤン/アントニオ・メネセス/ヴォルフラム・クリスト/リヒャルト・シュトラウス/ヘルベルト・フォン・カラヤン/アントニオ・メネセス",
        "publisherName": "",
        "label": "ユニバーサルミュージック クラシック",
        "isbn": "",
        "jan": "4988005753465",
        "hardware": "",
        "os": "",
        "itemCaption": "",
        "salesDate": "2013年03月20日",
        "itemPrice": 1572,
        "listPrice": 0,
        "discountRate": 0,
        "discountPrice": 0,
        "itemUrl": "http://books.rakuten.co.jp/rb/12169413/",
        "affiliateUrl": "",
        "smallImageUrl": "http://thumbnail.image.rakuten.co.jp/@0_mall/book/cabinet/3465/4988005753465.jpg?_ex=64x64",
        "mediumImageUrl": "http://thumbnail.image.rakuten.co.jp/@0_mall/book/cabinet/3465/4988005753465.jpg?_ex=120x120",
        "largeImageUrl": "http://thumbnail.image.rakuten.co.jp/@0_mall/book/cabinet/3465/4988005753465.jpg?_ex=200x200",
        "chirayomiUrl": "",
        "availability": "1",
        "postageFlag": 1,
        "limitedFlag": 0,
        "reviewCount": 0,
        "reviewAverage": "0.0",
        "booksGenreId": "002104002"
      }
    }
  ],
  "GenreInformation": []
}

Try It

Set the Parameters

  Show More Parameters

Request

https://app.rakuten.co.jp/services/api/BooksTotal/Search/20130522?applicationId=REPLACE_WITH_YOUR_APP_ID

Response