Keepa APIのリクエストの1つ、「Request Products」の公式レファレンスを日本語訳しました。
Amazonのapiでは取得できない販売数等を取得できるため、恐らく最もメジャーな花形リクエストですね。
一方で、トークンの消費量計算にややこしい部分もあります…
(特にoffersオプション、お前のことだ)
できるだけ理解しやすいように解説も加えているので、api使用者の助けになれば幸いです。
同じような情報が取得できるAPIにProduct Search↓がありますが、あちらは検索キーワードを指定する一方、Request ProductsはASINやJANを直接指定します。
- キーワードから競合商品の情報を取得したり、仕入れ商品の当たりをつける場合はProduct Search
- 販売できるASINやJANが決まっている場合(仕入先の商品リストがある場合など)はRequest Products
というように使い分けると良さそうです。
「リクエストの詳細じゃなくて、どんな情報が取得できるかを知りたい！」という方向けには、こちらの記事で詳しく解説しています。
それでは、↓から日本語訳スタートです！
- 「参考」で囲った部分は筆者の補足です。
- 適宜サブタイトルの追加や、意訳を実施しています。
- Keepaから翻訳の許可を頂いております。
こちら↓↓↓の記事に全てのKeepa APIに関する日本語訳記事をまとめているので、他のレファレンスも確認したい場合はご参考ください！
リクエストの基本情報
消費トークン
1トークン / 1商品
指定された ASIN およびドメインの商品オブジェクトを取得します。
最新の更新が1時間以上前のものである場合は、ほぼリアルタイムの価格データを取得できるように、配信前に自動的に更新されます。
ASIN（推奨）またはUPCおよびEANコードを介して製品をリクエストできます。
ASINとコードの両方のパラメータを同じリクエストで使用することはできません。
コードパラメータを使用し、提供されたコードがデータベースにない場合、製品は返されません。
この場合、代わりにproduct searchを使用して、Amazonコードを検索できます。
KeepaはAmazon FreshとeBook を追跡できません。
Amazon FreshはPrime会員向けの生鮮食品販売サービスです。
eBookは説明不要かと思いますが、電子書籍ですね。
リクエストのQueryパラメータ
/product?key=<yourAccessKey>&domain=<domainId>&asin=<ASIN> [or] &code=<productCode>- <yourAccessKey>
APIキー - <domainId>
アクセスしたいAmazonエリア[整数]
有効な値: [ 1: com | 2: co.uk | 3: de | 4: fr | 5: co.jp | 6: ca | 8: it | 9: es | 10: in | 11: com.mx ] - <ASIN>
リクエストする商品の ASIN。一括リクエストの場合、ASIN のコンマ区切りリスト (最大 100)。 - <productCode>
ご希望の商品の商品コードです。
現在、UPC、EAN、ISBN-13 コードを使用できます。
バッチリクエストの場合は、カンマ区切りのコード リスト(最大 100)。
複数のASIN が同じ商品コードを持つことができるため、商品コードをリクエストすると複数の商品が返される場合があります。
リクエストの追加パラメータ詳細
stats
基本情報
追加のトークンコストはありません。
指定した場合、製品オブジェクトには、現在の価格、最小/最大価格、および加重平均値にすばやくアクセスできる統計フィールドがあります。
offersパラメータが使用された場合は、カート情報も提供されます。
stats パラメータは次の 2 つの形式で指定できます。
- 過去 x 日間 (正の整数値):
過去 x 日間の統計を計算します。
ここで、xは統計パラメーターの値です。 - 日付間隔:
統計計算の日付範囲を指定できます。
範囲は、2つのタイムスタンプ (UNIX エポック時間のミリ秒) または 2 つの日付文字列 (ISO8601、UTC の時間ありまたはなし) で指定できます。
備考
価格タイプの履歴データが不十分な場合、加重平均計算の実際の間隔は指定よりも短くなる可能性があります。
statsフィールドを介して提供されるすべてのデータは、製品オブジェクトの csv history フィールドを使用して計算されるため、このパラメーターを介して提供される新しいデータはありません。
statsオプションは、オプション無しで得られる情報の統計値を返すだけということですね。
だったら、使用者側でプログラムを書いても良いですが、追加の消費トークンが0なので使用してもいいかと思います。
statsオプションで追加される情報の詳細は、下記記事で詳しく解説しています。
使用例
&stats=180 (過去180日間)
&stats=2015-10-20,2015-12-24 (2015年10/20 ~ 12/24)
&stats=2011-01-01,2025-01-01 (keepaに存在する全期間)
&stats=1445299200000,1450915200000 (unix エポックミリ秒表記, 2015年10/20 ~ 12/24)update
基本情報
+0 or 1トークン / 1商品
正の整数値。
製品の最終更新がupdateで指定した時間よりも古い場合は、データを更新します。
API が使用するデフォルト値は1時間です。
このパラメーターは、offersパラメーター(後述)と連携して機能します。
このパラメーターを使用すると、次のことを実現できます。
- 1以上の値:
最新のデータが必要ない場合は、デフォルトの1時間よりも高い値を使用してリクエストを高速化します。
追加のトークン コストはありません。 - 0:
最新データを取得します。
最後の更新が1時間以内に行われた場合、余分に1トークンを消費します。※1 - –1:
製品情報をまったく更新しない場合は、値 -1 を使用します。
製品がデータベースにない場合、製品リクエストトークンを消費せず、製品データも受け取りません。
元々keepaデータに存在する製品情報のみで問題ない場合は、トークンを節約するためにこの設定を使用してください。 - offersパラメーターと組み合わせると、最後のオファー データの更新が指定した更新時間よりも新しい場合、オファートークンの使用量は 5トークンに減り、要求されたオファー ページの数に関係なく、更新は行われません※2。
- ※1
検証していないので推測ですが、
・keepaでの「最新」データとは1時間以内に更新されたデータのこと
・1時間以内に更新されたデータは既に「最新」なので、0を指定してもデータの取得は行わない
・しかし1トークン余分に消費する
ではないかと思います。 - ※2
後述しますが、offersパラメータを設定すると、Amazonから最新の出品情報を取得できますが6トークン以上(!!)消費します。
そのトークン消費が5トークンまで減るので、節約になるよということです。
使用例
&update=48 (最新の更新が48時間よりも古い場合に実行されます)history
基本情報
追加のトークンコストはありません。
ブール値 (0 = false、1 = true)。
default : 1
値が0の場合、製品オブジェクトにはcsv、salesRanks、salesRankReferenceHistoryフィールドが含まれなくなります。
それらが必要ない場合は、history=0を指定して応答から削除します。
これにより、処理時間が短縮され、応答のサイズが大幅に縮小されます。
使用例
&history=0days
基本情報
追加のトークン コストはありません。
任意の正の整数値。
正の値Xを指定した場合、製品オブジェクトはすべての履歴データを最近のX日間に制限します。
これには、csv、buyBoxSellerIdHistory、salesRankReferenceHistory、salesRanks、offers、offers.offerCSV フィールドが対象です。
古い履歴データが必要ない場合は、daysを指定して応答から削除します。
これにより、処理時間が短縮され、応答のサイズが大幅に縮小されます。
パラメータは暦日を使用しないため、1日は過去24 時間に相当します。
※筆者注:時間[hours]単位で指定する必要がある
使用例
&days=90offers
基本情報
6トークン / 1出品ページ(最大10出品情報)
正の整数値。
指定する場合は、20から100の間でなければなりません。
マーケットプレイスの出品情報数を指定します。
追加のトークン コストは、要求された数ではなく、見つかった出品情報の数によって計算されます。
(製品の出品情報が要求された数よりも少ない場合があるため)
offersパラメータを使用する場合、Product Requestの基本消費トークン(1トークン/1ASIN)は適用されません。
オファー パラメータが使用されている場合、製品オブジェクトには追加のデータが含まれます。
- Marketplace offer objects
- ショッピングカートボックス獲得者の履歴を含む、新品および中古のショッピングカートボックスに関する情報。
- FBA (フルフィルメント by Amazon)、FBM (フルフィルメント by マーチャント)、Warehouse Deals※、およびすべての中古品および収集品のサブコンディションの価格履歴データ (配送料と手数料を含む)。
※筆者注 Amazonアウトレットのこと - 評価とレビュー数の履歴。
- すべての出品情報関連データは、他のすべての製品データほど頻繁ではなく、個別に不定期に更新されます。
追加の履歴データを評価するときは、このことに留意してください。
offersオプションを追加した場合、出品セラーに関する多くの情報がMarketplace offer objects として返されます。
どんな情報が含まれているかは下記記事をご参考ください。
備考
- 返品された製品には、指定されたよりもはるかに多くの出品情報が含まれている場合があります。
これは、出品情報の履歴を保持しているためです。
offersパラメーターで指定された数によって、Amazonから取得・更新しようとする出品情報の数が決まります。
各オファーオブジェクトには、最新のオファーをフィルタリングするために使用できる lastSeen フィールドがあります。 - バッチ処理されたリクエストは並行して処理されます。
- 出品情報関連するすべてのデータは、新しく更新された最新のものです。
- リクエストが完了するまでにはさらに時間がかかります。
2 ～ 20 秒の範囲で、平均 5 秒です。
必要に応じて、バッチ リクエストまたは並列リクエストを使用してスループットを向上させます。 - 出品情報の取得や更新に失敗した場合は1トークンのみ消費します。
リクエストが正常に返され、利用可能な場合は、すべての過去の出品情報(only-live-offersが使用されている場合を除く) と製品データが含まれます。
数分後にリクエストを再試行できます。
制限事項
デジタル商品、映画レンタル、Amazon Fresh および Amazon Pantry ではご利用いただけません。
使用例
&offers=40最大40個の出品情報をリクエストします。
10個ごとに6トークン消費するので、最大6×4=24トークン消費します。
仮に製品に18個の出品情報しかなかった場合、リクエストの合計消費トークンは、6×2 = 12トークンになります。
トークン周りがややこしいので整理します。
- offersによる情報取得が成功した場合、6トークン/1出品ページのトークンが消費される一方、Product Requestの基本消費トークン(1トークン/1商品)がなくなる。
- 1出品ページには最大で10出品情報が含まれるので、最大で取得する出品ページ数は「offersに指定した値(最大取得出品数) ÷10」になる。
- つまり、「6トークン× offersに指定した値÷10」が最大消費トークンになる。
- 実際に消費されるトークンは取得した出品ページ数に依存する。
- 取得する出品ページは出品情報が10を超えるごとに1増えるので、
・出品情報 が1~10個: 6×1ページ = 6トークン消費
・出品情報が11~20個 : 6×2ページ = 12トークン消費
…
となる。 - offersに指定できる値は最低でも20~なので、実際に取得できた出品情報数に応じて、6(出品情報が1~10個) or 12トークン(出品情報が11~20個)消費することになる。
only-live-offers
基本情報
追加のトークン コストはありません。
ブール値 (0 = false、1 = true)。
default : 0
値が1の場合、製品オブジェクトには最新のマーケットプレイスの出品情報のみが含まれます。
(offersパラメーターと組み合わせて使用された場合)
過去のオファーが必要ない場合は、これを使用して応答から削除します。
これにより、処理時間が短縮され、応答のサイズが大幅に縮小されます。
使用例
&only-live-offers=1rental
基本情報
追加のトークン コストはありません。
ブール値 (0 = false、1 = true)。
default : 0
offersパラメータと組み合わせてのみ使用できます。
値が 1 の場合、レンタル価格は利用可能になった時点で収集されます。
注: レンタル価格は、Amazon US および書籍のみで利用可能です (電子書籍は対象外)。
rating
基本情報
+1トークン / 1商品
ブール値 (0 = false、1 = true)。
default : 0
値が 1 の場合、製品オブジェクトには、offers パラメーターが使用されているかどうかに関係なく、csv フィールドに既存の RATING および COUNT_REVIEWS 履歴が含まれます。
追加のトークンは、両方のデータ ポイントへの最後の更新が 14 日以内に行われた場合にのみ消費されます。
このパラメーターを使用しても、これら 2 つのフィールドの更新はトリガーされず、既存のデータが利用可能な場合にのみアクセスできます。
最新のデータが必要な場合は、 offers パラメータを使用する必要があります。
評価のデータが古い可能性があっても問題なく、offersパラメーターを介して提供される他のデータフィールドも必要ない場合は、トークンを節約してリクエストを高速化するために、これを使用します。
評価データが返されない場合でも、offersパラメーターを使用して別のリクエストを行うことができます。
商品評価の情報のみが欲しい際に使用する、トークン節約用のオプションです。
最大14日古い情報で良ければ、
- rating=1 で評価情報を取得
- 評価情報を取得できなかった場合は、offersパラメータを使用して情報を取得
がトークン効率が良さそうです。
使用例
&rating=1製品オブジェクトのcsv履歴データフィールドと統計オブジェクトのそれぞれのフィールドに、評価とレビュー数のデータを含めます。
buybox
基本情報
+2トークン / 1商品
ブール値 (0 = false、1 = true)。
default : 0
値が1の場合、製品および統計オブジェクトには、利用可能なすべての購入ボックス関連データが含まれます。
- 現在の価格、価格履歴、統計値
- カート取得SellerIdの履歴
- 統計オブジェクトのすべてのショッピング ボックスのフィールド:
buyboxパラメーターは、新しいデータ収集をトリガーしません。
offersパラメータはすべてのショッピング ボックス関連データへのアクセスも提供するため、offersパラメータが使用されている場合、buyboxパラメータは無視されます。
統計オブジェクトにアクセスするには、stats パラメータが必要です。
使用例
&buybox=1リクエストのレスポンス
要求された各ASIN のエントリを持つproduct objectsの配列を含むproductsフィールド。
以上です！
リクエストのレスポンスについては、下記の記事で詳しく解説しています。
