【Keepa APIの使い方】公式レファレンスを日本語訳してみました【Browsing Deals】

Keepa APIのリクエストの1つ、「Browsing Deals」の公式レファレンスを日本語訳しました。

Keepaの「商品」タブの機能のAPI版のようです。

「商品」タブの機能は、Keepaの商品データベースの中で指定した条件にあった商品を抽出する機能で、主にAmazonでの販売価格が下落した商品を探す用途です。

Amazonで仕入れをする用の機能かなと思います。

それでは、↓から日本語訳スタートです！

「参考」で囲った部分は筆者の補足です。
適宜サブタイトルの追加や、意訳を実施しています。
Keepaから翻訳の許可を頂いております。

こちら↓↓↓の記事に全てのKeepa APIに関する日本語訳記事をまとめているので、他のレファレンスも確認したい場合はご参考ください！

【Keepa APIの使い方】公式レファレンス日本語訳のまとめ当ブログで投稿してきたKeepa APIの公式レファレンス(英語)の日本語訳解説のまとめ記事です。 Google翻訳でページ一括...

リクエストの基本情報
- 消費トークン
- リクエストのQueryパラメータ
リクエストのレスポンス

リクエストの基本情報

消費トークン

5トークン / 1リクエスト (1リクエストで最大150件)

dealsにアクセスすると、最近変更され、検索条件に一致する製品を見つけることができます。

1 回のリクエストで最大150件の取引(=deals)が返されます。

クエリは、ページングを使用して最大10000個のASIN を提供できます。

このドキュメントを読む前に、まず取引ページを試してみて、提供されるオプションと結果に慣れることをお勧めします。

バグを見つけた場合、または質問がある場合は、サポートカテゴリ95のトピックを開いてください。

当社の取引は、過去12時間以内に更新された製品のみを提供します。

リクエストのQueryパラメータ

HTTP GET または POST 要求のいずれかを選択できます。

GET format

/deal?key=<yourAccessKey>&selection=<queryJSON>

<yourAccessKey>
APIキー
<queryJSON>
queryJSON にはすべてのリクエストパラメータが含まれます。
GET 形式を使用する場合は、URL エンコードする必要があります。
有効なqueryJSON をすばやく取得するには、同じ設定のフィルターを施した上で、取引ページのリンクを確認してください。

POST format

/deal?key=<yourAccessKey>

<yourAccessKey>
APIキー
POST ペイロードには <queryJSON> が含まれている必要があります。

queryJSONのフォーマット

{
    "page": Integer,
    "domainId": Integer,
    "excludeCategories": Long array,
    "includeCategories": Long array,
    "priceTypes": Integer array,
    "deltaRange": Integer array,
    "deltaPercentRange": Integer array,
    "deltaLastRange": Integer array,
    "salesRankRange": Integer array,
    "currentRange": Integer array,
    "minRating": Integer,
    "isLowest": Boolean,
    "isLowestOffer": Boolean,
    "isOutOfStock": Boolean,
    "titleSearch": String,
    "isRangeEnabled": Boolean,
    "isFilterEnabled": Boolean,
    "hasReviews": Boolean,
    "filterErotic": Boolean,
    "singleVariation": Boolean
    "sortType": Integer,
    "dateRange": Integer
}

検索条件用の項目

page
ほとんどの取引クエリには 150 を超える結果があります (これが最大ページサイズです)。
クエリで見つかったすべての取引を閲覧するには (上限 10,000 まで)、ページパラメーターを反復処理し、他のすべてのパラメーターを同一に保ちます。
ページ0から開始し、応答に含まれる結果が 150 未満になったら終了します。
domainId
取引を取得する Amazon ロケールの domainId。
可能な値:
[ 1: com | 2: co.uk | 3: de | 4: fr | 5: co.jp | 6: ca | 8: it | 9: es | 10: in | 11: com.mx ]
priceTypes
取引のタイプを決定します。
これは整数配列ですが、1 つのエントリしか含めることができません。
クエリごとの複数のタイプはまだサポートされていません。
可能な値:
- 0 – Amazon: Amazonの価格履歴
- 1 – NEW: マーケットプレイスの新品価格履歴。
- 2 – USED: マーケットプレイスの中古価格履歴
- 3 – SALES: 販売ランキング履歴。
  すべての製品にセールスランクがあるわけではありません。
  通常、バリエーション商品には個別の販売順位はありません。
- 5 – COLLECTIBLE: コレクターの価格履歴
- 6 – 再生品: 再生品の価格履歴
- 7 – NEW_FBM_SHIPPING: サードパーティ(Amazonを除く) 販売者 (FBM) のみが発送する、配送料を含む新品価格履歴。
- 8 – LIGHTNING_DEAL: ライトニングディールの価格履歴。
  ライトニングディールは、以下の特別な関連する重要な情報です。
- 9 – WAREHOUSE: Amazon 倉庫の価格履歴。
- 10 – NEW_FBA: 最低価格のサードパーティ (Amazon/Warehouse を除く) のFBA新品価格履歴 Amazon。
- 18 – BUY_BOX_SHIPPING: 新品のカートボックス価格履歴。
  ショッピングカートボックスに該当するオファーがない場合 (またはショッピングボックスが中古のオファーの場合)、価格の値は -1 になります。
  送料を含みます。
- 19 – USED_NEW_SHIPPING: 「中古 – ほぼ新品」の価格履歴 (配送料を含む)。
- 20 – USED_VERY_GOOD_SHIPPING: 「中古 – 非常に良い」の価格履歴 (配送料を含む)。
- 21 – USED_GOOD_SHIPPING: 「中古 – 良い」の価格履歴 (配送料を含む)。
- 22 – USED_ACCEPTABLE_SHIPPING: 「中古 – 可」の価格履歴 (配送料を含む)。
- 値の例:[0] ※筆者注 現状1つの値しか指定できないが配列で入力
dateRange
keepaの取引は、製品が変更された時間間隔によって決定されるさまざまなセットに分けられます。
間隔が短いほど、変更が最近のものになります。
これは、大幅な値下げには適していますが、長期間にわたって蓄積されるゆっくりとした漸進的な値下げには適していません。
ほとんどの取引では、短い間隔で取得可能なデータはは長い間隔のデータに含まれます。
より多くの取引を見つけるには、より長い間隔を使用します。
可能な値:
- 0 – 日: 過去 24 時間
- 1 – 週: 過去 24 * 7 時間
- 2 – 月: 過去 24 * 31 時間
- 3 – 3 か月: 過去 24 * 90 時間
- 値の例:0

フィルター用の項目

isFilterEnabled
フィルターオプションを有効に切り替えます。

値の例 : true
excludeCategories
記載したカテゴリの製品を除外するために使用されます。
サブカテゴリの場合、製品はこのカテゴリに直接リストされている必要があります。
ルートカテゴリでない限り、指定されたカテゴリの子カテゴリの製品は除外されません。
最大500 のカテゴリノード ID 配列をリクエストできます。

値の例:[77028031,186606]
includeCategories
記載したカテゴリにリストされている製品のみを含めるために使用されます。
サブカテゴリの場合、製品はこのカテゴリに直接リストされている必要があります。
ルートカテゴリでない限り、指定されたカテゴリの子カテゴリの製品は含まれません。
最大500 のカテゴリノード ID 配列をリクエストできます。

値の例:[3010075031,12950651,355007011]
isLowest
指定された価格タイプが(keepaがトラッキングを開始してから)最低値にある製品のみを含めます。
true の場合、「isRisers_※1」は false でなければなりません。

値の例:true
isLowestOffer
選択した価格タイプがすべての新規オファーの中で最も低い場合にのみ製品を含めます (Amazon および Marketplace New に適用されます)。
「isRisers_※1」が true の場合は適用されません。

値の例:true
isOutOfStock
過去 24 時間以内に注文可能で、現在在庫切れの製品のみを含めてください。
※筆者注 つまり24時間以内に在庫切れになった商品

値の例:true
hasReviews
true の場合、レビューのないすべての製品が除外されます。
false の場合、フィルターは非アクティブです。
※筆者注 falseはレビューのない商品のみを取得する「わけではない」(=フィルターは非アクティブ)

値の例:false
filterErotic
成人向け商品として記載されているすべての商品を除きます。

値の例:false
singleVariation
複数のバリエーションがクエリに一致する場合は、1 つのバリエーションのみを提供します。
提供されるものはランダムに選択されます。

値の例:true
minRating
最低評価を指定します。
評価は 0 から 50 までの整数です (例: 45 = 4.5 星)。
-1 の場合、フィルターは非アクティブです。

値の例:20 (=評価☆数が2以上)

※1 isRisersについて

オプションの一つだと思いましたが、少なくともこのリクエストには含まれていませんでした。謎……。

分かったらまた追記します。

範囲を決める用のオプション

すべての範囲オプションは、2つのエントリを持つ整数配列です。
最初のエントリは最小値で、2 番目のエントリは最大値です。

isRangeEnabled
範囲オプションを有効に切り替えます。

値の例:true
currentRange
指定した価格タイプの現在の値の範囲を制限します。
値の例:[105,50000]
(= 最低価格 $1.05、最高価格 $500、または 105 ～ 50000 のランキング)。
deltaRange
現在の値と選択した dateRange 間隔の加重平均値との絶対差の範囲を制限します。

値の例: [0,999]
(= 差なし ~ 差 $9.99)。
deltaPercentRange
deltaRange と同じですが、絶対値ではなくパーセントで与えられます。
最小パーセントは 10 で、販売ランクの場合は 80 です。
値の例: [30,80] (= 30% から 80% の間)。
salesRankRange
商品の販売ランク範囲を制限します。
価格タイプが販売ランクに設定されている場合、currentRange と同じです。
上限を開いたままにしたい場合は、-1 を指定できます。
(これは最大の符号付き整数値に変換されます)

重要な注意: この範囲オプションを使用すると、販売ランクのないすべての製品が除外されます。
使用しないようにするには、null に設定します (または JSON から除外します)。

値の例:
[0,5000] (=売上ランク0～5000の商品のみ)
[5000,-1] (= 5000 以上)

検索と並び替え用のオプション

titleSearch
キーワードによる商品タイトル検索で取引を選択します。
検索では大文字と小文字が区別されず、最大 50 個のキーワードがサポートされます。
キーワードを指定してスペースで区切ると、すべて一致する必要があります。

値の例:”samsung galaxy”
タイトルに「samsung」と「galaxy」の両方の文字列が含まれるすべての製品に一致します
sortType
取得した取引のソート順を決定します。
ソート順を逆にするには、負の値を使用します。

可能なソート値:
- 1 – 取引年月日。
  最新の取引が最初に行われ、逆順にできません。
- 2 – 絶対デルタ。 (現在の値と、選択した dateRange開始時の値との差)。
  並べ替え順序は、最大のデルタから最小のデルタです。
- 3 – 販売ランキング。
  並べ替え順序は、最低ランキングから最高ランキングです。
- 4 – パーセンテージデルタ (現在の値と、選択した dateRange開始時の値とのパーセンテージ差)。
  並べ替え順序は、パーセントが高いものから低いものへです。

queryJSONの例

{
	"page": 0,
	"domainId": 1,
	"excludeCategories": [1064954, 11091801],
	"includeCategories": [16310101],
	"priceTypes": [0],
	"deltaRange": [0, 10000],
	"deltaPercentRange": [20, 100],
	"deltaLastRange": null,
	"salesRankRange": [0, 40000],
	"currentRange": [500, 40000],
	"minRating": -1,
	"isLowest": false,
	"isLowestOffer": false,
	"isOutOfStock": false,
	"titleSearch": null,
	"isRangeEnabled": true,
	"isFilterEnabled": false,
	"filterErotic": true,
	"hasReviews": false,
	"sortType": 4,
	"dateRange": 1
}

リクエストのレスポンス

応答には、次の内容の取引フィールドが含まれています。

{
    "dr" : deal object array,
    "drDateIndex" : Integer array,
    "categoryIds" : Long array,
    "categoryNames" : String array,
    "categoryCount" : Integer array
}