[Keepa API⑤] セラーの出品商品や評価が取れる！Request Seller Informationについて詳しく解説

2020 6/28

2020年6月28日 2020年6月28日

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

Keepa API連続記事、5回目の今回はセラーIDから出品商品などセラーに関する様々な情報が取得できるRequest Seller Informationを説明します。

MWSではセラーに関してほぼ何も取れないのでこれは嬉しい！

Keepa API記事の3回目では商品情報を取得するRequest Productsを解説しましたが、こちらに比べると取得できる情報の種類もリクエスト方法もぐっとシンプルになります。

どんな情報が取得できる？

Request Seller Informationで取得できるの内、重要なものは次の6つです。

セラー名　sellerName
出品商品　asinList
出品商品の総数　totalStorefrontAsins
セラー評価　csv
主要な出品カテゴリ　sellerCategoryStatistics
FBA出品の有無　hasFBA

特に注目すべきは「出品商品」。セラーが出品中のASINリストをまるっと取れます。しかも数秒で数千というスピードで取れます。

また、その下の4つの情報を使えば「このセラーはリサーチすべきか否か」を定量的に評価できますね！例えば、

出品商品数：300以上
セラー評価個数：100以上
FBA出品の有無：有

なんて条件を設定すれば、中級者以上の有在庫セラーを絞り込むことができます。また、「主要な出品カテゴリ」を使って

おもちゃカテゴリの商品比率：20%以下

というような条件を設定すれば、自分が扱いたくない商品を多く出品しているセラーを除外できます。

その他にも、

中国出荷かどうか　shipsFromChina
詐欺セラーかどうか　isScammer

なんていうのも取れます。「詐欺セラー」はKeepaが独自に評価などから判定しているらしいです(未だこのフラグがたったセラーは見たことがありませんが)。

在庫数の取得はできる？

2020年現在、公式ドキュメントからは記載が消えているのですが、かつて各出品の在庫数を取得するオプションがありました(何と追加トークンなしで！)。リクエスト時に「stock=1」を指定すると、「offer.offer.stockCSV」で在庫数が取得できるというもの。

何とこれ、今でも使えるんです。が、返ってきたデータをよく見てみると、どれも2018年10月まで・・・。途中でKeepaは在庫数の取得をやめてしまったんですね。残念！

必要なトークンは？

基本的には1セラーにつき1トークン消費します。ただし、出品商品を取る場合には追加で9トークン必要です。出品商品の取得は失敗する(全く取れない、または1つだけ取れる)ことがあり、この場合追加トークンは支払われません。

なお、トークンの仕組みついては別記事で詳しく解説しています！

APIの実際の利用方法

Request Productsの解説記事と同様にレスポンスのデータから先に説明します。

Request Seller Informationのレスポンス

Request Seller Informationも他のリクエストと同様にJSON形式でレスポンスを返します。

公式には、

A sellers field containing an array of seller objects
https://keepa.com/#!discuss/t/request-seller-information/790

と、配列を返すとあるのですが、実際にはセラーIDをキー、Seller Objectを値としたオブジェクト(連想配列)を返します。Request Seller Informationのレスポンスのデータの具体例を以下に示します(番号のついたコメントは後で説明をつけています)。

{
  {"A0000000000001": //キーとなるセラーID
    {　//この波括弧の中が1つのSeller Object
      "domainId": 5,
      "sellerId": "A0000000000001",
      "sellerName": "A Seller",
      "asinList": ["B000000001", "B000000002", "B000000003", "B000000004", ...],
      "asinListLastSeen": [4988856, 4988852, 4988850, 4988848, ...], //[4]ASINの取得日時
      "totalStorefrontAsins": [4988850, 500], //[1]出品商品数
      "sellerCategoryStatistics": [
        {
          "catId": 13299531,
          "productCount": 124,
          "avg30SalesRank": 103100,
          "productCountWithAmazonOffer": 3
        }, //[2]主な出品カテゴリ
        ...
      ],
      "csv": [ //[3]レビュー
        [3455380, 100, 3575630, 94, 3576296, 100, 3659438, 97, ...], //レビューレート
        [3455380, 1, 3478446, 2, 3484796, 3, 3485748, 4, ...] //レビュー個数
      "hasFBA": true,
      "isScammer": true,
      "shipsFromChina": Boolean,
      ...
    }
  },
  ...
}

[1]出品商品数 totalStorefrontAsins

出品商品のASINリストを取るために9トークン払わなくても取れます。ある意味ASINリストの長さと同義ですが、ASINリストには必ずしも出品中の全てのASINが入っている訳ではないので、総数を知るにはこちらの方が正確です。なお、形式は[タイムスタンプ, 出品商品数]という要素数が2の配列です。

Keepa独自のタイムスタンプ

Keepa APIの中に出てくるタイムスタンプ、実は「Keepa time minutes」なる独自のものです。一般的に使われるUNIX時間に変換するには以下の計算をします。

(Keepa time nimutes + 21564000) * 60 = UNIX時間

[2]主な出品カテゴリ sellerCategoryStatistics

そのセラーが多く出品しているカテゴリのリストです。カテゴリID以外にも以下の情報が含まれます。「カテゴリに含まれる出品商品数」が取れるので、そのセラーの出品商品のカテゴリ別比率も計算できますね。

カテゴリID catId
カテゴリに含まれる出品商品数 productCount
カテゴリに含まれる商品の平均ランキング(30日) avg30SalesRank
Amazon本体が出品している商品数 productCountWithAmazonOffer

なお、カテゴリIDの中身は、別途Category Lookupというリクエストを行うか、「https://www.amazon.co.jp/b/?node=」の後につけてページを開いてみると分かります。

[3]レビュー csv

一行目がレビューレート、二行目がレビュー個数の二次元配列です。各配列は[タイムスタンプ 1, レビューレート1, タイムスタンプ2, レビューレート2, ・・・]と言うようにタイムスタンプと値が時系列順に交互に並びます。最新の値を取得するには次のようにします。

const lastReviewRate = csv[0][csv[0].length - 1];
const lastReviewNum = csv[1][csv[1].length - 1];

[4] ASINの取得日時 asinListLastSeen

asinList(出品商品のASINリスト)のASINの並びと対応し、「セラーがそのASINを出品していることをKeepaが確認したタイムスタンプ」が格納された配列です。(例: 10番目のASIN、asinList[9]に対応するタイムスタンプはasinListLastSeen[9])

そのデータはいつのもの？

これまでデータの鮮度という観点の話をしてきませんでしたが、Keepaが提供するデータは常に最新の状態のものということではなく、過去のある時点で取得したものになります。そして、データ毎に取得時点が異なります。

ここで、Request Seller Informationをリクエストする際に「update=N(Nは○時間前を表す整数)」というオプションをつけることで、もしASINリストの最終更新日時が指定の時間よりも古い場合は、最新のデータを取りに行かせることができます。その場合にはトータルで50トークン必要になります。ただ、セラーリサーチでそこまで最新のデータにこだわるケースは少ないので、使う場面はあまりなさそうです。

Request Seller Informationのリクエスト

Keepa APIのリクエストの概要はこれまたRequest Productsの解説記事で解説していますので、今回はいきなりGoogle Apps Script(GAS)のサンプルコードを貼っておきます。

const key = "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx";
//本来はPropertyなどから読み出す

const sellerIdList = ["A0000000000001", "A0000000000002", "A0000000000003"].join();
//本来はSpreadsheet上などから取得する

const endpoint = 'https://api.keepa.com/seller';
const payload = { 
　key,
　seller: sellerIdList,
　domain: '5', //1:com 2:co.uk 3:de 4:fr 5:co.jp 6:ca 8:it 9:es 10:in
　storefront: '1', //1:出品商品を取得する(+9トークン)　0:取得しない
};

//リクエスト実行
const response = UrlFetchApp.fetch(endpoint, { method: 'post', payload });
const content = response.getContentText();
    
//JSONデータのパース
const json = JSON.parse(content);
if (json.error) {
  throw new Error(json.error.message); //エラーが発生した場合、レスポンスは"error"というキーを含む
}
const sellers = json.sellers;

//取得情報の表示
for(const sellerId of sellerIdList) {
  const seller = sellers[sellerId];
  if(!seller) continue;

  const { sellerName, asinList, totalStorefrontAsins, csv, sellerCategoryStatistics, hasFBA } = seller;

  console.log('セラー名', sellerName);
  console.log('出品商品', asinList);
  console.log('出品商品数', totalStorefrontAsins);
  console.log('セラーレビューレート', csv[0][csv[0].length - 1]);
  console.log('セラーレビュー個数', csv[1][csv[1].length - 1]);
  sellerCategoryStatistics.forEach(stats => {
    const { catId, productCount, avg30SalesRank, productCountWithAmazonOffer } = stats;
    console.log(`カテゴリID:${catId} 商品数:${productCount} 平均ランキング:${avg30SalesRank} Amazon本体出品数:${productCountWithAmazonOffer}`;
  }
  console.log('FBA出品', hasFBA ? '有' : '無');
}

ほぼ、Request Productsの場合と同じ流れです。指定できるセラーIDの上限が100というところも同じです。

唯一注意するのは、sellersは配列ではなくセラーIDをキーとした連想配列になりますので、sellersではなくセラーIDのリスト(sellerIdList)でループを回しています。

まとめ

MWSでは取れないセラー情報を取得するというKeepa APIならではのリクエストRequest Seller Informationを紹介しました。

Request Seller Informationを使うと、セラーの出品商品を高速で取得できる上に、セラーを評価するための指標となる次の情報が取得できます。

出品商品の総数
セラー評価
主要な出品カテゴリ
FBA出品の有無

前回の記事ではRequest Productsと一部このRequest Seller Informationを使って商品情報を取得するツールをご紹介しました。