Keepa APIのリクエストの1つ、「Product Search」の公式レファレンスを日本語訳しました。
Amazonの検索結果からASINの情報を取得するAPIです。
同じような情報が取得できるAPIにRequest Products↓がありますが、あちらはASINやJANを直接指定する一方、Product Searchは検索キーワードを指定します。
- キーワードから競合商品の情報を取得したり、仕入れ商品の当たりをつける場合はProduct Search
- 販売できるASINやJANが決まっている場合(仕入先の商品リストがある場合など)はRequest Products
というように使い分けるとよさそうです！
「リクエストの詳細じゃなくて、どんな情報が取得できるかを知りたい！」という方向けには、こちらの記事で詳しく解説しています。
それでは、↓から日本語訳スタートです！
- 「参考」で囲った部分は筆者の補足です。
- 適宜サブタイトルの追加や、意訳を実施しています。
- Keepaから翻訳の許可を頂いております。
こちら↓↓↓の記事に全てのKeepa APIに関する日本語訳記事をまとめているので、他のレファレンスも確認したい場合はご参考ください！
リクエストの基本情報
消費トークン
10トークン / 1ページ (1ページ当たり最大10商品)
検索用語ごとに最大 100 件(※筆者注 10商品×10ページ)の結果が得られるキーワードを使用して、Amazon 製品を検索します。デフォルトでは、製品検索応答には、見つかった製品の製品オブジェクトが含まれています。
後述しますが、オプションでpageパラメータを使用しない場合は最初の40件の結果を取得できます。
つまり、最大10トークン/40ASIN で実行できることになるので、ページを指定するよりトークン消費が少なくなります。
最初の40件で問題なければpageパラメータを使用しないようにすると吉！
リクエストのQueryパラメータ
/search?key=<yourAccessKey>&domain=<domainId>&type=product&term=<searchTerm>- <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 ] - <searchTerm>
検索したい用語。
URL は エンコードされている必要があります。
リクエストの追加パラメータ詳細
asins-only
提供され、値が 1 の場合、見つかった製品の 製品オブジェクトではなく ASIN のみが提供されます。
page
整数値。 有効な値は 0 ～ 9 です。
各検索結果ページには、最大 10 件の結果が表示されます。
より多くの結果を取得するには、ページ パラメーターを反復し、他のすべてのパラメーターを同一に保ちます。
0 ページから開始し、応答に含まれる結果が 10 件未満になるか、制限である 9 ページに達したら停止します。
page パラメーターを使用しない場合、最初の 40 件の結果が返されます。
値の例: &page=0
stats
追加のトークン コストはありません。
指定した場合、製品オブジェクトには、現在の価格、最小/最大価格、および加重平均値にすばやくアクセスできる統計フィールドがあります。
stats パラメータは次の 2 つの形式で指定できます。
- 過去 x 日間 (正の整数値):
過去 x 日間の統計を計算します。
ここで、x は統計パラメーターの値です。 - 間隔:
統計計算の日付範囲を指定できます。
範囲は、2 つのタイムスタンプ (UNIX エポック時間のミリ秒) 、または 2 つの日付文字列 (ISO8601、UTC の時間ありまたはなし) で指定できます。
注: 価格タイプの履歴データが不十分な場合、加重平均計算の実際の間隔は指定よりも短くなる可能性があります。
stats フィールドを介して提供されるすべてのデータは、製品オブジェクトの csv history フィールドを使用して計算されるため、このパラメーターを介して提供される新しいデータはありません。
値の例:
- &stats=180
過去180日間 - &stats=2015-10-20,2015-12-24
2015年10月20日～12月24日 - &stats=1445299200000,1450915200000
2015年10月20日～12月24日(unix エポック時間のミリ秒)
statsオプションは、オプション無しで得られる情報の統計値を返すだけということですね。
だったら、使用者側でプログラムを書いても良いですが、追加の消費トークンが0なので使用してもいいかと思います。
update
+0 or 1トークン/1商品
正の整数値。
製品の最終更新がupdateで指定した更新時間より古い場合は、データを更新します。
API が使用するデフォルト値は 1 時間です。
このパラメーターを使用すると、次のことを実現できます:
- 1以上の値:
最新のデータが必要ない場合は、デフォルトの1時間よりも高い値を使用してリクエストを高速化します。
追加のトークン コストはありません。 - 0:
最新データを取得します。
最後の更新が1時間以内に行われた場合、余分に1トークンを消費します。
値の例:
&update=48
製品の最後の更新が 48 時間以上前の場合にのみ、データを更新します。
history
追加のトークンコストはありません。
ブール値 (0 = false、1 = true)。
default : 1
値が 0 の場合、製品オブジェクトには csv フィールドが含まれません。
商品オブジェクトの csv フィールドが必要ない場合は、これを使用して応答から削除します。
これにより、処理時間が短縮され、応答のサイズが大幅に縮小されます。
値の例:
&history=0
製品オブジェクトから csv 履歴データ フィールドを削除します。
rating
+0 or 1トークン/1商品 (最大+5トークン/1検索)
ブール値 (0 = false、1 = true)。
指定され、値が 1 の場合、製品オブジェクトには、csv フィールドの既存の RATING および COUNT_REVIEWS 履歴が含まれます。
追加のトークンは、両方のデータ ポイントへの最後の更新が 14 日以内に行われた場合にのみ消費されます。
このパラメーターを使用しても、これら 2 つのフィールドの更新はトリガーされず、既存のデータが利用可能な場合にのみアクセスできます。
最新のデータが必要な場合は、別の商品リクエストの offers パラメータを使用する必要があります。
評価のデータが古い可能性があっても問題なく、offersパラメーターを介して提供される他のデータフィールドも必要ない場合は、トークンを節約してリクエストを高速化するために、これを使用します。
評価データが返されない場合でも、offersパラメーターを使用して別のリクエストを行うことができます。
値の例:
&rating=1
商品オブジェクトの csv 履歴データ フィールドと統計オブジェクトのそれぞれのフィールドに、評価とレビュー数のデータを含めます。
商品評価の情報のみが欲しい際に使用する、トークン節約用のオプションです。
最大14日古い情報で良ければ、
- rating=1 で評価情報を取得
- 評価情報を取得できなかった場合は、offersパラメータを使用して情報を取得
がトークン効率が良さそうです。
リクエストのレスポンス
products フィールド内のProduct Objectの順序付き配列。
または asinList フィールド内の ASIN の順序付き文字列配列 (asins-only パラメータが使用された場合)。
以上です！
リクエストのレスポンスについては、下記の記事で詳しく解説しています。
