Top > API一覧 > 楽天商品検索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を指定することで出力されます。

フィールド名keyword, sortに対応する[value]はUTF-8でURLエンコードされている必要があります。
(リクエストURL全体をエンコードするのではなく、[value]部分を個別にエンコードしてください。)
たとえば、「福袋」という検索キーワードで検索し、結果を価格が安い順に並べたい(sort=+itemPrice)場合のリクエストURLは下記になります。(実際には改行せずに1行につなげてリクエストしてください。)

http://api.rakuten.co.jp/rws/3.0/rest?
developerId=[YOUR_developerID]
&operation=ItemSearch
&version=2010-09-15
&keyword=%E7%A6%8F%E8%A2%8B
&sort=%2BitemPrice

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

SOAPについて


SOAPを用いることで、より高度なアプリの開発が可能となります。SOAPに関しての詳細は「楽天商品検索API(ItemSearch)SOAP開発用」をご覧ください。※version:2010-09-15は、現在SOAP未対応です。

入力パラメーター


楽天商品検索API(ItemSearch) 入力パラメーター version:2010-09-15

ID 項目名 パラメーター 型(括弧内は最大バイト数) 必須 デフォルト 備考
区分:共通パラメーター
1 デベロッパID developerId String Affiliate対応あり - デベロッパーID(こちらで確認できるアプリケーションIDのことです)
2 アフィリエイトID affiliateId String - 指定無し アフィリエイトID
3 操作 operation String Affiliate対応あり - 使用するAPIの操作名:ItemSearch
4 コールバック関数名 callBack String - 指定無し JSONPとして出力する際のコールバック関数名
(UTF-8でURLエンコードした文字列)
英数字、「.(ドット)」、「_(アンダーバー)」、「[(中括弧)」、「](中括弧)」のいずれか1文字以上
区分:サービス固有パラメーター
1 検索キーワード keyword String Affiliate対応あり
(*1)
- UTF-8でURLエンコードした文字列
(*1)検索キーワード、ジャンルIDのいずれかが指定されていることが必須です。
2 バージョン version String Affiliate対応あり - 2010-09-15
3 ショップコード shopCode String - 指定無し ショップごとのURL
(http://
www.rakuten.co.jp/[xyz])におけるxyzのこと
4 ジャンルID genreId long Affiliate対応あり
(*1)
0 楽天市場におけるジャンルを特定するためのID
ジャンル名、ジャンルの親子関係を調べたい場合は、「楽天ジャンル検索API(GenreSearch)」をご利用ください
(*1)検索キーワード、ジャンルIDのいずれかが指定されていることが必須です。
5 1ページあたりの取得件数 hits int - 30 1から30までの整数
6 取得ページ page int - 1 1から100までの整数
7 ソート sort String - standard +affiliateRate:
アフィリエイト料率順(昇順)
-affiliateRate:
アフィリエイト料率順(降順)
+reviewCount:
レビュー件数順(昇順)
-reviewCount:
レビュー件数順(降順)
+reviewAverage:
レビュー平均順(昇順)【NEW】
-reviewAverage:
レビュー平均順(降順)【NEW】
+itemPrice:
価格順(昇順)
-itemPrice:
価格順(降順)
+updateTimestamp:
商品更新日時順(昇順)
-updateTimestamp:
商品更新日時順(降順)
standard:
楽天標準ソート順
※UTF-8でURLエンコードされている必要があります。
8 最小価格 minPrice long - 指定無し 0以上の整数
9 最大価格 maxPrice long - 指定無し 0以上の整数
maxPriceはminPriceより大きい必要がある
10 販売可能 availability int(1) - 1 0:すべての商品
1:販売可能な商品のみ
11 検索フィールド field int(1) - 1 0:検索対象が広い(同じ検索キーワードでも多くの検索結果が得られる)
1:検索対象範囲が限定される(同じ検索キーワードでも少ない検索結果が得られる)
12 キャリア carrier int(1) - 0 PC用の情報を返すのか、モバイル用の情報を返すのかを選択
PC: 0
mobile: 1
13 商品画像有無フラグ imageFlag int(1) - 0 0 : すべての商品を検索対象とする
1 : 商品画像ありの商品のみを検索対象とする
14 OR検索フラグ orFlag int(1) - 0 複数キーワードが設定された場合に、AND検索、OR検索のいずれかが選択可能。
0:AND検索
1:OR検索
※ただし、(A and B) or Cといった複雑な検索条件設定は指定不可。
15 除外キーワード NGKeyword String - 指定無し 検索結果から除外したいキーワード
UTF-8でURLエンコードした文字列
16 ジャンルごとの商品数取得フラグ genreInformationFlag int(1) - 0 0 :ジャンルごとの商品数の情報を取得しない
1 :ジャンルごとの商品数の情報を取得する
17 購入種別 purchaseType int(1) - 0 商品を購入方法別に検索する事が可能
0:通常購入
1:定期購入(定期購入とは、お客様の欲しい商品が欲しいサイクルで買えるサービスです。)
2:頒布会購入(頒布会購入とは、ショップがセレクトした商品を、ショップが決めた回数でお届けするサービスです。)
18 海外配送フラグ shipOverseasFlag int(1) - 0 0 :すべての商品
1 :海外配送可能な商品のみ
19 海外配送対象地域 shipOverseasArea String - ALL 配送可能地域での絞込みが可能
配送地域コードについては別途「海外配送対象地域 コード一覧」を参照してください
※海外配送フラグで「1」が指定されたときのみ利用可能
20 あす楽フラグ asurakuFlag int(1) - 0 0 :すべての商品
1 :あす楽対応可能な商品のみ
21 あす楽配送対象地域 asurakuArea int - 0 配送可能地域での絞込みが可能
配送地域コードについては別途「あす楽配送対象地域 コード一覧」を参照してください
※あす楽フラグで「1」が指定されたときのみ利用可能
22 ポイント倍付けフラグ【NEW】 pointRateFlag int(1) - 0 0 :すべての商品
1 :ポイント倍付け商品のみ
23 商品別ポイント倍付け【NEW】 pointRate int - 指定なし 2から10までの整数 例)5 →ポイント5倍
商品別ポイント倍付けについてはこちらをご確認ください。
※ポイント倍付け商品フラグに「1」が指定されたときのみ利用可能
24 送料フラグ【NEW】 postageFlag int(1) - 0 0 :すべての商品
1 :送料込み/送料無料の商品のみ
25 クレジットカード利用可能フラグ【NEW】 creditCardFlag int(1) - 0 0 :すべての商品
1 :クレジットカード利用可能な商品のみ

出力パラメーター


楽天商品検索API(ItemSearch) 出力パラメーター version:2010-09-15

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 全体情報 検索数 count 検索結果の総商品数
2 ページ番号 page 現在のページ番号
3 ページ内商品始追番 first 検索結果の何件目からか
4 ページ内商品終追番 last 検索結果の何件目までか
5 ヒット件数番 hits 1度に返却する商品数
6 キャリア情報 carrier PC=0 or mobile=1
7 総ページ数 pageCount 最大100
8 商品情報
(全体:<Items> ~ </Items> 、個別商品:<Item> ~ </Item>)
商品情報詳細 商品名 itemName 従来の商品名を表示させたい場合は、「catchcopy+itemname」で表示してください。
※キャリア(carrier)の指定により返却情報が異なります。
9 キャッチコピー catchcopy
10 商品コード itemCode  
11 商品価格 itemPrice  
12 商品説明文 itemCaption ※キャリア(carrier)の指定により返却情報が異なります。
13 商品URL itemUrl ※キャリア(carrier)の指定により返却情報が異なります。
14 アフィリエイトURL affiliateUrl (入力パラメーターにアフィリエイトIDが含まれていた時のみ)
※carrierパラメーターの指定に関わらずPC/mobile両対応のURLを返却
15 商品画像有無フラグ imageFlag 0:商品画像無し
1:商品画像有り
16 商品画像64x64URL smallImageUrl (画像サイズ64px*64px)
17 商品画像128x128URL mediumImageUrl (画像サイズ128px*128px)
18 販売可能フラグ availability 0:販売不可能
1:販売可能
19 消費税フラグ taxFlag 0:税込
1:税別
20 送料フラグ postageFlag 0:送料込
1:送料別
21 クレジットカード利用可能フラグ creditCardFlag 0:カード利用不可
1:カード利用可
22 ショップオブザイヤーフラグ shopOfTheYearFlag 1:ショップオブザイヤー受賞店舗
23 海外配送フラグ shipOverseasFlag 0:海外配送不可
1:海外配送可能
24 海外配送対象地域 shipOverseasArea 「/」(スラッシュ)区切りで対応国が表示されます。
25 あす楽フラグ asurakuFlag 0:翌日配送不可
1:翌日配送可能
※「あす楽」の詳細はこちらをご覧ください
26 あす楽配送対象地域 asurakuArea 「/」(スラッシュ)区切りで対応地域が表示されます。
27 アフィリエイト利用利率 affiliateRate  
28 販売開始時刻 startTime タイムセールが設定されている場合のみ(YYYY-MM-DD HH:MM形式)
29 販売終了時刻 endTime タイムセールが設定されている場合のみ(YYYY-MM-DD HH:MM形式)
30 レビュー件数 reviewCount  
31 レビュー平均 reviewAverage  
32 商品別ポイント倍付け pointRate 例)5 →ポイント5倍
商品別ポイント倍付けについてはこちらをご確認ください。
※ポイント倍付けの終了日時がリクエスト日時から24時間後以降の場合のみ表示されます。
33 商品別ポイント倍付け開始日時 pointRateStartTime 商品別ポイント倍付け(pointRate)の適用開始日時
※ポイント倍付けの終了日時がリクエスト日時から24時間後以降の場合のみ表示されます。
34 商品別ポイント倍付け終了日時 pointRateEndTime 商品別ポイント倍付け(pointRate)の適用終了日時
※ポイント倍付けの終了日時がリクエスト日時から24時間後以降の場合のみ表示されます。
35 店舗情報 店舗名 shopName  
36 店舗コード shopCode 店舗ごとのURL (http://
www.rakuten.co.jp/[xyz])
におけるxyzのこと
37 店舗URL shopUrl httpからはじまる店舗ごとのURL
38 ジャンル情報 ジャンルID genreId  
39 ジャンルごとの商品数
(全体:<GenreInformation>
~ </GenreInformation>
、個別ジャンル:<parent> ~ </parent>もしくは<current> ~ </current>もしくは<child> ~ </child>)
親ジャンル - parent 入力したジャンルIDの親ジャンル
40 ジャンルID genreId  
41 ジャンル名 genreName  
42 ジャンル階層 genreLevel  
43 自ジャンル - current ユーザの入力したジャンルID
44 ジャンルID genreId  
45 ジャンル名 genreName  
46 ジャンルに紐づく商品数 itemCount  
47 ジャンル階層 genreLevel  
48 子ジャンル - child ユーザの入力したジャンルIDの子ジャンル
複数の子ジャンルがある場合は<child> ~ </child>が複数生成される
入力が「genreId=0」の時はgenreLevel=1の ジャンルが<child> ~ </child>に表示される
49 ジャンルID genreId  
50 ジャンル名 genreName  
51 ジャンルに紐づく商品数 itemCount  
52 ジャンル階層 genreLevel  

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


商品購入時に付与される楽天スーパーポイントは、通常、購入金額の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(モバイル)]

エラー


エラーが起こった際は、出力中の「共通パラメーター」のStatusに下表に記載されたいずれかが表示されます。

Statusでの表示 内容
NotFound 検索結果が存在しない。
ServerError 楽天ウェブサービス側のエラー。
ClientError デベロッパーの入力に起因するエラー。
Maintenance メンテナンス。
AccessForbidden リクエスト回数制限オーバー。
※しばらく時間を空けて、再度ご利用ください