Twitter検索の結果をCSVに保存するツール「tw2csv」を作った

Twitter検索からツイート一覧をCSV形式で取得できれば様々な用途に使えます。RやPythonで各種統計処理を実施する方も多いでしょう。
しかし、かゆいところに手が届くようなツールがなかったのでNode.jsでコマンドラインツール「**[tw2csv](https://www.npmjs.com/package/tw2csv)**」[^1]を作ってみました。

もし需要があればGUI化するかもしれませんが、今のところはコマンドラインツールです。

<img src="https://qiita-image-store.s3.amazonaws.com/0/185296/2e1ab6bf-ae7a-6157-e01f-d629f5cf7aab.png" width=50%>

## 機能

- クロスプラットフォーム
    + Node.js で書かれているため、Windows/MacOS/Linuxで動作します。
- コマンド1つで15分あたりの取得上限である最大18,000件まで取得可能
    + もちろん最大値なので、botやリツイートを除去するとそこまで至らない場合の方が多いです。
    + Twitter APIの都合で、無料APIであれば最大1週間前までしか取れないので、あまりツイートされていないワードであれば先に期間制限の方が来ると思います。
- botの検知
- リツイートの検知
- ツイート本文以外の情報も詳細な取得可能
    +  投稿日時
    +  ツイートのID（数字）
    +  ツイート本文
    +  Twitterクライアント名
    +  言語（言語コード）
    +  位置情報（ある場合のみ）
    +  被リツイート数
    +  被いいね数
    +  ユーザ情報
        +  ユーザID（数字）
        +  ユーザのスクリーンネーム
        +  ユーザの名前
        +  ユーザのプロフィール
            + 場所[^2]
            + プロフィール文
            + 鍵垢かどうか[^3]
            + 累計ツイート数
            + フォロー数
            + フォロワー数
            + リスト数
            + お気に入り数
            + ユーザの登録日時
            + 認証済みかどうか


動作の様子
![tw2csv.gif](https://qiita-image-store.s3.amazonaws.com/0/185296/12812c52-6e85-3674-0c7f-a4fdf89f9a05.gif)


## インストール

### Node.js のインストール

動作するにはNode.jsが必要です。（Node使いの方はこの解説をすっ飛ばして `npm install` してください）
普段Node.jsを使っておらず、特にこだわりがない場合は [公式サイト](https://nodejs.org/ja/) から「安定版」をインストールしてください。

インストール後、ターミナル（WindowsであればコマンドプロンプトやPowerShell）から

```sh
node -v
npm -v
```

を叩いて、バージョンが表示されればOKです。

### tw2csvのインストール

ターミナルで以下のコマンドを入力してください。

```sh
npm install -g tw2csv
```

## 使い方

### セットアップ

まずは　[apps.twitter.com](http://apps.twitter.com) からアプリケーションを登録します。使用するTwitterアカウントは何でもよいのですが、最近は電話番号が登録されているアカウントでないとアプリケーションを登録できないようなのでお気をつけください。

**追記**（2018/10/12）: 2018年7月より、Twitter側の仕様変更により、[developer.twitter.com](https://developer.twitter.com/)からの登録が必要になったようです。

4種類のキー/トークン（Consumer Key, Consumer Secret, Access Token, Access Token Secret）を取得し、控えておいてください。
この手順がよく分からない方は「[Twitter API Key を取得する方法 (phiary.me)](http://phiary.me/twitter-api-key-get-how-to/)」などを参考にしてください。

続いて、任意の作業フォルダを作成した上でターミナルからそのフォルダに移動し、

```sh
tw2csv
```

と叩いてください。 `npm init` するような感覚です。
すると、`tw2csv-config.json` というJSONファイルが生成されるので、先程取得した4種類のキーをJSONファイル内の所定の位置に貼り付けてください。（コピペする際にスペースなどが混じらないように気をつけてください。）

### 検索

```sh
tw2csv search "検索ワード" 保存ファイル名.csv
```

botとリツイートは検索結果から除外されます。
bot/RTを含んで最大で18,000件のツイートが取得できますが、大抵の検索ワードでbotやリツイートが存在するほか、Twitter APIの仕様によって1週間より前のツイートは取得できないため、実際はそれ未満になると思います。

#### オプション

- `--bots` - botの可能性があるツイートも含めます。OAuthを用いた連携アプリからのツイートを拾いたい場合にご利用ください。また、bot検知機能自体がマイナーなクライアントには対応していないため、誤検知が怖い場合にもご利用ください。
- `--retweets` - リツイートを除外しません。（2018/05/30追記: 0.1.4から追加）


### ストリームからリアルタイム検索
Notice: [User Streamsは2018年6月に廃止](https://blog.twitter.com/developer/ja_jp/topics/tools/2017/aaa.html)されますが、Public Streamsは当面廃止されないようです。

```sh
tw2csv stream "Search Keywords" 保存ファイル名.csv
```

- 実験的機能です
    + Twitterの技術的制約により、分かち書きされない言語（日本語、中国語、韓国語など）は正常にフィルタできません。
    + 接続が思いがけないタイミングで切断される可能性がありますが、自動再接続は行いません。

### APIリミット確認

Twitterの検索APIには180リクエスト/15分という上限が存在します。
現在の制限状況と制限のリセット時刻を確認するコマンドです。

```sh
tw2csv limit
```

## 開発
tw2csv開発の経緯とメモです。
### 要件

- ローカルで動く
    + Webサービスは突然終了する可能性があるため、研究や実務でそれらに依存するのは危なっかしい。
        + 実際、2017年にサービスを終了してしまった検索結果保存サービスが存在する。
- アプリケーションのConsumer Keyは利用者が用意する
    + 万が一、アプリがBAN[^4]されたとしても利用者が巻き添えにならない。
    + 手間取ることはせずに設定ファイルにベタ書きできる感じで。
- Twitter APIの上限(18,000件)まで全自動で取得できる
    + なぜか1,500件が上限のものが多い。少なくとも2018年5月現在、最大で18,000件（1ページあたり100件×リクエスト180回）取得できるはず。
    + 100件ずつ手動で件数を増やしていくサービスが存在したが、一度ならともかく何度も実行するのはつらい。
- Streamからも拾いたい
    + リアルタイム検索をCSVに保存していきたい
- bot検知機能
  + SNSを検索する場合、たいていは人間のリアクションを知りたいのであって、botのツイートはノイズでしかない場合が多い。
  + ホワイトリストに登録されたメジャーなクライアント以外を除外したい。
- APIアクセス制限をすぐ把握したい
    + 無料で使える検索APIは180件/15回のリクエストまでしか処理できない。案外すぐ引っかかる。 
    + あと何件くらい検索回せるのか、何時になったら制限がリセットされるのかを知りたい。

### cac.js

コマンドラインツール用のフレームワークとして、[cac.js](https://www.npmjs.com/package/cac)を利用しました。フレームワークに頼らなくとも引数の取得は`process.argv`で簡単に出来ますが、オプションの組み合わせなどで複雑になってくると意外と面倒なので、予めこういったフレームワークを使うと（機能拡張するときに）楽だと思います。

### ツイート検索を再帰で掘っていく
こちらは [Node.jsでTwitter検索から100件を超えるツイートを取得したい](https://qiita.com/ryo-a/items/53fe9eadcf719b817c9a) に書きました。


---
[^1]: ツイートゥCSV（twee-to-C-S-V）とでもお読みいただければ幸いです。
[^2]: ユーザが自由に入力できる欄なので信頼はできませんが
[^3]: ただし、自分がフォローしているユーザでなければ検索結果に鍵垢のツイートは表示されません
[^4]: ちょうどこのツールを作っている間にも、[クライアント自体がBANされた事例](http://mikutter.hatenablog.com/entry/2018/05/05/164014)が発生していました。ユーザの凍結もそうですが、最近のTwitterはこの辺がいまいち信頼できないのがつらいところです。