Twitter API､ややこしくないですか…？
この記事では自分の情報の整理を兼ねて､自分が今理解している範囲で､
ツイート収集に関するTwitter APIの種類についてまとめます｡
筆者の理解不足などで､記述に不正確な点があるかもしれません｡
気付いた点があればコメントいただけると幸いです｡
実際にツイートを収集する方法は､機会があれば別の記事にまとめます｡
この記事の想定読者
- Twitter APIを使ってツイートの収集をしてみたい
- そのために､Twitter APIの種類について基本的なことを知りたい
なお､この記事ではTwitter API利用の中でも､ツイートを収集することに主眼を置きます｡
その他のAPI利用については言及しません｡
TwitterAPIの種類
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のみで利用可 無償 |
| v2 | Elevated | Recent search | -- | 要申請､無償 |
| v2 | Elevated+ | Details unknown | -- | 詳細不明 |
| v2 | Academic Research | Full-archive search | -- | 学術研究利用に限定 無償 |
各階層は以下の要素で分かれています｡
- API version(v1.1/v2)
- Access level(Standard,Premium…/Essential,Elevated…)
- Endpoint(recent search, 30 day search…)
- 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のアクセスレベルが必要なようです｡1
アクセスレベルの話が二重に出てきているようでややこしいです｡
現在申し込むと自動的にv2のアクセスレベルが割り振られて､
Elevatedになれば過去のAPIのバージョン(v1.1)にもアクセスできるようになる､
ということなのでは…と推測しています
Standard
v1.1のStandardでは直近7日間のツイートが収集できます｡
ただ､直近7日間のツイートであればv2でも可能です｡
v1.1を使うにはElevatedのアクセスレベルが必要なので､
これからツイート収集を始める場合には､基本的にv2の方が良さそうです｡2
StandardのAPIについては､以下をご参照ください｡
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万ツイート収集が可能なはずです｡
500(Tweets per Request) * 500(Total Requests) = 250,000
Sandboxと比較して､最大で10倍のボリュームです｡すごいですね｡3
Premiumの料金プランについては､以下のページをご参照ください｡
また､Premiumで使える検索式は以下に記載があります｡
Enterprise
Enterpriseについては､詳細な情報を得られなかったため割愛します｡
個人レベルで利用することはほとんどないのではと思います｡
v2について
v2には､以下の4つのアクセスレベルがあります｡1
※ 画像再掲
- Essential
- Elevated
- Elevated+
- Academic Research
基本的にv2で収集できるツイートは直近7日間のツイートに限定されます｡4
例外的に､Academic Researchだけは過去のすべてのツイートを収集できます｡
以下､順に説明します｡
Essential
Essentialは無料で利用できるアクセスレベルです｡
最大50万件/月までツイートを取得できます｡
単にSing upすれば使えるようになるようですが､
他のコースよりもできることは限定されます｡
Essentialを使ってみて､本格的にツイート収集をしたくなったら
次に説明するElevatedを申請するとよいかと思います｡
Elevated
Elevatedも無料で利用できるアクセスレベルです｡
最大200万件/月までツイートを取得できます｡
また､Elevatedのアクセスレベルであればv1.1のAPIも使えます｡
ただし､ElevatedではSing upをすることに加えて､追加の申請が必要になります｡
「こういう目的で使いますよ」という内容を英語で送って､審査に通れば使えるようになるはずです｡
審査には数日要することもあるようなので､日程に余裕を持って申請することをおすすめします｡
筆者は2021年頃に以下のページを参考にさせていただき､申請をしました｡
Elevated+
Elevated+はElevatedの上位版のようです｡
おそらくv1.1のPremiumに相当する有償版のアクセスレベルだと思います｡
詳細はまだ表に記載がありませんでした｡"coming soon"とのことです｡
Academic Research
Academic Researchはその名のとおり学術研究専用です｡
最大1000万件/月までツイートを取得できます｡
単に大学生であれば利用できるわけでもなく､
大学院生以上で､研究に利用する明確な目的が必要なようです｡5
結局､どのアクセスレベル/エンドポイントを利用すればよいのか
- ツイートの収集をまず試してみたい
→ 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のみで利用可 無償 |
| v2 | Elevated | Recent search | -- | 要申請､無償 |
| v2 | Elevated+ | Details unknown | -- | 詳細不明 |
| v2 | Academic Research | Full-archive search | -- | 学術研究利用に限定 無償 |
余談
- ツイート検索のAPIの仕様はv1.1とv2とで若干異なります
- よって､ツイートを収集するためのコードはv1.1とv2とで別々に必要になるはずです
- v2もv1.1も使いたい人向けに両方のコードを記事にする…かもしれません
-
公式ドキュメントの Please note を参照｡
Search Tweets: Standard v1.1 ↩ -
筆者はお財布と相談した結果､有償利用はしませんでした｡ ↩
-
筆者はこの要件を満たしていないためFull-archiveの方は利用できません｡残念です｡ ↩