Top  > API一覧 > 楽天オークション商品検索API

楽天オークション商品検索APIは、楽天オークションの商品情報を取得することが可能なAPIです。デベロッパーはキーワードでの商品検索をはじめ、ジャンル別や商品の状態などの絞り込み検索も可能となります。

リクエストURL


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

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

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

http://app.rakuten.co.jp/services/api/AuctionItem/Search/20130905?
applicationId=[アプリID]&
keyword=%E7%A6%8F%E8%A2%8B&
sort=%2BbidCount

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

入力パラメーター


楽天オークション商品検索API 入力パラメーター version:2013-09-05

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 検索キーワード keyword String Affiliate対応あり
(*1)
-

UTF-8でURLエンコードした文字列

  • 検索キーワード全体は半角で128文字以内で指定する必要があります。
  • 検索キーワードは半角スペースで区切ることができ、デフォルトではAND条件 (すべてのキーワードが含まれるものを検索 ) になります。 もし、OR条件 (いずれかのキーワードが含まれるものを検索) を利用したい場合は、 orFlag1 に設定してください。
  • 各検索キーワードは半角2文字 もしくは 全角1文字 以上で指定する必要があります。
  • また例外として、各検索キーワードがひらがな・カタカナ・記号の場合は2文字以上で指定する必要があります。

(*1)検索キーワード、楽天オークションジャンルIDのいずれかが指定されていることが必須です

2 楽天オークションジャンルID auctionGenreId long Affiliate対応あり
(*1)
0 楽天オークションにおけるジャンルを特定するためのID。
ジャンル名、ジャンルの親子関係を調べたい場合は、「楽天オークションジャンル検索API」をご利用ください。
(*1)検索キーワード、楽天オークションジャンルIDのいずれかが指定されていることが必須です
3 1ページあたりの取得件数 hits int - 30 1から30までの整数
4 取得ページ page int - 1 1から100までの整数
5 最小現在価格 minItemPrice long - 指定無し 0以上の整数
6 最大現在価格 maxItemPrice long - 指定無し 0以上の整数 maxItemPriceはminItemPriceより大きい必要がある
7 ソート sort String - standard newArrivals:
新着順
+endTime:
残り時間順(昇順)
-endTime:
残り時間順(降順)
+itemPrice:
現在価格順(昇順)
-itemPrice:
現在価格順(降順)
+blowPrice:
即落価格順 (昇順)
-blowPrice:
即落価格順 (降順)
+bidCount:
入札件数順(昇順)
-bidCount:
入札件数順(降順)
+affiliateRate:
アフィリエイト料率順(昇順)
-affiliateRate:
アフィリエイト料率順(降順)
+startTime:
オークション開始時間 (昇順)
-startTime:
オークション開始時間 (降順)
standard:
楽天標準ソート順 (注目のオークションを加味した、残り時間降順)
※UTF-8でURLエンコードされている必要があります。
8 即落フラグ blowFlag int(1) - 0 0:すべての商品を検索対象とする
1:即落商品のみ検索対象とする
※即落商品とは、オークションの入札期間終了を待たずに即落札することが可能な商品のことです。
9 最小即落価格 minBlowPrice long - 指定無し 0以上の整数
10 最大即落価格 maxBlowPrice long - 指定無し 0以上の整数 maxBlowPriceはminBlowPriceより大きい必要がある
11 対象商品識別フラグ itemType int(1) - 0 0:すべての商品を検索対象とする
1:個人の出品商品のみ検索対象とする
2:楽天市場店舗の出品商品のみ検索対象とする
3:楽オク事業者の出品商品のみ検索対象とする
(複数指定可 例:0,1,2)
12 商品状態フラグ newFlag int(1) - 0 0:すべて
1:中古のみ
2:新品のみ
13 1円スタートフラグ y1startFlag int(1) - 0 0:すべて
1:1円スタート商品のみ
14 匿名配送対応フラグ anonymityFlag int(1) - 0 0:すべて
1:匿名配送に対応している商品のみ
15 送料無料フラグ postageFreeFlag int(1) - 0 0:すべて
1:送料無料
16 クローズド除外フラグ closedFlag int(1) - 0 0:すべて
1:クローズドを除く
17 入札状況 bidStatus int(1) - 0 0:すべて
1:入札あり
2:入札なし
18 検索フィールド field int(1) - 1 0:検索対象が広い(同じ検索キーワードでも多くの検索結果が得られる)
1:検索対象範囲が限定される(同じ検索キーワードでも少ない検索結果が得られる)
19 キャリア carrier int(1) - 0 PC用の情報を返すのか、モバイル用の情報を返すのかを選択
PC: 0
mobile: 1
20 商品画像有無フラグ imageFlag int(1) - 0 0:すべての商品を検索対象とする
1:商品画像ありの商品のみを検索対象とする
21 OR検索フラグ orFlag int(1) - 0 複数キーワードが設定された場合に、AND検索、OR検索のいずれかが選択可能。
0:AND検索
1:OR検索
※ただし、(A and B) or Cといった複雑な検索条件設定は指定不可。
22 除外キーワード NGKeyword String - 指定無し

検索結果から除外したいキーワード

UTF-8でURLエンコードした文字列

形式については keyword と同様

23 目立ち
アイコン
【NEW】
noticeIcon String - 指定無し 0:目立ちアイコン 表示なし
1:目立ちアイコン 美品
2:目立ちアイコン 激安
3:目立ちアイコン 人気
4:目立ちアイコン 限定
5:目立ちアイコン 非売
6:目立ちアイコン 新製
7:目立ちアイコン 鑑定
(複数指定可 例:0,1,2)
24 ジャンルごと
の商品数
取得フラグ
genreInformationFlag int(1) - 0 0:ジャンルごとの商品数の情報を取得しない
1:ジャンルごとの商品数の情報を取得する
25 値下げ設定ありフラグ autoPriceDownFlag int(1) - 0 0:すべての商品
1:値下げ設定あり商品のみ
26 値下済み商品フラグ priceDownExecFlag int(1) - 0 0:すべての商品
1:値下げ済み商品のみ

出力パラメーター


楽天オークション商品検索API 出力パラメーター version:2013-09-05

区分:サービス固有パラメーター
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」で表示してください。
9 キャッチコピー catchcopy ※キャリア(carrier)の指定により返却情報が
異なります。
⇒carrier「1」の際はモバイル用の商品名・
キャッチコピーを返却する
10 オークション商品コード itemCode  
11 出品商品現在価格 itemPrice  
12 最低入札価格 minPrice  
13 商品説明文 itemCaption ※キャリア(carrier)の指定により返却情報が
異なります。
⇒carrier「1」の際はモバイル用の商品説明文
を返却する
14 商品URL itemUrl ※キャリア(carrier)の指定により返却情報が
異なります。
⇒carrier「0」の際はPC用のURLを返却する
15 アフィリエイトURL affiliateUrl (入力パラメーターにアフィリエイトIDが
含まれていた時のみ)
※carrierパラメーターの指定に関わらずPC/mobile両対応のURLを返却
16 商品画像有無フラグ imageFlag 0:商品画像無し
1:商品画像有り
17 商品画像 64x64URL smallImageUrl (画像サイズ 64px*64px)
18 商品画像 128x128URL mediumImageUrl (画像サイズ 128px*128px)
19 即落フラグ blowFlag 0:通常のオークション商品
1:即落商品
20 即落価格 blowPrice 即落商品だった場合のみ表示
21 結果フラグ resultFlag 0:取引中の場合
1:取引が終了した場合
22 入札件数 bidCount  
23 消費税フラグ taxFlag 0:税別
1:税込
2:税なし
3:非課税
24 送料フラグ postageFlag 0:送料込
1:送料別
25 配送タイプ deliveryType 0:条件なし
1:送料無料で配送
2:匿名配送
3:匿名配送かつ送料無料で配送
26 クレジットカード利用可能フラグ creditCardFlag 0:カード利用不可
1:カード利用可
27 アフィリエイト利用利率 affiliateRate  
28 入札開始時間 startTime 現在時刻よりも未来の時間は、 startTime に設定できません。
29 入札終了時間 endTime  
30 注目のオークション設定金額 searchwordcost  
31 出品者情報 出品者名 shopName  
32 出品者種別フラグ shopStatusFlag 1:個人 2:楽天市場店舗 3:楽オク事業者
33 ジャンル情報 楽天オークションジャンルID auctionGenreId  
34 目立ち
アイコン
【NEW】
商品アイコン noticeIcon 0:目立ちアイコン 表示なし
1:目立ちアイコン 美品
2:目立ちアイコン 激安
3:目立ちアイコン 人気
4:目立ちアイコン 限定
5:目立ちアイコン 非売
6:目立ちアイコン 新製
7:目立ちアイコン 鑑定
35 背景色 noticeBgColor
0:背景色なし
1:背景色あり
36 大文字 noticeLargeChar 0:大文字なし
1:大文字あり
37 ジャンルごとの商品数
(全体:<GenreInformation>
~ </GenreInformation> 、
個別ジャンル:<parent> ~ </parent>
もしくは<current> ~ </current>
もしくは<children> ~ </children>)
親ジャンル - parent 入力したジャンルIDの親ジャンル
38 楽天オークションジャンルID auctionGenreId  
39 楽天オークションジャンル名 auctionGenreName  
40 ジャンル階層 genreLevel  
41 自ジャンル - current ユーザの入力したジャンルID
42 楽天オークションジャンルID auctionGenreId  
43 楽天オークションジャンル名 auctionGenreName  
44 ジャンルに紐づく商品数 itemCount  
45 ジャンル階層 genreLevel  
46 子ジャンル - child ユーザの入力したジャンルIDの子ジャンル
複数の子ジャンルがある場合は<children> ~ </children>内に<child> ~ </child>が複数生成される
入力が「auctionGenreId=000」の時はgenreLevel=1のジャンルが<child> ~ </child>に表示される
47 楽天オークションジャンルID auctionGenreId  
48 楽天オークションジャンル名 auctionGenreName  
49 ジャンルに紐づく商品数 itemCount  
50 ジャンル階層 genreLevel  

アフィリエイトに関して


デベロッパーは、楽天オークション商品検索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"
}
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>