|
楽天商品ランキングAPIとは
楽天商品ランキングAPIは、楽天市場内のコンテンツ「ランキング市場」の情報を取得することが可能なAPIです。
デベロッパーはジャンル別や性別、年代別などで売れている商品の情報を取得することができます。 |
|
|
■リクエストURL（REST／JSON形式の場合）
http://api.rakuten.co.jp/rws/3.0/rest?[parameter]=[value]...
http://api.rakuten.co.jp/rws/3.0/json?[parameter]=[value]...
※JSONP形式は、JSON形式で入力パラメーターにcallBackを指定することで出力されます。
たとえば、以下の3つのような場合のリクエストURLは下記になります。（実際には改行せずに1行につなげてリクエストしてください。）
(1)総合ランキングの情報を取得する場合（サービス固有パラメーターを無指定）
http://api.rakuten.co.jp/rws/3.0/rest?
developerId=[YOUR_developerID]
&operation=ItemRanking
&version=2010-08-05
(2)「洋菓子（genreId=100283）」ジャンルのランキング情報を取得する場合（ジャンルパラメーターを指定）
http://api.rakuten.co.jp/rws/3.0/rest?
developerId=[YOUR_developerID]
&operation=ItemRanking
&version=2010-08-05
&genreId=100283
(3)「20代の女性」のランキング情報を取得する場合（年代別・性別パラメーターを指定）
http://api.rakuten.co.jp/rws/3.0/rest?
developerId=[YOUR_developerID]
&operation=ItemRanking
&version=2010-08-05
&age=20
&sex=1
| ※ |
短い時間の間に大量に、同一のリクエストURLへアクセスすると、一定時間利用できなくなる場合がございます。テストの際にはご注意ください。 |
■利用上の注意
※入力パラメーターに関する注意事項（2010年06月現在）
ランキング情報を取得する際には、「ジャンルID」「年代別」「性別」のサービス固有パラメーターを指定して行ないます。
| （1） |
「ジャンルID」
「ジャンルID」のみが指定された場合は、入力されたジャンルのランキング情報が表示されます。
「ジャンルID」は、「年代別」「性別」と同時に指定できません。 |
| （2） |
「年代別」
「年代別」のみが指定された場合は、各年代別の総合ランキングが表示されます。
また「年代別」パラメーターは、同時に「性別」を指定することが可能で、両方が指定された場合、各性別の年代別ランキングが表示されます。 |
| （3） |
「性別」
「性別」のみが指定された場合は、各性別の総合ランキングが表示されます。
また「性別」パラメーターは、同時に「年代別」を指定することが可能で、両方が指定された場合、各性別の年代別ランキングが表示されます。 |
| （4） |
無指定の場合は「総合ランキング」が表示されます。 |
※ランキング順位と総数が「ランキング市場」と一部異なる場合があります。
取得できるランキング情報は、「ランキング市場」と同じものとなりますが、「ランキング市場」でランクインしている商品の商品ページが何らかの理由で削除されている場合、楽天商品ランキングAPI(version:2010-08-05)ではその順位を飛ばして表示しております。よって「ランキング市場」と一部、総数が異なる場合があります。予めご了承ください。
|
■入力パラメーター
| 楽天商品ランキングAPI（ItemRanking) 入力パラメーター version:2010-08-05 |
| 区分 |
ID |
項目名 |
フィールド名 |
型
(括弧内は
最大
バイト数） |
必須 |
デフォルト |
備考 |
共
通
パ
ラ
メ
|
タ
| |
1 |
デベロッパID |
developerId |
String |
○ |
--- |
デベロッパーID |
| 2 |
アフィリエイトID |
affiliateId |
String |
- |
指定無し |
アフィリエイトID |
| 3 |
操作 |
operation |
String |
○ |
--- |
使用するAPIの操作名：
ItemRanking |
| 4 |
コールバック関数名 |
callBack |
String |
- |
指定無し |
JSONPとして出力する際のコールバック関数名
（UTF-8でURLエンコードした文字列）
英数字、「.(ドット)」、「_(アンダーバー)」、「[(中括弧)」、「](中括弧)」のいずれか1文字以上 |
サ
|
ビ
ス
固
有
パ
ラ
メ
|
タ
| |
1 |
バージョン |
version |
String |
○ |
--- |
2010-08-05 |
| 2 |
ジャンルID |
genreId |
long |
(*1)
(*3) |
--- |
楽天市場におけるジャンルを特定するためのID
ジャンル名、ジャンルの親子関係を調べたい場合は、「楽天ジャンル検索API(GenreSearch)」をご利用ください
(*1)ジャンルID、性別、年代別のいずれも指定されない場合「総合ランキング」が表示されます。
(*3)その他入力パラメーター指定の際の詳細は、本ページ内の「利用上の注意」内の「入力パラメーターに関する注意事項」をご覧ください |
| 3 |
年代別 |
age |
int |
(*1)
(*2)
(*3) |
--- |
10：10代
20：20代
30：30代
40：40代
50：50代以上
(*1)ジャンルID、性別、年代別のいずれも指定されない場合「総合ランキング」が表示されます。
(*2)年代別、性別は同時に両方を指定可能です
(*3)その他入力パラメーター指定の際の詳細は、本ページ内の「利用上の注意」内の「入力パラメーターに関する注意事項」をご覧ください |
| 4 |
性別 |
sex |
int |
(*1)
(*2)
(*3) |
--- |
0：男性
1：女性
(*1)ジャンルID、性別、年代別のいずれも指定されない場合「総合ランキング」が表示されます。
(*2)年代別、性別は同時に両方を指定可能です
(*3)その他入力パラメーター指定の際の詳細は、本ページ内の「利用上の注意」内の「入力パラメーターに関する注意事項」をご覧ください |
| 5 |
キャリア |
carrier | int(1) |
- |
0 |
PC用の情報を返すのか、モバイル用の情報を返すのかを選択
PC:0
mobile:1 |
| 6 |
取得ページ |
page |
int |
- |
1 |
1から10までの整数
※30位よりも下のランキングに対応している場合に指定可能
|
|
■出力パラメーター
| 楽天商品ランキングAPI（ItemRanking) 出力パラメーター version:2010-08-05 |
| 区分 |
ID |
分類 |
項目名 |
フィールド名 |
備考 |
共
通
パ
ラ
メ
|
タ
| |
1 |
ARG |
--- |
User-Agent |
Valueにはユーザのユーザエージェントが表示される |
| 2 |
--- |
developerId |
ValueにはデベロッパーIDが表示される |
| 3 |
--- |
affiliateId |
Valueにはユーザの指定したアフィリエイトIDが表示される |
| 4 |
--- |
operation |
Valueにはユーザの指定した操作名が表示される |
| 5 |
--- |
version |
Valueにはユーザの指定した操作のバージョンが表示される |
| 6 |
Status |
--- |
Status |
Success / NotFound / ServerError/
ClientError / Maintenance のいずれか |
| 7 |
StatusMsg |
--- |
StatusMsg |
Statusに特化したメッセージを出力 |
サ
|
ビ
ス
固
有
パ
ラ
メ
|
タ
| |
1 |
全体情報 |
ランキングタイトル |
title |
|
| 2 |
最終更新時間 |
lastBuildDate |
|
| 3 |
--- |
順位 |
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)の指定により返却情報が異なります。 |
| 11 |
アフィリエイトURL【NEW】 |
affiliateUrl |
（入力パラメーターにアフィリエイトIDが含まれていた時のみ）
※carrierパラメーターの指定に関わらずPC/mobile両対応のURLを返却
|
| 12 |
商品画像有無フラグ |
imageFlag |
0：商品画像無し
1：商品画像有り |
| 13 |
商品画像64x64URL |
smallImageUrl |
（画像サイズ64px*64px） |
| 14 |
商品画像128x128URL |
mediumImageUrl |
（画像サイズ128px*128px） |
| 15 |
販売可能フラグ |
availability |
0：販売不可能
1：販売可能 |
| 16 |
消費税フラグ |
taxFlag |
0：税込
1：税別 |
| 17 |
送料フラグ |
postageFlag |
0：送料込
1：送料別 |
| 18 |
クレジットカード利用可能フラグ |
creditCardFlag |
0：カード利用不可
1：カード利用可 |
| 19 |
ショップオブザイヤーフラグ |
shopOfTheYearFlag |
1：ショップオブザイヤー受賞店舗 |
| 20 |
海外配送フラグ |
shipOverseasFlag |
0：海外配送不可
1：海外配送可能 |
| 21 |
海外配送対象地域 |
shipOverseasArea |
「/」(スラッシュ)区切りで対応国が表示されます。 |
| 22 |
あす楽フラグ |
asurakuFlag |
0：翌日配送不可
1：翌日配送可能
※「あす楽」の詳細はこちらをご覧ください |
| 23 |
あす楽配送対象地域 |
asurakuArea |
「/」(スラッシュ)区切りで対応地域が表示されます。 |
| 24 |
アフィリエイト利用利率 |
affiliateRate |
|
| 25 |
販売開始時刻 |
startTime |
タイムセールが設定されている場合のみ（YYYY-MM-DD HH:MM形式） |
| 26 |
販売終了時刻 |
endTime |
タイムセールが設定されている場合のみ（YYYY-MM-DD HH:MM形式） |
| 27 |
レビュー件数 |
reviewCount |
|
| 28 |
レビュー平均 |
reviewAverage |
|
| 29 |
商品別ポイント倍付け【NEW】 |
pointRate |
例）5 →ポイント5倍
商品別ポイント倍付けについてはこちらをご確認ください。
|
| 30 |
商品別ポイント倍付け開始日時【NEW】 |
pointRateStartTime |
商品別ポイント倍付け(pointRate)の適用開始日時
|
| 31 |
商品別ポイント倍付け終了日時【NEW】 |
pointRateEndTime |
商品別ポイント倍付け(pointRate)の適用終了日時
|
| 32 |
店舗情報 |
店舗名 |
shopName |
|
| 33 |
店舗コード |
shopCode |
店舗ごとのURL （http://www.rakuten.co.jp/[xyz]） におけるxyzのこと |
| 34 |
店舗URL |
shopUrl |
httpからはじまる店舗ごとのURL |
| 35 |
ジャンル情報 |
ジャンルID |
genreId |
|
|
■商品別ポイント倍付けに関して
商品購入時に付与される楽天スーパーポイントは、通常、購入金額の1%ですが、ポイント倍付けが設定されている商品は、設定期間中に商品を購入すると、設定された倍率が適用されます。ポイント倍付けの詳しい仕組みは、こちらでご確認ください。
ショップが設定するポイント倍付けには、特定商品のみに適用される商品別ポイント倍付けと、特定ショップの全商品に適用されるショップ別ポイント倍付けの2種類があります。本APIでは、現在のところ、商品別ポイント倍付けの情報を提供しています。
■アフィリエイトに関して
デベロッパーは、楽天商品ランキングAPIから取得した商品情報からアフィリエイトURLを作成することが可能です。リンク先にそのアフィリエイトURLを指定することで、楽天アフィリエイト経由の成果報酬を獲得することができます。
「アフィリエイト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（モバイル）]
|
■エラー
エラーが起こった際は、出力中の「共通パラメーター」のStatusに下表に記載されたいずれかが表示されます。
| Statusでの表示 |
内容 |
| NotFound |
検索結果が存在しない。 |
| ServerError |
楽天ウェブサービス側のエラー。 |
| ClientError |
デベロッパーの入力に起因するエラー。 |
| Maintenance |
メンテナンス。 |
|
■過去のバージョン
本APIの過去のバージョンは下記からご覧いただけます。
|
