Keepa APIのレスポンスの1つ、「Statistics Object」の公式レファレンスを日本語訳しました。
Request Productsで入手したデータベース(価格履歴やランキング履歴など)をもとに、最大・平均などの統計値(Statistics)を計算した結果が含まれています。
よく使用するところでは、ランキング下降回数≒販売数が取得できます。
あとは、最低価格のFBA出品者数なんかもわかるのでリサーチに便利ですね。
それでは、↓から日本語訳スタートです！
- 「参考」で囲った部分は筆者の補足です。
- 適宜サブタイトルの追加や、意訳を実施しています。
- Keepaから翻訳の許可を頂いております。
こちら↓↓↓の記事に全てのKeepa APIに関する日本語訳記事をまとめているので、他のレファレンスも確認したい場合はご参考ください！
- 概要
- Statistics Objectを返すリクエスト
- 重要なポイント
- レスポンスの形式
- 【筆者補足】Price Typeのインデックスについて
- 基本レスポンス
- カートボックスに関する項目
- buyBoxSellerId
- buyBoxPrice
- buyBoxShipping
- buyBoxIsUnqualified
- buyBoxIsShippable
- buyBoxIsPreorder
- buyBoxIsBackorder
- buyBoxIsFBA
- buyBoxIsAmazon
- buyBoxIsMAP
- buyBoxMinOrderQuantity, buyBoxMaxOrderQuantity
- buyBoxAvailabilityMessage
- buyBoxShippingCountry
- buyBoxIsPrimeExclusive
- buyBoxIsPrimeEligible
- buyBoxIsPrimePantry
- buyBoxStats
- buyBoxUsedStats
- buyBoxUsedPrice
- buyBoxUsedShipping
- buyBoxUsedSellerId
- buyBoxUsedIsFBA
- buyBoxUsedCondition
- 出品セラーに関する項目
概要
製品の集計情報が含まれています。
Statistics Objectを返すリクエスト
statistics objectは、statsパラメーターが使用された場合にProduct Requestによって返されるProduct Objectの一部です。
Product Requestは販売数やカテゴリなどの商品情報を取得するリクエストで、そのレスポンスがProduct Objectです。
本記事のStatistics ObjectはProduct Objectの一部分ですね。
Product RequestとProduct Objectについてはそれぞれ下記記事もご参考ください。
重要なポイント
一部のフィールドは、製品リクエストの offers パラメータが使用され、マーケットプレイス データが正常に取得された場合にのみ設定されます (製品オブジェクトの offersSuccessful フィールドで確認してください)。
offers パラメータって何？
offers パラメータは製品情報を取得するProduct Requestのオプションパラメータで、指定することで送料やセラーIDを取得できます。
しかし、追加で6トークン~ 必要になるため使いどころには注意です。
レスポンスの形式
{
"current": Integer array,
"avg": Integer array,
"avg30": Integer array,
"avg90": Integer array,
"avg180": Integer array,
"atIntervalStart": Integer array,
"min": two dimensional Integer array,
"max": two dimensional Integer array,
"minInInterval": two dimensional Integer array,
"maxInInterval": two dimensional Integer array,
"outOfStockPercentageInInterval": Integer array,
"outOfStockPercentage30": Integer array,
"outOfStockPercentage90": Integer array,
"lastOffersUpdate": Integer,
"salesRankDrops30": Integer
"salesRankDrops90": Integer
"salesRankDrops180": Integer
"totalOfferCount": Integer,
"lightningDealInfo": Integer array,
// following fields are only set if the offers or buybox parameter was used
"buyBoxSellerId": String,
"buyBoxPrice": Integer,
"buyBoxShipping": Integer,
"buyBoxIsUnqualified": Boolean,
"buyBoxIsShippable": Boolean,
"buyBoxIsPreorder": Boolean,
"buyBoxIsBackorder": Boolean,
"buyBoxIsFBA": Boolean,
"buyBoxIsAmazon": Boolean,
"buyBoxIsMAP": Boolean,
"buyBoxMinOrderQuantity": Boolean,
"buyBoxMaxOrderQuantity": Boolean,
"buyBoxAvailabilityMessage": String,
"buyBoxShippingCountry": String,
"buyBoxIsPrimeExclusive": Boolean,
"buyBoxIsPrimeEligible": Boolean,
"buyBoxIsPrimePantry": Boolean,
"buyBoxStats": Object,
"buyBoxUsedStats": Object,
"buyBoxUsedPrice": Integer,
"buyBoxUsedShipping": Integer,
"buyBoxUsedSellerId": String,
"buyBoxUsedIsFBA": Boolean,
"buyBoxUsedCondition": Integer,
// the following fields are only set if the offers parameter was used
"retrievedOfferCount": Integer,
"isAddonItem": Boolean,
"sellerIdsLowestFBA": String array,
"sellerIdsLowestFBM": String array,
"offerCountFBA": Integer,
"offerCountFBM": Integer
}【筆者補足】Price Typeのインデックスについて
Price Typeのインデックスって何？
以後レスポンス項目の説明が続くのですが、「Price Typeインデックス」という言葉が度々でてきます。
これはどのインデックスに何の情報が入っているかを示す情報です。
例えば、
- インデックス0(1番目) : Amazonの価格
- インデックス1(2番目) : 新品の価格
- インデックス2(3番目) : 中古のの価格
- インデックス3(4番目) : ランキング
といったように多数の情報が配列の形で含まれています。
その数、現状でも34種類!!
詳しく知りたい方は、下記記事一番最後の「csv」の項目をご確認ください。
基本レスポンス
current
Price Typeのインデックスを使用して、最後に更新された製品の価格/ランクが含まれています (product objectの csv フィールドを参照してください)。
価格は、それぞれの Amazon ロケールの最小通貨単位を表す整数です (例: ユーロ セントまたは円)。
-1 の値は、指定された期間でオファーが利用できなかったことを示します (例: 在庫切れ)。
avg
Price Type インデックスを使用して、商品リクエストの stats パラメータで指定された間隔の過去の加重平均が含まれます。
-1 の値は、間隔内にオファーがなかったか、データが不十分であることを示します。
avg30
avg の過去 30 日間版
avg90
avg の過去 90 日間版
avg180
avg の過去 180 日間版
atIntervalStart
Price Type インデックスを使用して、商品リクエストの stats パラメータで指定された間隔の開始時に登録された価格が含まれます。
-1 の値は、間隔内にオファーがなかったか、データが不十分であることを示します。
min, max
この商品に登録された最低価格と最高価格が含まれています。
最初のディメンションは、Price Type インデックスを使用します (product objectの csv フィールドを参照)。
2 番目の次元は null (価格タイプで利用できるデータがない) またはサイズ 2 の配列で、最初の値は極値の時間 (Keepa 時間分) で、2 番目の値はそれぞれの極値です。
minInInterval, maxInInterval
min および max と同じですが、商品リクエストのstatsパラメーターで指定された間隔に制限されます。
outOfStockPercentageInInterval
Price Type インデックスを使用して、商品リクエストの stats パラメータで指定された間隔での在庫切れの割合が含まれます (product objectの csv フィールドを参照)。
-1 の値は、データが不十分であるか、価格タイプが価格ではないことを示します。
例:
0 = 在庫切れなし
100 = 100% の確率で在庫切れ
25 = 25% の確率で在庫切れ
outOfStockPercentage30
Price Type インデックスを使用した 30 日間の在庫切れ率が含まれます (product objectの csv フィールドを参照)。
-1 の値は、データが不十分であるか、価格タイプが価格ではないことを示します。
例:
0 = 在庫切れなし
100 = 100% の確率で在庫切れ
25 = 25% の確率で在庫切れ
outOfStockPercentage90
outOfStockPercentage30 の90 日版。
salesRankDrops30
過去 30 日間の売上ランクの低下 (高い値から低い値へ) の数は、売上を示していると見なされます。
salesRankDrops90
salesRankDrops30 の90日版。
salesRankDrops180
salesRankDrops30 の180日版。
lastOffersUpdate
オファー情報が最後に更新された時刻 (Keepa 時間分)。
totalOfferCount
この商品のオファーの総数 (すべての条件を組み合わせたもの)。
条件ごとのオファー数は、current のフィールドで確認できます。
lightningDealInfo
過去、今後、または現在のライトニング ディール オファーを識別するために使用されます。
形式は [startDate, endDate] (null でない場合は常に長さ 2 の配列) です。
商品にライトニング ディールがなかった場合は null です。
両方のタイムスタンプは UTC と Keepa 時間の分です。
今後のライトニング ディールがある場合は、startDate のみが設定されます (endDate の値は -1)。
現在のライトニング ディールがある場合、startDate と endDate の両方が設定され、startDate は現在の時刻よりも古く、endDate は未来になります。
過去の取引しかない場合は、startDate と endDate の両方が過去に設定されます。
カートボックスに関する項目
以下のフィールドは、offers または buybox パラメーターが使用された場合にのみ設定されます。
buyBoxSellerId
ショッピング カート ボックス オファーの販売者 ID (存在する場合)。
それ以外の場合は、-1、-2、または null。
buyBoxPrice
ショッピング ボックスの新品価格 (存在する場合)。
それ以外の場合は、-1 または -2。
buyBoxShipping
ショッピング カート ボックスの新品配送料 (存在する場合)。
それ以外の場合は、-1 または -2。
buyBoxIsUnqualified
出品者がショッピング カート ボックスを獲得したかどうかを示します。
条件の悪い出品者しかいない場合、ショッピング カート ボックスの対象にはなりません。
buyBoxIsShippable
ショッピング ボックスが出荷可能としてリストされているかどうかを示します。
buyBoxIsPreorder
ショッピング ボックスが予約注文かどうかを示します。
buyBoxIsBackorder
ショッピング カート ボックスが取り寄せかどうかを示します。
buyBoxIsFBA
ショッピングカートボックスが FBAかどうかを示します。
buyBoxIsAmazon
ショッピング カート ボックスの出品者が Amazon かどうかを示します。
buyBoxIsMAP
MAPの制限（最低広告価格）により、ショッピングカートボックスの新品がAmazonで非表示になっているかどうかを示します。
buyBoxMinOrderQuantity, buyBoxMaxOrderQuantity
ショッピングカートボックスの最小および最大注文数量。利用できない場合は -1、制限が存在しない場合は 0。
buyBoxAvailabilityMessage
ショッピング ボックスの在庫メッセージ。利用できない場合は null。例: “在庫あり”
buyBoxShippingCountry
ショッピングカートボックス販売者のデフォルトの配送国。
利用できない場合、または販売者が Amazon の場合は null。例: “US”
buyBoxIsPrimeExclusive
ショッピング ボックスがプライム専用かどうかを示します。
利用できない場合は null。
buyBoxIsPrimeEligible
ショッピングカートボックスがプライム対象かどうかを示します。
利用できない場合は null。
buyBoxIsPrimePantry
ショッピング カート ボックスがPrime Pantryのオファーかどうかを示します。
利用できない場合は null。
Prime Pantryって何？
おそらく「Amazonパントリー」のことだと思います。
Amazonパントリーは複数の日用品などを1つの段ボールにまとめて送ってくれるサービスです。
しかし、日本でもアメリカでも2021年にサービス終了しているようです。
buyBoxStats
指定された期間の購入ボックス統計を含むオブジェクト。
各キーは、ショッピング ボックス販売者の SellerId を表し、各オブジェクトはショッピング ボックス統計オブジェクトです。
例：
"buyBoxStats": {
"ATVPDKIKX0DER": {
"avgNewOfferCount": 1, // avg. "New" offer count during the time the seller held the Buy Box
"avgPrice": 1466, // avg. price of the Buy Box offer of this seller
"isFBA": false, // whether or not this offer is fulfilled by Amazon
"lastSeen": 5911806, // last time the seller won the buy box
"percentageWon": 100.0 // percentage the seller won the buy box
}
},buyBoxUsedStats
指定された間隔で中古購入ボックスの統計を含むオブジェクト。
フォーマットはbuyBoxStatsと同じです。
buyBoxUsedPrice
中古ショッピング カート ボックスの価格（利用可能な場合）。
それ以外の場合は -1 または null。
buyBoxUsedShipping
中古ショッピング カート ボックスの送料（利用可能な場合）。
それ以外の場合は -1 または null。
buyBoxUsedSellerId
中古ショッピング カート ボックス取得者のセラーID（利用可能な場合）。
それ以外の場合は null。
buyBoxUsedIsFBA
中古のショッピング カート ボックスが FBAかどうかを示します。
buyBoxUsedCondition
中古のショッピング ボックスのサブコンディション。
可能な値は次のとおりです。
- “2” – 中古 – ほぼ新品
- “3” – 中古 – 非常に良い
- “4” – 中古 – 良い
- “5” – 中古 – 可
出品セラーに関する項目
以下のフィールドは、offers パラメーターが使用された場合にのみ設定されます。
retrievedOfferCount
このリクエストで取得されたオファーの数。
isAddonItem
商品がadd-on商品かどうかを示します (追加商品は、Amazon が発送する $25 以上の商品を含む注文で発送されます)。
日本でAdd-on itemにドンピシャ当てはまるモノはなさそうです…。
ただ内容としては、日本でもたまにある「〇〇円以上じゃないと購入できない」商品が近そうです。
そのような商品がisAddonItemがtrueになるかは要検証ですね。
sellerIdsLowestFBA
最低価格の現在の新品FBA オファーの出品者 ID (存在する場合) が含まれます。
複数のオファーが同じ価格を共有している場合、複数のエントリが存在します。
sellerIdsLowestFBM
最低価格の現在の新品FBM オファーの販売者 ID (存在する場合) が含まれます。
複数のオファーが同じ価格を共有している場合、複数のエントリが存在します。
offerCountFBA
利用可能な場合、取得された現在の新品FBA オファーの数。
それ以外の場合は -2。
offerCountFBM
利用可能な場合、取得された現在の新品FBM オファーの数。
それ以外の場合は -2。
Keepa Time minutesとは？
すべてのタイムスタンプに使用される時刻形式です。
圧縮されていないタイムスタンプ (Unix エポック時間) に変換するには、21564000 を加算してから 60000 を掛けます (ミリ秒の場合、または秒の場合は 60)。
以上です！
消費トークンなどリクエストの詳細については下記記事を参考にしてみてください。
また、一緒に返される他のレスポンスの情報(販売数や商品サイズなど)は下記記事でまとめているのでご参考ください。
