トップ  > API一覧 > 楽天ジャンル検索API

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

楽天ジャンル検索APIは楽天市場のジャンル名・ジャンル構造を返すAPIです。デベロッパーはジャンルIDを指定することでこれらの情報を得ることができます。
過去の楽天ジャンル検索APIにはなかった、兄弟ジャンル情報、指定したジャンルに紐づくタグ情報を返却するようになりました。
タグに関する詳細な説明は、Q&Aや楽天ウェブサービスのブログにて記載します。

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


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

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

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

https://app.rakuten.co.jp/services/api/IchibaGenre/Search/20140222?
        applicationId=[アプリID]&
        genreId=0

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

入力パラメーター


楽天ジャンル検索API 入力パラメータ version:2014-02-22

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 genreId int 必須
- ジャンルルートは、genreId=0とする
2 ジャンルパス genrePath int(1) - 1 結果セットに祖先ジャンル(親ジャンルよりも上のジャンル)を含めるか否か
0:含めない
1:含める

出力パラメーター


楽天ジャンル検索API 出力パラメーター version:2014-02-22

区分:サービス固有パラメーター
1 親ジャンル 親ジャンル 親ジャンル parents 入力したジャンルIDの親ジャンル
「genrePath=1」を入力パラメータで指定し、 指定したgenreIdよりも更に上位階層がある場合、"<parents>~ </parents>"内に複数の"<parent>~ </parent>"が表示される
2 ジャンルID genreId ジャンルID
3 ジャンル名 genreName ジャンル名
4 ジャンル階層 genreLevel ジャンル階層。ジャンルルートは0
5 自ジャンル 自ジャンル current ユーザの入力したジャンルID
6 ジャンルID genreId ジャンルID
7 ジャンル名 genreName ジャンル名
8 ジャンル階層 genreLevel ジャンル階層
9 兄弟ジャンル【NEW】 兄弟ジャンル brothers ユーザーの入力したジャンルIDの兄弟ジャンル
複数の子ジャンルがある場合は"<brothers>~ </brothers>"内に複数の"<brother>~ </brother>"が表示される
10 ジャンルID genreId ジャンルID
11 ジャンル名 genreName ジャンル名
12 ジャンル階層 genreLevel ジャンル階層
13 子ジャンル 子ジャンル children ユーザの入力したジャンルIDの子ジャンル
複数の子ジャンルがある場合は"<children>~ </children>"内に複数の"<child>~ </child>"が表示される
入力パラメータで「genreId=0」を指定した場合はgenreLevel=1の ジャンルが複数<child>~</child>に表示される
14 ジャンルID genreId ジャンルID
15 ジャンル名 genreName ジャンル名
16 ジャンル階層 genreLevel ジャンル階層
17 タグ情報【NEW】 タググループ情報 - tagGroup  
18 タググループ名 tagGroupName  
19 タググループID tagGroupId  
20 タグ情報 - tags "<tags>~</tags>の中に複数の<tag>~</tag>"
21 タグID tagId  
22 タグ名 tagName  
23 親タグID parentTagId  

エラー

エラー内容は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>

SDKによるデータ取得

楽天ウェブサービス上で公開しているSDKでは、以下のようにデータを取得することができます。

PHP SDK について
<?php
require_once '/path/to/sdk-dir/autoload.php';

$client = new RakutenRws_Client();
// アプリID (デベロッパーID) をセットします
$client->setApplicationId('YOUR_APPLICATION_ID');

// 楽天市場ジャンル検索API では operation として 'IchibaGenreSearch' を指定してください。
// ここでは例として genreId に 0 を指定しています。
$response = $client->execute('IchibaGenreSearch', array(
    'genreId => 0
));

// レスポンスが正常かどうかを isOk() で確認することができます
if ($response->isOk()) {
    foreach ($response['children'] as $childGenre) {
        $genre = $childGenre['child'];

        // ジャンル名を出力します
        echo $genre['genreName']."\n";
    }
} else {
    // getMessage() でレスポンスメッセージを取得することができます
    echo 'Error:'.$response->getMessage();
}

過去のバージョン


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