Home      API一覧     楽天商品ランキングAPI

2013年7月、API名称「楽天商品ランキングAPI2」は「楽天商品ランキングAPI」に変更されました

楽天商品ランキングAPIは、楽天市場内のコンテンツ「ランキング市場」の情報を取得することが可能なAPIです。
デベロッパーはジャンル別や性別、年代別などで売れている商品の情報を取得することができます。
過去の楽天商品ランキングAPIからバージョンアップし、リアルタイムのランキングの取得、3枚の商品画像の取得、最大1000位までのランキング取得ができるようになりました。

リクエストURL


https://app.rakuten.co.jp/services/api/IchibaItem/Ranking/20170628?[parameter]=[value]…

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

たとえば、以下の3つのような場合のリクエストURLは下記になります。(実際には改行せずに1行につなげてリクエストしてください。)

(1)総合ランキングの情報を取得する場合(サービス固有パラメーターを無指定)
https://app.rakuten.co.jp/services/api/IchibaItem/Ranking/20170628?
applicationId=[アプリID]

(2)「洋菓子(genreId=100283)」ジャンルのランキング情報を取得する場合(ジャンルパラメーターを指定)
https://app.rakuten.co.jp/services/api/IchibaItem/Ranking/20170628?
applicationId=[アプリID]
&genreId=100283

(3)「20代の女性」のランキング情報を取得する場合(年代別・性別パラメーターを指定)
https://app.rakuten.co.jp/services/api/IchibaItem/Ranking/20170628?
applicationId=[アプリID]
&age=20
&sex=1

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

利用上の注意


※入力パラメーターに関する注意事項(2012年10月現在)
ランキング情報を取得する際には、「ジャンルID」「年代別」「性別」のサービス固有パラメーターを指定して行ないます。

(1) 「ジャンルID」
「ジャンルID」のみが指定された場合は、入力されたジャンルのランキング情報が表示されます。
「ジャンルID」は、「年代別」「性別」と同時に指定できません。

(2) 「年代別」
「年代別」のみが指定された場合は、各年代別の総合ランキングが表示されます。
また「年代別」パラメーターは、同時に「性別」を指定することが可能で、両方が指定された場合、各性別の年代別ランキングが表示されます。

(3) 「性別」
「性別」のみが指定された場合は、各性別の総合ランキングが表示されます。
また「性別」パラメーターは、同時に「年代別」を指定することが可能で、両方が指定された場合、各性別の年代別ランキングが表示されます。

(4) 無指定の場合は「総合ランキング」が表示されます。

※ランキング順位と総数が「ランキング市場」と一部異なる場合があります。
取得できるランキング情報は、「ランキング市場」と同じものとなりますが、 「ランキング市場」でランクインしている商品の商品ページが何らかの理由で削除されている場合、 楽天商品ランキングAPIではその順位を飛ばして表示しております。 よって「ランキング市場」と一部、総数が異なる場合があります。予めご了承ください。

入力パラメーター


楽天商品ランキングAPI 入力パラメーター version:2017-06-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 genreId long (*1)(*3) - 楽天市場におけるジャンルを特定するためのID
ジャンル名、ジャンルの親子関係を調べたい場合は、「楽天ジャンル検索API(GenreSearch)」をご利用ください)
(*1)ジャンルID、性別、年代別のいずれも指定されない場合「総合ランキング」が表示されます。
(*3)その他入力パラメーター指定の際の詳細は、本ページ内の「利用上の注意」内の「入力パラメーターに関する注意事項」をご覧ください
2 年代別 age int (*1)(*2)(*3) - 10:10代
20:20代
30:30代
40:40代
50:50代以上
(*1)ジャンルID、性別、年代別のいずれも指定されない場合「総合ランキング」が表示されます。
(*2)年代別、性別は同時に両方を指定可能です
(*3)その他入力パラメーター指定の際の詳細は、本ページ内の「利用上の注意」内の「入力パラメーターに関する注意事項」をご覧ください
3 性別 sex int (*1)(*2)(*3) 0 0:男性
1:女性
(*1)ジャンルID、性別、年代別のいずれも指定されない場合「総合ランキング」が表示されます。
(*2)年代別、性別は同時に両方を指定可能です
(*3)その他入力パラメーター指定の際の詳細は、本ページ内の「利用上の注意」内の「入力パラメーターに関する注意事項」をご覧ください
4 キャリア carrier int(1) - 0 PC用の情報を返すのか、モバイル用の情報を返すのかを選択
PC:0
mobile:1
5 取得ページ page int - 1 1から34までの整数
※30位よりも下のランキングに対応している場合に指定可能
6 ランキング集計期間【NEW】 period string - - realtime:リアルタイムランキングを取得

出力パラメーター


楽天商品ランキングAPI 出力パラメーター version:2017-06-28

ID 大分類 分類 項目名 パラメーター 備考
区分:サービス固有パラメーター
1 全体情報 ランキングタイトル title  
2 最終更新時間 lastBuildDate  
3 商品情報
(全体:<Items> ~ </Items> 、個別商品:<Item> ~ </Item>)
商品情報詳細 順位 rank  
4 キャリア carrier PC=0 or mobile=1
5 商品名 itemName 従来の商品名を表示させたい場合は、「catchcopy+itemname」で表示してください。
※キャリア(carrier)の指定により返却情報が異なります。
6 キャッチコピー catchcopy
7 商品コード itemCode  
8 商品価格 itemPrice  
9 商品説明文 itemCaption ※キャリア(carrier)の指定により返却情報が異なります。
10 商品URL itemUrl ※キャリア(carrier)の指定により返却情報が異なります。

※仕様変更により、2015/07/01から、
入力パラメーターにアフィリエイトIDが
含まれていた場合、affiliateUrlと
同じ値を返却いたします。

httpsからはじまる商品URL
11 アフィリエイトURL affiliateUrl (入力パラメーターにアフィリエイトIDが含まれていた時のみ)
※carrierパラメーターの指定に関わらずPC/mobile両対応のURLを返却
httpsからはじまるアフィリエイトURL
12 商品画像有無フラグ imageFlag 0:商品画像無し
1:商品画像有り
13 商品画像64x64URL【NEW】 smallImageUrls 最大3枚の画像(画像サイズ64px*64px)をimageUrl の配列で返却
httpsからはじまる商品画像64x64URL
14 商品画像128x128URL【NEW】 mediumImageUrls 最大3枚の画像(画像サイズ128px*128px)を imageUrl の配列で返却
httpsからはじまる商品画像128x128URL
15 販売可能フラグ availability 0:販売不可能
1:販売可能
16 消費税フラグ taxFlag 0:税込
1:税別
17 送料フラグ postageFlag 0:送料込
1:送料別
18 クレジットカード利用可能フラグ creditCardFlag 0:カード利用不可
1:カード利用可
19 ショップオブザイヤーフラグ shopOfTheYearFlag 0:ショップオブザイヤー未受賞店舗
1:ショップオブザイヤー受賞店舗
20 海外配送フラグ shipOverseasFlag 0:海外配送不可
1:海外配送可能
21 海外配送対象地域 shipOverseasArea 「/」(スラッシュ)区切りで対応国が表示されます。
22 あす楽フラグ asurakuFlag 0:翌日配送不可
1:翌日配送可能
※「あす楽」の詳細はこちらをご覧ください
23 あす楽〆時間 asurakuClosingTime HH:MM という形式で返却します。
※「あす楽フラグ」が1の場合のみ返却します。
24 あす楽配送対象地域 asurakuArea 「/」(スラッシュ)区切りで対応地域が表示されます。
※「あす楽フラグ」が1の場合のみ返却します。
25 アフィリエイト利用利率 affiliateRate  
26 販売開始時刻 startTime タイムセールが設定されている場合のみ(YYYY-MM-DD HH:MM形式)
27 販売終了時刻 endTime タイムセールが設定されている場合のみ(YYYY-MM-DD HH:MM形式)
28 レビュー件数 reviewCount  
29 レビュー平均 reviewAverage  
30 商品別ポイント倍付け pointRate 例)5 →ポイント5倍
商品別ポイント倍付けについてはこちらをご確認ください。
※ポイント倍付けの終了日時がリクエスト日時から24時間後以降の場合のみ表示されます。
31 商品別ポイント倍付け開始日時 pointRateStartTime 商品別ポイント倍付け(pointRate)の適用開始日時
※ポイント倍付けの終了日時がリクエスト日時から24時間後以降の場合のみ表示されます。
32 商品別ポイント倍付け終了日時 pointRateEndTime 商品別ポイント倍付け(pointRate)の適用終了日時
※ポイント倍付けの終了日時がリクエスト日時から24時間後以降の場合のみ表示されます。
33 店舗情報 店舗名 shopName  
34 店舗コード shopCode 店舗ごとのURL (http://
www.rakuten.co.jp/[xyz])
におけるxyzのこと
35 店舗URL shopUrl httpsからはじまる店舗ごとのURL

※仕様変更により、2015/07/01から、
入力パラメーターにアフィリエイトIDが
含まれていた場合、shopAffiliateUrlと
同じ値を返却いたします。
36 ジャンル情報 ジャンル情報 ジャンルID genreId  

商品別ポイント倍付けに関して


商品購入時に付与される楽天スーパーポイントは、通常、購入金額の1%ですが、ポイント倍付けが設定されている商品は、設定期間中に商品を購入すると、設定された倍率が適用されます。ポイント倍付けの詳しい仕組みは、こちらでご確認ください。

ショップが設定するポイント倍付けには、特定商品のみに適用される商品別ポイント倍付けと、特定ショップの全商品に適用されるショップ別ポイント倍付けの2種類があります。本APIでは、現在のところ、商品別ポイント倍付けの情報を提供しています。

アフィリエイトに関して


デベロッパーは、楽天商品ランキングAPIから取得した商品情報からアフィリエイトURLを作成することが可能です。リンク先にそのアフィリエイトURLを指定することで、楽天アフィリエイト経由の成果報酬を獲得することができます。
アフィリエイトURLの作り方は2通りあります。入力パラメーターcarrierでPCが指定された場合でもモバイルが指定された場合でも同様の方法でアフィリエイトURLを作成することができます。

(1) APIの入力パラメーターに「アフィリエイトID」を含める場合: APIの出力に「アフィリエイトURL」が含まれます。

(2) デベロッパーが自ら、(APIから取得した)「商品URL」と「アフィリエイトID(β版)」から「アフィリエイトURL」を作成する場合: 「アフィリエイトURL」は以下のルールで生成可能です。ただし、「商品URL」の部分はURLエンコードされている必要があります。

http://hb.afl.rakuten.co.jp/hgc/[アフィリエイトID]/?pc=[商品URL(PC)]&m=[商品URL(モバイル)]

エラー

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

genreIDが未設定、sexperiodは設定済み、かつageが範囲外(20,30,40以外)の場合

{
	"error": "wrong_parameter",
	"error_description": "must set age parameter in 20,30,40 when set period parameter"
}

genreIDsexが設定されている場合

{
	"error": "wrong_parameter",
	"error_description": "no permit setting genreId and sex parameter at the same time"
}

genreIDとageが設定されている場合

{
	"error": "wrong_parameter",
	"error_description": "no permit setting genreId and age parameter at the same time"
}
404 データが見つからない場合

一切のデータが見つからない場合

{
    "error": "not_found",
    "error_description": "not found"
}

ランキングインフォーメーションにおけるアイテム数が3つよりも少ない場合

{
    "error": "not_found",
    "error_description": "This genre data does not exist"
}
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 として 'IchibaItemRanking' を指定してください。
// ここでは例として keyword に、うどんを指定しています。
$response = $client->execute('IchibaItemRanking', array(
  'genreId' => '100227'
));

// レスポンスが正常かどうかを isOk() で確認することができます
if ($response->isOk()) {
    // 配列アクセスで情報を取得することができます。
    echo $response['title']."ランキングタイトル\n";

    // foreach で商品情報を順次取得することができます。
    foreach ($response as $item) {
        echo $item['itemName']."\n";
    }
} else {
    // getMessage() でレスポンスメッセージを取得することができます
    echo 'Error:'.$response->getMessage();
}