一言コメント感情分析APIガイド

はじめに

本APIはニコニコメント感情分析室のコメント分析エンジンを外部から利用できるAPIです。以下の機能を提供しています。

  1. 単一のコメントをAPIサーバーに送信して感情分析結果を取得する。
  2. 複数のコメントをまとめてAPIサーバーに送信して感情分析結果を取得する。
  3. 本APIが定義している各感情の説明を取得する。

利用シーン(向き不向き)

本APIは現在のところ、ニコニコ動画のコメントを分析する用途のみに特化しているので、それに類するコメントであればそこそこの分析は可能です。逆に言うとそうでないコメントの場合は期待する結果が得られない可能性が高いです。

具体的には以下の条件を満たしていることが望ましいです。

一言かつ通常10文字以内

二言以上になると一文の中で複数の感情が発生しやすくなるので、「このコメントの感情は○○です」と断定しにくくなったり、断定した感情が間違いであるケースが多くなります。

○例

×例

口語体が中心

本感情分析エンジンは語尾も重視しています。したがって、くだけた表現のコメントの方が感情の分析はしやすいです。「w」の有無も重要なファクターとなっているのでそれくらい崩れたコメントの方が好みです。固いコメントだと感情を読み取れずに分類不能となるケースが多くなります。

○例

×例

ネットスラングを含む

ニコニコ動画でよく見かけるスラング的なコメントも感情分析対象となっているので、文章から一般的に連想される感情とは異なる結果を返す場合もあります。したがって、そういったスラングがあまり使われない分野でのコメントだと、適切な分析結果とは言いがたいものになるかもしれません。

向いていると思われる具体例

Twitch、AbemaTVのような視聴中にリアルタイムにコメントする動画サービスのコメント

向いているかもしれない具体例

2ちゃんねる系の掲示板の実況系スレッド(じっくり書き込む余裕がない系)の書き込み

向いていなさそうな具体例

Twitter、ヤフコメ、はてなブックマークなど長文がそれなりに多い傾向にあるサービスのコメント

その他注意事項

本APIのコメント分析エンジンはまだまだ発展途上なため、随時更新されていくことが予想されます。そのため、現状においては誤判定も多分に含みます。したがって、1つ1つのコメントの判定に間違いが許されないようなクリティカルな現場での使用に耐えるレベルではありません。

ニコニコメント感情分析室のように、まとまった件数のコメントの分析結果の統計を取り、その動画の大まかな傾向を調べるような用途であれば実用レベルであるかもしれません。

また、分析エンジンが随時更新されるという事は、まったく同じコメントでも分析したタイミングによって異なる判定結果が返ってくる可能性があるということになります。この点にもご注意ください。

なお、本APIは海外のフリープランのサーバーを使用しているのでレスポンスは遅いです。要望が多ければ国内のサーバーでの運用も検討しますが、費用などの観点から有料APIとなる可能性もあります。

API説明

エンドポイント

各API共通で以下のエンドポイントがベースURLとなります。

http://nicomment-api.ktty1220.me/v1

GET /single

単一のコメントの感情分析結果を取得します。

利用制限

同一IPアドレスにつき1秒に1回までの制限があります。

リクエストパラメータ

レスポンスJSON

以下のようなJSONが返ります。

{
  "status": "ok",
  "comment": "www",
  "emotion": "lol",
  "name": "笑い",
  "description": "語尾に「w」が付いていたり「~で草」といった爆笑系のコメントです。"
}

実演

ブラウザの開発者ツールのコンソールに実行結果が出力されます。

使用例

以下のサンプルソースはすべてUTF-8で書かれているという前提となっています。元のコメントがUTF-8でない場合は文字コードの変換処理を挟んでください。

ajax
$.ajax({
  url: 'http://nicomment-api.ktty1220.me/v1/single',
  data: {
    comment: 'www'
  }
}).done(function (result) {
  if (result.status !== 'ok') {
    return console.warn(result.status);
  }
  console.log(result);
}).fail(function (err) {
  console.error(err);
});
node.js
var request = require('request');

var params = {
  method: 'GET',
  url: 'http://nicomment-api.ktty1220.me/v1/single',
  qs: {
    comment: 'www'
  }
};

request(params, function (err, response, body) {
  if (err) {
    return console.error(err);
  }
  var result = JSON.parse(body);
  if (result.status !== 'ok') {
    return console.warn(err);
  }
  console.log(result);
});
php
$url = 'http://nicomment-api.ktty1220.me/v1/single';
$param = 'comment='. rawurlencode('www');

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url. '?'. $param);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$json = curl_exec($ch);
var_dump(json_decode($json, true));
curl_close($ch);
curl
curl 'http://nicomment-api.ktty1220.me/v1/single?comment=%EF%BD%97%EF%BD%97%EF%BD%97'

POST /multi

複数のコメントの感情分析結果を1回でまとめて取得します(最大1000コメント)。

利用制限

同一IPアドレスにつき10秒に1回までの制限があります。

リクエストパラメータ

このAPIはPOSTメソッドでJSON形式のパラメータを送信する形でリクエストします。具体的な呼び出し方は後述の使用例を参照ください。

レスポンスJSON

fullパラメータをtrueにした場合
{
  "status": "ok",
  "result": [
    {
      "comment": "うぽつー",
      "emotion": "greeting",
      "name": "挨拶",
      "description": "動画開始時の「うぽつ」や動画終了時の「乙」などです。"
    },
    {
      "comment": "自分草いいすか",
      "emotion": "lol",
      "name": "笑い",
      "description": "語尾に「w」が付いていたり「~で草」といった爆笑系のコメントです。"
    },
    {
      "comment": "今なんでもって",
      "emotion": "feed",
      "name": "ツッコミ",
      "description": "動画にツッコミを入れているコメントです。「いい加減にしろ」といったイライラなコメントでも「w」や「!」が付いている場合はきついツッコミとしてこちらに分類しています。"
    },
    {
      "comment": "きもいんだけど",
      "emotion": "critic",
      "name": "批判",
      "description": "悪い評価やダメ出しをしているコメントです。動画の内容でなく動画のテーマに関する話題(政治・社会問題など)で批判的なコメントが発生している場合もあります。"
    }
  ]
}
fullパラメータをfalseにした場合

リクエストパラメータのfullfalseにすると、レスポンスJSONのresult内の各分析結果からnamedescriptionが除外されます。

{
  "status": "ok",
  "result": [
    {
      "comment": "うぽつー",
      "emotion": "greeting"
    },
    {
      "comment": "自分草いいすか",
      "emotion": "lol"
    },
    {
      "comment": "今なんでもって",
      "emotion": "feed",
    },
    {
      "comment": "きもいんだけど",
      "emotion": "critic"
    }
  ]
}

大量のコメントを何度も処理する場合は、各感情の説明を別途/helpAPIで取得しておいて取得後のコメントと組み合わせるとネットワーク転送量を削減できます。

実演

ブラウザの開発者ツールのコンソールに実行結果が出力されます。

使用例

以下のサンプルソースはすべてUTF-8で書かれているという前提となっています。元のコメントがUTF-8でない場合は文字コードの変換処理を挟んでください。

ajax
var param = {
  comments: [
    'うぽつー',
    '自分草いいすか',
    '今なんでもって',
    'きもいんだけど'
  ],
  full: true
};

$.ajax({
  type: 'POST',
  url: 'http://nicomment-api.ktty1220.me/v1/multi',
  headers: {
    'Content-Type': 'application/json'
  },
  data: JSON.stringify(param)
}).done(function (result) {
  if (result.status !== 'ok') {
    return console.warn(result.status);
  }
  console.log(result);
}).fail(function (err) {
  console.error(err);
});
node.js
var request = require('request');

var params = {
  method: 'POST',
  url: 'http://nicomment-api.ktty1220.me/v1/multi',
  json: {
    comments: [
      'うぽつー',
      '自分草いいすか',
      '今なんでもって',
      'きもいんだけど'
    ],
    full: true
  }
};

request(params, function (err, response, body) {
  if (err) {
    return console.error(err);
  }
  if (body.status !== 'ok') {
    return console.warn(err);
  }
  console.log(body);
});
php
$url = 'http://nicomment-api.ktty1220.me/v1/multi';
$param = array(
  'comments' => array(
    'うぽつー',
    '自分草いいすか',
    '今なんでもって',
    'きもいんだけど'
  ),
  'full' => true
);

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($param));
curl_setopt($ch, CURLOPT_HTTPHEADER, array('Content-Type: application/json'));
$json = curl_exec($ch);
var_dump(json_decode($json, true));
curl_close($ch);
curl
curl -X POST -H 'Content-type: application/json' -d '{"comments":["\u3046\u307d\u3064\u30fc","\u81ea\u5206\u8349\u3044\u3044\u3059\u304b","\u4eca\u306a\u3093\u3067\u3082\u3063\u3066\u30fb\u30fb\u30fb","\u304d\u3082\u3044\u3093\u3060\u3051\u3069"],"full":true}' 'http://nicomment-api.ktty1220.me/v1/multi'

GET /help

本APIが定義している各感情の説明を取得します。

利用制限

同一IPアドレスにつき1秒に1回までの制限があります。

リクエストパラメータ

なし

レスポンスJSON

{
  "status": "ok",
  "emotions": {
    "unknown": {
      "name": "分類不能",
      "description": "感情の感じられないコメント、もしくは現段階の分析システムで分類することができなかったコメントです。"
    },
    "aa": {
      "name": "AA",
      "description": "コメントに改行が含まれていたり特殊な記号などで構成されているコメントなど、読むコメントではなく見るコメントです。"
    },
    "feed": {
      "name": "ツッコミ",
      "description": "動画にツッコミを入れているコメントです。「いい加減にしろ」といったイライラなコメントでも「w」や「!」が付いている場合はきついツッコミとしてこちらに分類しています。"
    },
    "irritate": {
      "name": "イライラ",
      "description": "「やれ」「しろ」「やめろ」といったきつい命令口調になっているコメントです。「w」や「!」が語尾についているときついツッコミ扱いとなりこちらには分類されません。"
    },
    "lol": {
      "name": "笑い",
      "description": "語尾に「w」が付いていたり「~で草」といった爆笑系のコメントです。"
    },
    "like": {
      "name": "称賛",
      "description": "良い評価をしているコメントです。中には皮肉的な内容のコメントが含まれているかも知れません。"
    },
    "critic": {
      "name": "批判",
      "description": "悪い評価やダメ出しをしているコメントです。動画の内容でなく動画のテーマに関する話題(政治・社会問題など)で批判的なコメントが発生している場合もあります。"
    },
    "cry": {
      "name": "感動",
      "description": "泣いた系や悲しい系のコメントです。"
    },
    "request": {
      "name": "要望",
      "description": "「~して欲しい」などのコメントです。「はよ」といった催促的な内容のコメントも含まれています。"
    },
    "response": {
      "name": "返事",
      "description": "動画投稿者の問いかけや宣言に対する返事です。"
    },
    "advice": {
      "name": "アドバイス",
      "description": "「~した方がいい」といった助言的な内容のコメントです。"
    },
    "surprise": {
      "name": "驚愕",
      "description": "驚きや「凄い」など尊敬に近い賞賛に関するコメントです。"
    },
    "abusive": {
      "name": "暴言",
      "description": "「氏ね」「ks」など、リアル社会の公的な状況では通常使用しないような汚い言葉を使用したコメントです。"
    },
    "greeting": {
      "name": "挨拶",
      "description": "動画開始時の「うぽつ」や動画終了時の「乙」などです。"
    },
    "exciting": {
      "name": "期待",
      "description": "「wktk」「楽しみ」など、ドキドキや期待に関するコメントです。"
    },
    "fever": {
      "name": "熱狂",
      "description": "語尾に「!」が付いていたり絶叫しているコメントです。絶叫でも「ぎゃああああ」などは恐怖に分類されるのでこちらには分類されません。"
    },
    "question": {
      "name": "疑問",
      "description": "語尾に「?」が付いていたり「~かな」といった質問・疑問的なコメントです。"
    },
    "fear": {
      "name": "恐怖",
      "description": "悲鳴や怯えといったコメントです。"
    },
    "exclude": {
      "name": "除外",
      "description": "一人で大量にコメントを投稿しており、一個人の感情が大きく反映されるといった適切な判定結果の妨げになる可能性があるので分析対象から除外されたコメントです。"
    }
  }
}

実演

ブラウザの開発者ツールのコンソールに実行結果が出力されます。

使用例

ajax
$.ajax({
  url: 'http://nicomment-api.ktty1220.me/v1/help'
}).done(function (result) {
  if (result.status !== 'ok') {
    return console.warn(result.status);
  }
  console.log(result);
}).fail(function (err) {
  console.error(err);
});
node.js
var request = require('request');

var params = {
  method: 'GET',
  url: 'http://nicomment-api.ktty1220.me/v1/help'
};

request(params, function (err, response, body) {
  if (err) {
    return console.error(err);
  }
  var result = JSON.parse(body);
  if (result.status !== 'ok') {
    return console.warn(err);
  }
  console.log(result);
});
php
$url = 'http://nicomment-api.ktty1220.me/v1/help';

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$json = curl_exec($ch);
var_dump(json_decode($json, true));
curl_close($ch);
curl
curl 'http://nicomment-api.ktty1220.me/v1/help'

利用制限について

現在のところ、どれくらいの利用があるのかが未知数なため、大事を取ってかなりケチくさい制限となっています。しばらく運用してみて余裕がありそうなら制限を緩める等の対応も検討しています。

利用条件

本APIは公序良俗に反しない範囲で、営利目的・商用利用を含むいかなる用途に使用することも可能ですが、下記利用規約に同意していることが条件となります。

利用規約

以下の条項に同意いただけない場合は本APIを利用することはできません(本APIを利用したことをもって本利用規約に同意したものとみなします)。

  1. 本APIを介して取得したコメントの分析結果を利用したことによって生じた直接的・間接的ないかなる結果・損害についてもAPI提供者は一切の責任を負わないものとします。

  2. API利用者と第三者との間で発生した紛争に対し、API提供者は一切関与しません。また、当該紛争等に関してAPI提供者に直接的・間接的な被害が生じた場合に発生した損害や費用については、API利用者がその賠償の責任を負うものとします。

  3. 本ドキュメントに記載されてない方法、形態での本APIの利用は禁止しています。そのような行為を発見した場合は、当該利用者のIPアドレスを無期限にアクセス停止することがあります。

  4. 利用制限を超えた過度なアクセス(制限が解けるタイミングまでアクセスし続ける等)や、利用制限の抜け道を突いて大量のリクエストを行った利用者のIPアドレスを無期限にアクセス停止することがあります。また、当該利用者の大量アクセスや不正アクセスによってに当サービスの運営に支障をきたした場合、当該利用者はAPI提供者に対しその賠償の責任を負うものとします。

  5. 本APIのエラーやバグ、その他の瑕疵がないことについてAPI提供者は保証しません。また、それらのエラーやバグが原因となってAPI利用者に発生したいかなる損害についてもAPI提供者は一切の責任を負わないものとします。

  6. API提供者は本APIの修正又は改良義務を負いません。

  7. API提供者は本APIの仕様の全部又は一部をAPI利用者への事前の通告なしにいつでも変更することができます。

  8. 本APIはAPI提供者の都合によりAPI利用者への事前の通告なしにいつでも提供を停止することができます。

2016/9/1制定