トップ > API一覧 > 楽天商品検索API

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

楽天商品検索APIは、楽天市場の商品(共同購入商品・オークション商品・フリマ商品・楽天オークション の個人間オークション商品は除く。)の情報を取得することが可能なAPIです。デベロッパーはキーワードでの商品検索をはじめ、ショップ別・ジャンル別の 絞込み検索も可能となります。
楽天商品検索APIは、過去の楽天商品検索APIにはなかった、 出力パラメーター指定や、商品コード検索、レビューあり商品の検索、配送日指定対応商品の検索などが可能になりました。

リクエストURL


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

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

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

https://app.rakuten.co.jp/services/api/IchibaItem/Search/20130424?
applicationId=[アプリID]
&keyword=%E7%A6%8F%E8%A2%8B
&sort=%2BitemPrice

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

入力パラメーター


楽天商品検索API 入力パラメーター version:2013-04-24

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文字以上
区分:サービス固有パラメーター
1 検索キーワード keyword String 必須
(*1)
-

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

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

(*1)検索キーワード、ジャンルID、商品コードのいずれかが指定されていることが必須です。

2 ショップコード shopCode String - - ショップごとのURL(http://www.rakuten.co.jp/[xyz])におけるxyzのこと
3 ジャンルID genreId long 必須
(*1)
0 楽天市場におけるジャンルを特定するためのID
ジャンル名、ジャンルの親子関係を調べたい場合は、「楽天ジャンル検索API」をご利用ください
(*1)検索キーワード、ジャンルID、商品コードのいずれかが指定されていることが必須です。
4 1ページあたりの取得件数 hits int - 30 1から30までの整数
5 取得ページ page int - 1 1から100までの整数
6 ソート sort String - standard +affiliateRate:
アフィリエイト料率順(昇順)
-affiliateRate:
アフィリエイト料率順(降順)
+reviewCount:
レビュー件数順(昇順)
-reviewCount:
レビュー件数順(降順)
+reviewAverage:
レビュー平均順(昇順)
-reviewAverage:
レビュー平均順(降順)
+itemPrice:
価格順(昇順)
-itemPrice:
価格順(降順)
+updateTimestamp:
商品更新日時順(昇順)
-updateTimestamp:
商品更新日時順(降順)
standard:
楽天標準ソート順
※UTF-8でURLエンコードされている必要があります。
7 最小価格 minPrice long - - 1以上999,999,999以下の整数
8 最大価格 maxPrice long - - 1以上999,999,999以下の整数
maxPriceはminPriceより大きい必要がある
9 販売可能 availability int(1) - 1 0:すべての商品
1:販売可能な商品のみ
10 検索フィールド field int(1) - 1 0:検索対象が広い(同じ検索キーワードでも多くの検索結果が得られる)
1:検索対象範囲が限定される(同じ検索キーワードでも少ない検索結果が得られる)
11 キャリア carrier int(1) - 0 PC用の情報を返すのか、モバイル用の情報を返すのか、スマートフォン用の情報を返すのか、を選択
PC: 0
mobile: 1
smartphone: 2
12 商品画像有無フラグ imageFlag int(1) - 0 0 : すべての商品を検索対象とする
1 : 商品画像ありの商品のみを検索対象とする
13 OR検索フラグ orFlag int(1) - 0 複数キーワードが設定された場合に、AND検索、OR検索のいずれかが選択可能。
0:AND検索
1:OR検索
※ただし、(A and B) or Cといった複雑な検索条件設定は指定不可。
14 除外キーワード NGKeyword String - -

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

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

形式については keyword と同様

15 購入種別 purchaseType int(1) - 0 商品を購入方法別に検索する事が可能
0:通常購入
1:定期購入(定期購入とは、お客様の欲しい商品が欲しいサイクルで買えるサービスです。)
2:頒布会購入(頒布会購入とは、ショップがセレクトした商品を、ショップが決めた回数でお届けするサービスです。)
16 海外配送フラグ shipOverseasFlag int(1) - 0 0 :すべての商品
1 :海外配送可能な商品のみ
17 海外配送対象地域 shipOverseasArea String - 指定無し 配送可能地域での絞込みが可能
配送地域コードについては別途「海外配送対象地域 コード一覧」を参照してください
※海外配送フラグで「1」が指定されたときのみ利用可能
18 あす楽フラグ asurakuFlag int(1) - 0 0 :すべての商品
1 :あす楽対応可能な商品のみ
19 あす楽配送対象地域 asurakuArea int - 0 配送可能地域での絞込みが可能
配送地域コードについては別途「あす楽配送対象地域 コード一覧」を参照してください
※あす楽フラグで「1」が指定されたときのみ利用可能
20 ポイント倍付けフラグ pointRateFlag int(1) - 0 0 :すべての商品
1 :ポイント倍付け商品のみ
21 商品別ポイント倍付け pointRate int - - 2から10までの整数 例)5 →ポイント5倍
商品別ポイント倍付けについてはこちらをご確認ください。
※ポイント倍付け商品フラグに「1」が指定されたときのみ利用可能
22 送料フラグ postageFlag int(1) - 0 0 :すべての商品
1 :送料込み/送料無料の商品のみ
23 クレジットカード利用可能フラグ creditCardFlag int(1) - 0 0 :すべての商品
1 :クレジットカード利用可能な商品のみ
24 商品コード itemCode String 必須
(*1)
- 商品検索APIや、楽天商品ランキングAPIや、お気に入りブックマーク取得APIの出力パラメータに含まれまれる
「shop:1234」という形式の値
(*1)検索キーワード、ジャンルID、商品コードのいずれかが指定されていることが必須です。
25 ギフト対応フラグ giftFlag int(1) - 0 0:全ての商品
1:ギフト対応商品のみ
26 レビューありフラグ hasReviewFlag int(1) - 0 0:全ての商品
1:レビューがある商品のみ
27 アフィリエイト料率最大制限値 maxAffiliateRate float - - 1.0から99.9までの数値 例)5.0 →5%アフィリエイト料率以下の商品のみ
指定したアフィリエイト料率以上は表示しない
少数第一位まで指定可能
28 アフィリエイト料率最小制限値 minAffiliateRate float - - 1.0から99.9までの数値 例)5.0 →5%アフィリエイト料率以上の商品のみ
指定したアフィリエイト料率以下は表示しない
少数第一位まで指定可能
アフィリエイト料率最大制限値以下の値を指定してください。
29 動画ありフラグ hasMovieFlag int(1) - 0 0:全ての商品
1:動画がある商品のみ(動画リンクを返却します)
30 資料請求対応フラグ pamphletFlag int(1) - 0 0:全ての商品
1:資料請求対応商品のみ
31 配送日指定対応フラグ appointDeliveryDateFlag int(1) - 0 0:全ての商品
1:配送日指定可能な商品のみ
32 出力パラメーター指定 elements String - ALL カンマ区切りで、必要な出力パラメータを指定した場合、
指定された出力パラメータのみを返却します。
(例)elements=reviewCount,reviewAverage
33 ジャンルごとの商品数取得フラグ【NEW】 genreInformationFlag int(1) - 0 0 :ジャンルごとの商品数の情報を取得しない
1 :ジャンルごとの商品数の情報を取得する

出力パラメーター


楽天商品検索API 出力パラメーター version:2013-04-24

ID 大分類 分類 項目名 パラメーター 備考
区分:サービス固有パラメーター
1 全体情報 検索数 count 検索結果の総商品数
2 ページ番号 page 現在のページ番号
3 ページ内商品始追番 first 検索結果の何件目からか
4 ページ内商品終追番 last 検索結果の何件目までか
5 ヒット件数番 hits 1度に返却する商品数
6 キャリア情報 carrier PC=0 or mobile=1 or smartphone=2
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)の指定により返却情報が異なります。

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

※仕様変更により、2015/07/01から、
入力パラメーターにアフィリエイトIDが
含まれていた場合、shopAffiliateUrlと
同じ値を返却いたします。
39 ジャンル情報 ジャンル情報 ジャンルID genreId  
40 ジャンルごとの商品数
(全体:<GenreInformation>
~ </GenreInformation> 、
個別ジャンル:<parent> ~ </parent>
もしくは<current> ~ </current>
もしくは<children> ~ </children>)【NEW】
親ジャンル - parent 入力したジャンルIDの親ジャンル
41 ジャンルID genreId  
42 ジャンル名 genreName  
43 ジャンル階層 genreLevel  
44 自ジャンル - current ユーザの入力したジャンルID
45 ジャンルID genreId  
46 ジャンル名 genreName  
47 ジャンルに紐づく商品数 itemCount  
48 ジャンル階層 genreLevel  
49 子ジャンル - child ユーザの入力したジャンルIDの子ジャンル
複数の子ジャンルがある場合は<children> ~ </children>内に<child> ~ </child>が複数生成される
入力が「genreId=0」の時はgenreLevel=1のジャンルが<child> ~ </child>に表示される
50 ジャンルID genreId  
51 ジャンル名 genreName  
52 ジャンルに紐づく商品数 itemCount  
53 ジャンル階層 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(モバイル)]

エラー

エラー内容は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 として 'IchibaItemSearch' を指定してください。
// ここでは例として keyword に、うどんを指定しています。
$response = $client->execute('IchibaItemSearch', array(
  'keyword' => 'うどん'
));

// レスポンスが正常かどうかを isOk() で確認することができます
if ($response->isOk()) {
    // 配列アクセスで情報を取得することができます。
    echo $response['count']."件見つかりました。\n";

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