[Keepa API②] Keepa APIの肝、トークンの仕組みを詳しく解説

こんにちは！Ryoku(@ryoku_dev)です。

前回の記事ではKeepa APIでできることを中心にその概要を説明しました。この記事ではKeepa APIの制約であるトークンについて詳しく説明します。

トークンとはスタミナ

トークン(Token)という言葉は、ITの世界では文脈により異なる意味で幅広く使われる言葉です(認証では利用者が持つ鍵だったり、ブロックチェーンでは証明書だったり、ネットワークでは通行手形だったり)。

難しい話はさておき、Keepa APIにおけるトークンとは、スマホゲームで言うところのスタミナです。呼び出しの度に消費して、時間とともに回復する。課金をすれば回復レートと上限が増える。なんとも恐ろしいシステムです。

Keepa APIの機能と消費トークンの関係は以下の表のようになっています(前回記事の再掲)。

リクエスト名	説明	消費トークン
Request Products	上で説明したランキング変動など商品情報を参照します	1~ / ASIN
Searching for Products	キーワードからASINを検索します	25 / ページ
Category Lookup	カテゴリIDからカテゴリ名などを参照します	1 / カテゴリ
Category Searches	キーワードからカテゴリIDを検索します	1 / 回
Browsing Deals	Keepa独自の値下げ商品ページからASINを検索します	5 / 150件
Request Seller Information	セラーIDからセラー名や出品リストを参照します	1~10 / セラー
Request Best Sellers	カテゴリIDからベストセラー商品のASINリストを取得します	50 / 回
Most Rated Sellers	全体を通して最も評価が高いセラーのリストを取得します	50 / 回

ASINなどIDを渡す参照系のリクエスト(Request Productsなど)は、1IDにつき1トークン消費というように比較的低コストで使えます(実際は全くそんなことなくて恐ろしい罠が待っています。後述)。

一方で、条件を渡す検索系のリクエスト(Searching for Productsなど)は、結果1ページあたり25トークン消費というように高コストです。

Keepa APIの有料プランに入る必要はある？

おそらくこのページを読まれている大多数の人が契約しているだろう15€/月の有料プラン。これにも上限300トークン(毎分5トークン発生)がついております。

正直、モノレート の代わりとして販売数や価格変動を取るだけであれば300トークン=300ASIN/時でやりくりできるのではないかと思います。

ただし、大量のASINを集めてきて、一括で情報取得と絞り込みを行う、といった使い方をするならばKeepa API用の有料プランに入るべきでしょう。では、どのプランに入るべきか？

何度見ても分かりにくいプランです。

と思うじゃないですか普通。プランの中身を見る前に重要な前提を書いておきますね。

トークンは発生から1時間のみ有効。つまり保持できるトークンの上限は「発生レート×60分 」

39€のプランだと、上限は20トークン×60分＝1200トークンになります。これが最大貯められるトークンの量です。先ほど15€のプランの上限が300だと書いたのはこういう訳でした。

もう一つ、プランとトークンについてお伝えすることがあります。

プランは複数契約可能(同じプランに2つ入ってもよい)。その場合、発生トークンは足し合わされる。

ということで39€のプランに入った場合、元々入っている15€のプランと足し合わせて、上限1500トークンとなります。

結論！ 寝てる間にASINの大量取得と解析を繰り返す、という使い方でなく、PCの前に座りインタラクティブに使うのならば、15€プランでもなんとかなる。39€プランならかなり余裕。むしろこれで足りない場合は、前処理としてASINのフィルタリングを別の方法でやった方がいいです。

何かとトークンをせびってくるKeepa API

Request ProductsはASINから商品情報を取得し、1ASIN、1トークン消費します。1トークンでこのASINに関する情報をまるっと取れるかというと、全くそんなことはなく、何かと高くつくオプションが存在します。

例えば、

• レビュー(レート・個数)は追加で1トークン
• カート価格は追加で2トークン
• 出品情報を取ると6トークン/10件

1件6トークン・・・。しかも「6トークン払うんで10件分だけください」と言えません。指定できるのは20件からです。出品数が欲しいだけの場合はMWSを併用した方が良さそうです。

そのほかにも、セラーIDからセラー名などを取得するRequest Seller Informationも1セラー、1トークン消費します。このセラーが出品しているASINリストを取るためには追加で9トークン必要になります(ただ、これはその価値あるかも)。

おまけ：トークンのちょっとした疑問

トークンが残りいくつあるかはどうやって確認できますか？

Keepa APIページでリアルタイムに確認できます。
プログラム的に取得するにはRetrieve Token Statusというリクエストが用意されています(さすがに消費トークン0！)。残量だけでなく、次にトークンが発生するまでの時間や発生レートも取れます。

トークンが足りない状態でリクエストするとどうなりますか？

トークンが1でもあればリクエストは実行されます。足りない分はマイナスのトークンとして計上されます
(例：残量1の状態で、100トークン消費するリクエストをした場合、実行後の残量は-99になる)。

トークンが0またはマイナスの場合はリクエストがエラーになります(ただし、HTTPステータスコードは200のままで、レスポンスのJSONにerrorというキーが含まれます)。

まとめ

これまでに述べたKeepa APIのトークンの特徴を列挙します。

• トークンはAPIのリクエストの度に消費し、0になるとリクエストに失敗する
• トークンは1分ごとに規定量発生し、1時間で消滅する
• そのためトークンの保持上限は「発生レート×60」
• 発生レートは課金プランに応じて増えていく
• 15€/月の有料プランでも5トークン/分のトークンが付与される
• プランは複数契約(同じものも可)でき、トークンの発生レートは足し合わされる
• トークンの消費量はリクエストの種類や指定するオプションによって異なる
• 最小の消費量はRequest Productsの1ASIN 1トークン。ただし出品情報を取ると6トークン以上になる
• トークンの残りはKeepa APIページで確認可能
• トークンが1でも残っていれば、足りなくても実行可能。その後残りトークンがマイナスになる
• トークンがない場合はリクエスト時にエラーになる

そしてプラン選択についてのわたしの見解は

• 販売数や価格変動をインタラクティブに取得するだけならば15€でよし
• ASINを一括で処理して、ガンガン絞り込みをしたいなら39€がおすすめ
• バッググラウンドでASINの取得・解析も行いたい場合はそれ以上のプランへ

です。

公式を読んでも、やりたいことをやるのにどれだけトークンがいるのかがいまいち分かりにくい印象でしたが、
トークンの仕組み自体はとてもシンプルで開発側としては扱いやすいと思います(少なくともMWSのスロットルと比べれば！)。

この記事でトークンの仕組みを理解していただき、素晴らしいKeepa APIライフをお送りください！