【2022年 Twitter API】ツイート収集したい人向けのTwitter APIの種類と使い分け

# Twitter API､ややこしくないですか…？

この記事では自分の情報の整理を兼ねて､自分が今理解している範囲で､
**ツイート収集に関するTwitter APIの種類**についてまとめます｡

筆者の理解不足などで､記述に不正確な点があるかもしれません｡
気付いた点があればコメントいただけると幸いです｡

実際にツイートを収集する方法は､機会があれば別の記事にまとめます｡

# この記事の想定読者
- Twitter APIを使ってツイートの収集をしてみたい
- そのために､Twitter APIの種類について基本的なことを知りたい

なお､この記事ではTwitter API利用の中でも､**ツイートを収集すること**に主眼を置きます｡
その他のAPI利用については言及しません｡

# TwitterAPIの種類
Twitter APIの公式ドキュメントはこちらです｡

- [Twitter API](https://developer.twitter.com/en/docs/twitter-api)

ツイートを検索(収集)するためのAPIについて､
筆者が理解できている範囲で以下のように整理しました｡


API version | Access Level | Endpoint | Plan | 備考
---------|----------|---------|---------|---------
 v1.1 | Standard | Recent search | -- | 要申請､無償
 v1.1 | Premium | 30 day reseach | Sandbox | 要申請､無償
 v1.1 | Premium | 30 day reseach | Premium plan… | 要申請､有償
 v1.1 | Premium | Full-archive search | Sandbox | 要申請､無償
 v1.1 | Premium | Full-archive search | Premium plan… | 要申請､有償
 v1.1 | Enterprise: Gnip 2.0 | Details unknown | -- | 詳細不明
 v2 | Essential | Recent search | -- | Sign upのみで利用可<br>無償
 v2 | Elevated | Recent search | -- | 要申請､無償
 v2 | Elevated+ | Details unknown | -- | 詳細不明
 v2 | Academic Research | Full-archive search | -- | 学術研究利用に限定<br>無償
<!--  

- v1.1
  - Standard v1.1
    - recent search
  - Premium v1.1
    - 30 day search
      - sandbox
      - Premium plan …
    - Full-archive search
      - sandbox
      - Premium plan …
  - Enterprise: Gnip 2.0
- v2
  - Essential
    - Recent search
  - Elevated
    - Recent search
  - Elevated+
    - Recent search
  - Academic Research
    - Full-archive search -->


各階層は以下の要素で分かれています｡
1. API version(v1.1/v2)
2. Access level(Standard,Premium…/Essential,Elevated…)
3. Endpoint(recent search, 30 day search…)
4. Plan(sandbox/Premium…)


まず､主な系統として､**v1.1**と**v2**があります｡
現在主要な方はv2なのですが､順番的にv1.1から先に説明します｡

# v1.1について
v1.1には､以下の3種類のアクセスレベルがあります｡


- Standard v1.1
- Premium v1.1
- Enterprise: Gnip 2.0

アクセスレベルの種類によって､取得できるツイート数の上限や､利用できる検索式などが異なります｡
下のアクセスレベルになるほどグレードが高く､できることが増えます｡

v2のアクセスレベルの表を見る限り､
いずれも**v2のElevatedのアクセスレベルが必要**なようです｡[^6]


![スクリーンショット 2022-04-20 22.59.11.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2602439/b36e325d-89b2-05e2-a3ee-82a092f2a94b.png)

アクセスレベルの話が二重に出てきているようでややこしいです｡
現在申し込むと自動的にv2のアクセスレベルが割り振られて､
Elevatedになれば過去のAPIのバージョン(v1.1)にもアクセスできるようになる､
ということなのでは…と推測しています

## Standard
v1.1のStandardでは直近7日間のツイートが収集できます｡
ただ､直近7日間のツイートであればv2でも可能です｡

v1.1を使うにはElevatedのアクセスレベルが必要なので､
これからツイート収集を始める場合には､基本的にv2の方が良さそうです｡[^2]
[^2]:公式ドキュメントの Please note を参照｡ 
[Search Tweets: Standard v1.1](https://developer.twitter.com/en/docs/twitter-api/v1/tweets/search/api-reference/get-search-tweets#:~:text=Standard%20search%20API-,Please%20note,-We%20recently%20released)


StandardのAPIについては､以下をご参照ください｡
- [Search Tweets: Standard v1.1 API reference](https://developer.twitter.com/en/docs/twitter-api/v1/tweets/search/api-reference/get-search-tweets)

## Premium
Premiumは基本的に有償で利用するアクセスレベルです｡

しかし､**Sandbox**という無償で利用できるプランもあります｡
有償プランと比べるとできることは大きく制限されますが､お金がかからないのはありがたいです｡

Premiumで利用可能になるエンドポイントは以下の2種類です｡
- 直近30日分のツイートを収集できる **30 day search**
- 過去のすべてのツイートを収集できる **Full-archive search**

このPremiumのSandboxを使えば､**直近7日間より前のツイート**を無償で収集できます｡

v2では基本的に直近7日間のツイートしか収集できないため､
ツイート収集可能な期間が長いことは､筆者にとって大きなメリットでした｡

ただし､残念ながらSandboxは大量のツイート収集には適していません｡
具体的には､以下のようなツイート取得の上限があります｡

- 直近30日分のツイートは最大で25,000件/月
- 過去のすべてのツイートは最大で5,000件/月

大量のツイートを収集したい場合には､Premiumの有償利用か､v2の利用をおすすめします｡
(後ほど説明しますが､v2では直近7日間のツイートを最大200万ツイート収集できます)

とはいえ､有償の場合でも､無制限にツイートを収集できるわけではありません｡

たとえば"30 day search"の場合､最小限の$149(日本円だと2万弱？)のプランであれば､
理論的には以下の計算に基づき､最大25万ツイート収集が可能なはずです｡



![スクリーンショット 2022-04-23 16.52.41.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2602439/31588621-b940-7d35-93bc-ceb1b127538f.png)

`500(Tweets per Request) * 500(Total Requests) = 250,000`

Sandboxと比較して､最大で10倍のボリュームです｡すごいですね｡[^4]
[^4]:筆者はお財布と相談した結果､有償利用はしませんでした｡


Premiumの料金プランについては､以下のページをご参照ください｡

- [30 day search pricing](https://developer.twitter.com/en/pricing/search-30day)
- [Full-archive search pricing](https://developer.twitter.com/en/pricing/search-fullarchive)


また､Premiumで使える検索式は以下に記載があります｡

- [Rules and filtering: Premium v1.1](https://developer.twitter.com/en/docs/twitter-api/premium/rules-and-filtering/operators-by-product)


## Enterprise
Enterpriseについては､詳細な情報を得られなかったため割愛します｡
個人レベルで利用することはほとんどないのではと思います｡

# v2について
v2には､以下の4つのアクセスレベルがあります｡[^6]
[^6]:[Twitter API access levels and versions](https://developer.twitter.com/en/docs/twitter-api/getting-started/about-twitter-api#:~:text=Twitter%20API%20access%20levels%20and%20versions)

※ 画像再掲
![スクリーンショット 2022-04-20 22.59.11.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2602439/b36e325d-89b2-05e2-a3ee-82a092f2a94b.png)


- Essential
- Elevated
- Elevated+
- Academic Research

基本的にv2で収集できるツイートは**直近7日間のツイートに限定されます**｡[^8]
例外的に､Academic Researchだけは過去のすべてのツイートを収集できます｡

[^8]:[Search Tweets Recent search](https://developer.twitter.com/en/docs/twitter-api/tweets/search/introduction#:~:text=getting%20started%20guide.-,Recent%20search,-The%20recent%20search)

以下､順に説明します｡

## Essential
Essentialは無料で利用できるアクセスレベルです｡
**最大50万件/月**までツイートを取得できます｡

単にSing upすれば使えるようになるようですが､
他のコースよりもできることは限定されます｡

Essentialを使ってみて､本格的にツイート収集をしたくなったら
次に説明するElevatedを申請するとよいかと思います｡

## Elevated
Elevatedも無料で利用できるアクセスレベルです｡
**最大200万件/月**までツイートを取得できます｡

また､Elevatedのアクセスレベルであればv1.1のAPIも使えます｡

ただし､ElevatedではSing upをすることに加えて､追加の申請が必要になります｡
「こういう目的で使いますよ」という内容を英語で送って､審査に通れば使えるようになるはずです｡

審査には数日要することもあるようなので､日程に余裕を持って申請することをおすすめします｡

筆者は2021年頃に以下のページを参考にさせていただき､申請をしました｡

- [ITTI STAFF BLOG 2021年度版 Twitter API利用申請の例文からAPIキーの取得まで詳しく解説](https://www.itti.jp/web-direction/how-to-apply-for-twitter-api/)

## Elevated+
Elevated+はElevatedの上位版のようです｡

おそらくv1.1のPremiumに相当する有償版のアクセスレベルだと思います｡
詳細はまだ表に記載がありませんでした｡"coming soon"とのことです｡

## Academic Research
Academic Researchはその名のとおり**学術研究専用**です｡
**最大1000万件/月**までツイートを取得できます｡

単に大学生であれば利用できるわけでもなく､
大学院生以上で､研究に利用する明確な目的が必要なようです｡[^5]
[^5]:筆者はこの要件を満たしていないためFull-archiveの方は利用できません｡残念です｡


# 結局､どのアクセスレベル/エンドポイントを利用すればよいのか
- ツイートの収集をまず試してみたい
→ v2のEssentialがおすすめ
- より本格的に大量のツイートを収集したい
  → v2のElevatedがおすすめ
- 直近7日間よりも前のツイートを収集したい
→ まずはv1.1のPremiumのSandboxがおすすめ
(ただしSign upに加えて､追加の申請が必要)
より大量のツイートを取得したい場合には有償プランが必要

# まとめ
- ツイートの収集の仕方にはいろいろ種類がある！
- とりあえずv2のEssentialからはじめるのがおすすめ！

※表再掲

API version | Access Level | Endpoint | Plan | 備考
---------|----------|---------|---------|---------
 v1.1 | Standard | Recent search | -- | 要申請､無償
 v1.1 | Premium | 30 day reseach | Sandbox | 要申請､無償
 v1.1 | Premium | 30 day reseach | Premium plan… | 要申請､有償
 v1.1 | Premium | Full-archive search | Sandbox | 要申請､無償
 v1.1 | Premium | Full-archive search | Premium plan… | 要申請､有償
 v1.1 | Enterprise: Gnip 2.0 | Details unknown | -- | 詳細不明
 v2 | Essential | Recent search | -- | Sign upのみで利用可<br>無償
 v2 | Elevated | Recent search | -- | 要申請､無償
 v2 | Elevated+ | Details unknown | -- | 詳細不明
 v2 | Academic Research | Full-archive search | -- | 学術研究利用に限定<br>無償



# 余談
- ツイート検索のAPIの仕様はv1.1とv2とで若干異なります
- よって､ツイートを収集するためのコードは**v1.1とv2とで別々に必要**になるはずです
- v2もv1.1も使いたい人向けに両方のコードを記事にする…かもしれません