API・SDK

keepa APIで残トークン数がなくなった時に返されるJSONデータ

keepa-アイキャッチ

こんにちは!ゆーたろうです。

keepa APIでは、トークンという概念を使って、keepaが保有しているデータベースにアクセスできます。

このトークン数は契約しているプランによって増減しますが、0になった場合に返されるJSONデータが分かったので、その備忘録です。

トークンとは?

keepaにアクセスするためのアクセス権とお考え下さい。

このトークン数は契約プランによって変化します。

1トークン消費するのは、1ASINごとにです。

他のAPIでよくある「リクエスト数」で消費するタイプではないので注意が必要です。

また、一番低額のプランだと、1時間に使えるトークン数が1200。1分間に20トークンが回復する流れになっています。

そのため、

https://api.keepa.com/product/?key=キー&asin=B07XV8VSZT,B084HPMVNN&domain=5&category=1

というようなリクエストURLを発行した場合、消費されるトークンは2です。

1回のリクエストで2トークン消費されるということになります。

トークンの残りが0になった場合は?

残トークン数が0の時に上記のリクエストURLを送ってみましょう。

すると以下のようなJSONが返ってきます。

{
	"timestamp": 1594177158252,
	"tokensLeft": 0,
	"refillIn": 38205,
	"refillRate": 20,
	"tokenFlowReduction": 0,
	"tokensConsumed": 0,
	"processingTimeInMs": 0
}

【tokensLeft】が残トークン数に当たります。

この例でいうと、0になっています。

つまり、その時間ではもうデータベースにアクセスできないことを意味します。

また、以下のように、tokenLeftがマイナスの値になることもあります。

{
	"timestamp": 1594176918934,
	"tokensLeft": -1,
	"refillIn": 36722,
	"refillRate": 20,
	"tokenFlowReduction": 0,
	"tokensConsumed": 0,
	"processingTimeInMs": 0
}

画像取得APIも不可になる

https://api.keepa.com/graphimage?key=キー&asin=B084HPMVNN&domain=5&amazon=1&new=1&salesrank=1

折れ線グラフの画像を取得するリクエストURLはこちらになりますが、tokenLeftが0以下の場合はこのリクエストも失敗します。

グラフ画像も取得できなくなります。

以下が、残トークン数が0の時のグラフ画像APIのレスポンス結果です。

{
	"timestamp": 1594177160162,
	"tokensLeft": 0,
	"refillIn": 36295,
	"refillRate": 20,
	"tokenFlowReduction": 0,
	"tokensConsumed": 0,
	"processingTimeInMs": 0
}

トークン数がなくなれば、どのリクエストも、このようなフォーマットでJSONが返ってくることになります。

ちゃんとtokenLeftを検査して処理を分けよう

例えば、PHPならこんな感じで、取得されたJSONデータを最初に検査したほうが無難ですね。

if( $json['tokenLeft'] <= 0 ){
	return;
}

//各種データ取得処理
:
:

まとめ

KEEPAによらず他のAPIサービスもそうですが、レスポンスJSONには必ず取得結果が入っているので、そのレスポンス結果の値を確認してから、各要素へのアクセスをしていきましょう。