This website will be under maintenance from Friday August 23, 2:00 PM to Monday August 26, 2.00 PM JST. Only this website is impacted. The Rakuten APIs will continue to work. Sorry for the inconvenience. For more details please check our SNS announcement.
Home      API一覧     楽天ブックスジャンル検索API

2013年7月、API名称「楽天ブックスジャンル検索API2」は「楽天ブックスジャンル検索API」に変更されました

楽天ブックスジャンル検索APIは楽天ブックスのジャンル名・ジャンル構造を返すAPIです。デベロッパーはジャンルIDを指定することでこれらの情報を得ることができます。

リクエストURL(REST/JSON形式の場合)


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

※JSONP形式は、JSON形式で入力パラメーターにcallBackを指定することで出力されます。

たとえば、第一階層目のジャンル一覧を取得したい場合のリクエストURLは下記になります。(実際には改行せずに1行につなげてリクエストしてください。)

https://app.rakuten.co.jp/services/api/BooksGenre/Search/20121128?
        applicationId=[アプリID]
        &booksGenreId=000

※短い時間の間に大量に、同一のリクエストURLへアクセスすると、一定時間利用できなくなる場合がございます。テストの際にはご注意ください。

入力パラメーター


楽天ブックスジャンル検索API 入力パラメータ version:2012-11-28

ID 項目名 パラメーター 型(括弧内は最大バイト数) 必須 デフォルト 備考
区分:共通パラメーター
1 アプリID applicationId String 必須 - こちらで確認できます
2 アフィリエイトID affiliateId String - 指定無し こちらで確認できます
3 レスポンス形式 format String - json json か xml を選択することができます。
json を選択した場合、 callback パラメーター指定により jsonp 形式にすることもできます。
4 コールバック関数名 callback String - 指定無し JSONPとして出力する際のコールバック関数名
(UTF-8でURLエンコードした文字列)
英数字、「.(ドット)」、「_(アンダーバー)」、「[(中括弧)」、「](中括弧)」のいずれか1文字以上
5 出力パラメーター指定 elements String - ALL カンマ区切りで、必要な出力パラメータを指定した場合、
指定された出力パラメータのみを返却します。
(例)elements=reviewCount,reviewAverage
6 出力フォーマットバージョン formatVersion int - 1

出力フォーマットのバージョン指定です。

2 を指定すると、JSONの出力方法が改善され以下のようになります。

formatVersion=1 の場合:
配列データに関して、以下の様にデータが返ります。
したがって、最初の itemName にアクセスするためにitems[0].item.itemNameとたどる必要があります。

{"items": [
    {"item": {
        "itemName": "a",
        "itemPrice": 10
    }},
    {"item": {
        "itemName": "b",
        "itemPrice": 20
    }}
]}

formatVersion=2 の場合:
下記のように、配列中の重複するオブジェクトが省略されます。
最初の itemName にアクセスするためにitems[0].itemNameでアクセスできます。

{"items": [
    {
        "itemName": "a",
        "itemPrice": 10
    },
    {
        "itemName": "b",
        "itemPrice": 20
    }
]}
区分:サービス固有パラメーター
1 楽天ブックスジャンルID booksGenreId String Affiliate対応あり - ジャンルルートは、booksGenreId=000とする
2 ジャンルパス genrePath int(1) - 0 結果セットに祖先ジャンル(親ジャンルよりも上のジャンル)を含めるか否 か
0:含めない
1:含める

出力パラメーター


楽天ブックスジャンル検索API 出力パラメーター version:2012-11-28

ID 分類 項目名 パラメーター 備考
区分:サービス固有パラメーター
1 親ジャンル - parents 入力したジャンルIDの親ジャンル
「genrePath=1」を入力パラメータで指定し、指定したgenreIdよりも更に上位階層がある場合、"<parents>~ </parents>"内に複数の"<parent>~ </parent>"が表示される
2 楽天ブックスジャンルID booksGenreId ジャンルID
3 楽天ブックスジャンル名 booksGenreName ジャンル名
4 ジャンル階層 genreLevel ジャンル階層
ジャンルルートは000
5 自ジャンル - current ユーザの入力したジャンルID
6 楽天ブックスジャンルID booksGenreId ジャンルID
7 楽天ブックスジャンル名 booksGenreName ジャンル名
8 ジャンル階層 genreLevel ジャンル階層
9 子ジャンル - children ユーザの入力したジャンルIDの子ジャンル
複数の子ジャンルがある場合は"<children>~ </children>"内に複数の"<child>~ </child>"が複数生成される
入力が「booksGenreId=000」の時はgenreLevel=1のジャンルが"<children>~ </children>"内に複数の"<child>~ </child>"に表示される
10 楽天ブックスジャンルID booksGenreId ジャンルID
11 楽天ブックスジャンル名 booksGenreName ジャンル名
12 ジャンル階層 genreLevel ジャンル階層

エラー

エラー内容はHTTPステータスコードとレスポンスボディから判断できます。

HTTPステータスコード 意味 レスポンスボディ例 (JSON)
400 パラメーターエラー (必須パラメータ不足)

applicationId を指定しなかった場合

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

keyword が正しい値でなかった時。(半角1文字のみ指定など)

{
    "error": "wrong_parameter",
    "error_description": "keyword parameter is not valid"
}
404 対象のデータが存在しなかった場合
{
    "error": "not_found",
    "error_description": "not found"
}
429 リクエスト過多 (各ユーザ制限値超過)

APIリクエスト数が上限に達した場合のエラーです。しばらく時間を空けてから、ご利用ください。

{
    "error": "too_many_requests",
    "error_description": "number of allowed requests has been exceeded for this API. please try again soon."
}
500 楽天ウェブサービス内のエラー

システムエラー。長時間続くようであれば、こちらよりごお問い合わせください。

{
    "error": "system_error",
    "error_description": "api logic error"
}
503 メンテナンス・リクエスト過多 (全ユーザ制限値超過)

メンテナンス (XXX/XXX にはAPI名が入る)

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

レスポンスボディの形式は format に従います。

format エラー出力例
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>