Keepa APIのリクエストの1つ、「Tracking Products」の公式レファレンスを日本語訳しました。
Keepaのメイン機能としてネット上でよく紹介されているトラッキング機能のAPI版ですね。
トラッキング機能とは、商品が設定した価格条件(例:1,000円以下など)を満たしたときに通知する機能です。
単純におトクなタイミングで商品を購入したい場合や、Amazonで仕入れを行う場合に便利な機能になります。
それでは、↓から日本語訳スタートです！
- 「参考」で囲った部分は筆者の補足です。
- 適宜サブタイトルの追加や、意訳を実施しています。
- Keepaから翻訳の許可を頂いております。
こちら↓↓↓の記事に全てのKeepa APIに関する日本語訳記事をまとめているので、他のレファレンスも確認したい場合はご参考ください！
リクエストの基本情報
消費トークン
トークンのコスト: 追跡対象の製品ごとに異なるコスト
Keepa が製品の変更を追跡し、通知します。
API を介した追跡では、Keepa アカウントとは別のリストが使用されます。
API 呼び出しを介して追跡する製品のみを表示および管理できます。
トラッキングはkeepaのwebページからでも設定できますが、webページとapiから設定するものは独立しているということみたいです。
知っておくべき重要事項:
追跡された製品ごとに、トークンの補充率が低下します。
補充レートが 0 に達すると、それ以上製品を追跡したり、トークンを必要とする API リクエストを作成したりできなくなります。
API アクセスが終了すると、アクセスが再開されない限り、追跡リストは無効になり、2 週間後に削除されます。
API プランをダウングレードし、新しいプランが追跡リストに十分なトークンを提供しない場合、リストの十分な数の追跡が無効になります。
トラッキングの費用を他の API の使用と分けたい場合は、それぞれ独自の API サブスクリプションを持つ 2 つの Keepa アカウントを使用できます。
トラッキングには次の 2 種類があります。
- 通常のトラッキング
次の価格タイプを追跡できます:
Amazon、新品、中古、リスト、収集品、再生品、Lightning Deal※1、すべての出品数、および販売ランク。 - マーケットプレイスのトラッキング
通常の追跡タイプに加えて、これにより、Warehouse Deals※2、ショッピングカートボックス、新しいサードパーティの FBA および FBM、評価、レビュー数、すべての中古品および収集品の状態を送料とともに追跡することもできます。
製品の最初の 20 件の出品が追跡に使用されます。
- ※1
Lightning Deal = 日本でいうタイムセール。 - ※2
Warehouse Deals = 日本でいうAmazonアウトレット。
Amazonが返品された商品など訳アリ品を販売するシステムです。
追跡対象の各 ASIN には、複数の Amazon ロケールごとに通知ルールを設定し、異なる更新間隔を設定できます。
これらの要因により、トラッキングごとにトークンの補充率がどれだけ削減されるかが決まります:
- 通常のトラッキング: 追跡される各ロケールの更新ごとに 0.9 トークン
- マーケットプレイスのトラッキング: 追跡される各ロケールの更新ごとに 9 トークン
トークン補充率は整数であるため、追跡削減率は四捨五入されます。
現在の削減率は、他のトークン統計とともに、すべての API 応答 (tokenFlowReduction フィールド) の一部です。
tokenFlowReduction は、追跡を追加または削除した直後ではなく、5 分ごとに更新されます。
トークン コストの例:
- 1 時間の更新間隔で 1 つのロケールで 2000 の通常のトラッキング:
2000商品 × 0.9トークン ÷ 1時間 = 1800 トークン/時
⇒30 トークン/分
⇒トークン補充率が30トークン減る - 12 時間の更新間隔で 1 つのロケールで 700 のマーケットプレイスのトラッキング:
700商品 × 9トークン ÷ 12時間 = 525 トークン/時
⇒8.75トークン/分
⇒トークン補充率が9トークン減る
※筆者注 最後に四捨五入されていることに注意
トークンレートが許す限り多くの製品を追跡できます。
他のリクエストと違い、トークン補充率が減るのが特殊です。
多くの人が登録しているであろうkeepaの最低価格のプランだと、5トークン/分の補充率です。
5トークン/分の場合、上記例のように通常トラッキングで1時間に1回更新する場合だと、350商品ほどでトークン補充率が0になります。
トークン補充率が0になると、トークンを使用する他のリクエストも不可になるので、トラッキングする商品はある程度厳選する必要があります。
名前付きトラッキングリスト
トラッキングオブジェクトの論理的な分離として機能する、名前付きのトラッキングリストを使用することができます。
これにより、同じ ASIN に対して複数の異なる追跡を行うことができます。
デフォルトでは、すべての追跡は名前のないリストで管理されます。
すべてのトラッキング リクエスト (Set Webhook を除く) は、追加のパラメーター listをサポートして、リクエストが作用するリストの名前を指定します (例: &list=user123)。
リスト名は最大 64 文字で、最大 100,000 個のリストを管理できます (さらに必要な場合はお問い合わせください)。
リストは最初に追加されたトラッキングで暗黙的に作成され、removeAll リクエストで削除できます。
トラッキングが名前付きリストに追加された場合、トラッキング オブジェクトは trackingListName に設定されたリスト名を持ちます。
同じことが通知オブジェクトにも当てはまります。
Get Named Lists リクエストを使用して、すべての名前付きリストのリストを取得できます。
リクエストのコマンド説明
API 追跡を管理するには、一連のコマンドが必要です。
- Add Tracking
トラッキングをリストに追加します。 - Remove Tracking
リストからトラッキングを削除するか、リスト全体をクリアします。 - Get Tracking
リストまたはリスト全体の製品のトラッキング情報を取得します。 - Get Notifications
最近の通知を取得します。 - Get Named Lists
すべての名前付きトラッキングリストのリストを取得します。 - Set Webhook
プッシュ通知を受信するように Webhook URL を更新します。
Add Tracking
基本情報
1トークン / 1トラッキング
リストに新しいトラッキングを追加します。
リストに 同じASIN のトラッキングがある場合は上書きされ、非アクティブ化されていた場合は再度アクティブ化されます。
1 回のリクエストで最大 1,000 個の追跡をバッチ処理して、複数の追跡を追加するプロセスを大幅に高速化できます。
リクエストのQueryパラメータ
HTTP GET または POST 要求のいずれかを選択できます。
GET形式
/tracking?key=<yourAccessKey>&type=add&tracking=<trackingJSON>- <yourAccessKey>
APIキー - <trackingJSON>
trackingJSON には、tracking creation objectsの配列が含まれています。
GET 形式を使用する場合は、URL エンコードする必要があります。
URL の長さには制限があるため、バッチ リクエストに GET メソッドを使用しないでください。
POST形式
/tracking?key=<yourAccessKey>&type=add- <yourAccessKey>
APIキー - POST ペイロードには、tracking creation objects を 1 つまたは配列で含める必要があります。
JSON 配列表記 [object, object, …] の 1 つのリクエストで、最大 1000 個のtracking creation objectを指定できます。
リクエストのレスポンス
作成/更新されたトラッキング オブジェクトを含むトラッキング配列フィールド。
エラーが発生した場合、エラー フィールドが設定されます。
追跡を追加できなかった場合、バッチリクエストは失敗せず、失敗したすべての ASIN のコンマ区切りリストがエラーフィールドに含まれます。
レスポンスの詳細はこちら↓↓↓の記事をご参考ください。
Remove Tracking
基本情報
必要トークン0
リストから 1 つのトラッキングを削除します。
リクエストのQueryパラメータ
/tracking?key=<yourAccessKey>&type=remove&asin=<ASIN>- <yourAccessKey>
APIキー - <ASIN>
トラッキングリストから削除する商品の ASIN
トラッキングを 1 つずつ削除する代わりに、次の 1 回の呼び出しですべてのトラッキングを削除することもできます。
/tracking?key=<yourAccessKey>&type=removeAllリクエストのレスポンス
トークン バケット情報のみ。
指定した ASIN の追跡がない場合、エラー フィールドが設定されます。
追跡を削除しても、tokenFlowReduction はすぐには更新されないことに注意してください。
Get Tracking
基本情報
必要トークン0
リストから単一の追跡を取得します。
リクエストのQueryパラメータ
/tracking?key=<yourAccessKey>&type=get&asin=<ASIN>- <yourAccessKey>
APIキー - <ASIN>
トラッキングを取得する商品の ASIN。
トラッキングを 1 つずつリクエストする代わりに、次の 1 回の呼び出しでリスト全体を取得することもできます。
/tracking?key=<yourAccessKey>&type=list&asins-only=<asinsOnly>多くの製品を追跡する場合、これはリソースを大量に消費する操作です。
責任を持って使用してください。
追跡対象のすべての ASIN のリストのみを取得する場合は、パラメータ asins-only に値「1」を指定できます。
これは、すべての追跡オブジェクトを取得するよりもはるかに高速な操作です。
リクエストのレスポンス
Tracking Object (常に配列) を含むtrackingsフィールド。
指定した ASIN の追跡がない場合、エラー フィールドが設定されます。
または、asin-only パラメータを使用したリスト操作の場合は、追跡されたすべての ASIN の文字列配列を含む asinList フィールド。
レスポンスの詳細はこちら↓↓↓の記事をご参考ください。
https://tonokokko.com/https-tonokokko-com-keepa-api-reference-tracking-object/Get Notifications
基本情報
必要トークン0
最近の通知オブジェクトを取得します。
通知は、この呼び出しを通じて配信されるか、Webhook にプッシュされると、既読としてマークされます。
通知は作成から 24 時間後に削除されます。
Webhook 経由のプッシュ通知を使用したくない場合、または Webhook エンドポイントがオフラインであった場合にのみ、この要求を使用してください。
リクエストのQueryパラメータ
/tracking?key=<yourAccessKey>&type=notification&since=<since>&revise=<revise>- <yourAccessKey>
APIキー - <since>
この日付以降に発生した利用可能なすべての通知を KeepaTime 分単位で取得します。 - <revise>
ブール値 (0 = false、1 = true)。
すでに既読としてマークされている通知を要求するかどうかを選択します。
リクエストのレスポンス
最新の順にソートされた、Notification Object を含む通知フィールドです。
常に配列です。
レスポンスの詳細はこちら↓↓↓の記事をご参考ください。
Get Named Lists
基本情報
必要トークン0
名前付きリストのすべての名前のリストを取得します。
(上記の名前付きトラッキングリストのセクションで詳細を参照してください)。
※筆者注 リンクはページ内リンクです。
リクエストのQueryパラメータ
/tracking?key=<yourAccessKey>&type=listNames- <yourAccessKey>
APIキー
リクエストのレスポンス
すべての名前付きリストの名前を含む trackingListNames フィールド。
常に配列です。
Set Webhook
基本情報
必要トークン0
通知がトリガーされるたびにサービスが呼び出す Webhook URL を更新します。
URL は、Web サイトから更新およびテストすることもできます。
プッシュ通知は、そのコンテンツとして単一のNotification Object を持つ HTTP POST 呼び出しになります。
サーバーは、正常に取得されたことを確認するために、ステータス コード 200 で応答する必要があります。
配信に失敗した場合、15 秒の遅延で 2 回目の試行が行われます。
備考:
POST のコンテンツ タイプは application/json であり、application/x-www-form-urlencoded ではありません。
PHP を使用する場合は、file_get_contents(‘php://input’) または $HTTP_RAW_POST_DATA を使用してコンテンツにアクセスする必要があります。
Notification Objectの詳細はこちら↓↓↓の記事をご参考ください。
リクエストのQueryパラメータ
/tracking?key=<yourAccessKey>&type=webhook&url=<URL>- <yourAccessKey>
APIキー - <url>
新しい Webhook URL
リクエストのレスポンス
更新が成功した場合はトークン バケット情報のみを返します。
指定された URL の形式が無効な場合、エラー フィールドが設定されます。
以上です！
リクエストによって返却されるレスポンスが異なります。
文中にも載せていますが、ユニークなレスポンスは
の3種類です。
リンクはそれぞれ解説記事なので、ご参考ください！
