Top  > 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>

過去のバージョン


本APIの過去のバージョンは下記からご覧いただけます。

楽天ブックスジャンル検索API(2009-03-26)