v2 のフルアーカイブ検索エンドポイントを使用して過去の投稿を取得する

はじめに

v2 の Search Posts エンドポイントを使用すると、作成した検索クエリに基づいて、関心のあるトピックに関連する投稿を取得できます。v2 の Search Posts には 2 種類のエンドポイントがあります。承認済みアカウントを持つすべての開発者が利用でき、最大 7 日前までの投稿を検索できる recent search と、Academic Research product track に承認された研究者のみが利用でき、2006 年 3 月までさかのぼってアーカイブ全体の投稿を検索できる full-archive search です。

検索機能全体の内容は、 search overview ページ で確認できます。

これらの Search Posts エンドポイントは、縦断的研究や過去のトピック・イベントの分析など、学術研究者にとってよくあるユースケースの一つに対応するものです。

このチュートリアルでは、公開されている X データの完全な履歴を検索するために full-archive search エンドポイントを利用したい研究者向けに、ステップバイステップのガイドを提供します。また、ジオタグ付きの投稿を取得するなど、データセットを構築するさまざまな方法と、クエリに対して利用可能な投稿をページングしながら取得する方法も示します。

前提条件

現在、このエンドポイントは Academic Research プロダクトトラック の一部としてのみ利用できます。 このエンドポイントを利用するには、 アクセス申請 を行う必要があります。 このトラックの 申請手順と要件の詳細 をご覧ください。

学術プロジェクトに App を接続する

Academic Research プロダクトトラックの利用が承認されると、 Developer Console 上に Academic Project が表示されます。 「Apps」セクションから「Add App」をクリックして、 X App を Project に接続します。

次に、既存の App を選択してプロジェクトに接続できます (下図のとおり) 。

または、新しい App を作成して名前を付け、「Complete」をクリックすることで、 新しい App を Academic Project に接続することもできます。

これにより API キーと Bearer Token が発行され、これらを使用してフルアーカイブ検索エンドポイントに接続できるようになります。

注意

上記のスクリーンショットではキーは非表示になっていますが、 ご自身の Developer Console では API Key、API Secret Key、 および Bearer Token の実際の値を確認できます。 これらのキーと Bearer Token は、フルアーカイブ検索エンドポイントを呼び出す際に必要になるため、 必ず保存しておいてください。

フルアーカイブ検索エンドポイントへの接続

以下の cURL コマンドは、@XDevelopers のアカウントから過去の投稿を取得する方法を示しています。$BEARER_TOKEN を自分のベアラートークンに置き換え、リクエスト全体をターミナルに貼り付けてから “return” キーを押してください。

curl --request GET 'https://api.x.com/2/tweets/search/all?query=from:xdevelopers' --header 'Authorization: Bearer $BEARER_TOKEN'

レスポンス JSON が表示されます。

デフォルトでは、直近 10 件の投稿のみが返されます。1 回のリクエストで 10 件より多く取得したい場合は、max_results パラメータを使用し、以下のように 1 リクエストあたり最大 500 件の投稿まで指定できます。

curl --request GET 'https://api.x.com/2/tweets/search/all?query=from:xdevelopers&max_results=500' --header 'Authorization: Bearer $BEARER_TOKEN'

クエリの構築

上記の呼び出し例から分かるように、query パラメータを使用すると、 検索したいデータを指定できます。たとえば、covid という単語、または coronavirus という単語を含むすべての投稿を取得したい場合は、 括弧の中で OR 演算子を使用し、クエリを (covid OR coronavirus) のように指定できます。この場合、API 呼び出しは 次のようになります。

curl --request GET 'https://api.x.com/2/tweets/search/all?query=(covid%20OR%20coronavirus)&max_results=500' --header 'Authorization: Bearer $BEARER_TOKEN'

同様に、covid19 という語を含み、かつ リポストではないすべての投稿を取得したい場合は、論理否定 (- で表されます) と組み合わせて is:retweet 演算子を使用できます。つまり、クエリは covid19 -is:retweet となり、API コールは次のようになります。

curl --request GET 'https://api.x.com/2/tweets/search/all?query=covid19%20-is:retweet&max_results=500' --header 'Authorization: Bearer $BEARER_TOKEN'

次の オペレーターの完全な一覧をまとめたガイド を参照して、フルアーカイブ検索エンドポイントでサポートされているオペレーターを確認してください。

start_time パラメーターと end_time パラメーターを使って過去の投稿を取得する

full-archive search エンドポイントを使用する場合、デフォルトでは直近 30 日間の 投稿が返されます。30 日より前の投稿を取得したい場合は、API 呼び出しで start_time と end_time パラメーターを使用できます。これらのパラメーターは、 有効な RFC3339 日時形式で指定する必要があります (例: 2020-12-21T13:00:00.00Z) 。そのため、2020 年 12 月の XDevelopers アカウントからすべての投稿を取得したい場合、API 呼び出しは次のようになります。

curl --request GET 'https://api.x.com/2/tweets/search/all?query=from:XDevelopers&start_time=2020-12-01T00:00:00.00Z&end_time=2021-01-01T00:00:00.00Z' --header 'Authorization: Bearer $BEARER_TOKEN'

位置情報付きの過去の投稿を取得する

位置情報付きの投稿とは、市区町村、州、国などの地理情報が付与されている投稿のことです。

has:geo オペレーターの使用

位置情報データを含む投稿を取得したい場合は、has:geo オペレーターを使用します。 たとえば、次の cURL リクエストでは、位置情報データを含む @XDevelopers アカウントからの投稿のみを取得します。

curl --request GET
'https://api.x.com/2/tweets/search/all?query=from:xdevelopers%20has:geo' --header
'Authorization: Bearer $BEARER_TOKEN'

place_country 演算子の使用

同様に、place_country 演算子を使用することで、ジオデータを持つ投稿を特定の国に限定できます。以下の cURL コマンドは、米国に紐づく @XDevelopers ハンドルからのすべての投稿を取得します。

curl --request GET
'https://api.x.com/2/tweets/search/all?query=from:xdevelopers%20place_country:US'
--hbasheader 'Authorization: Bearer XXXXX'

上記では、ISO の2文字のアルファベットコードを使用して国が指定されています。有効な ISO コードはこちらで確認できます。

next_token を使って 500 件を超える過去の投稿を取得する

前述のとおり、デフォルトでは、フルアーカイブ検索エンドポイントへの 1 回のクエリで取得できる投稿は最大 500 件までです。クエリに対して 500 件を超える投稿が存在する場合、JSON レスポンスには next_token が含まれます。この next_token を API 呼び出しに指定することで、そのクエリに対して次に取得可能な投稿を取得できます。この next_token は JSON レスポンス内の meta オブジェクトに含まれており、次のような形式になります。

{ "newest_id": "12345678...", "oldest_id": "12345678...", "result_count": 500,
"nebashxt_token": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" }

したがって、次に取得可能な投稿を取得するには、この meta オブジェクトの next_token の値を使用し、下記のとおり API 呼び出しで full-archive search エンドポイントの next_token の値として指定します (実際には、前回の API 呼び出しで取得した next_token の値と、ご自身のベアラートークンを使用します) 。

curl --request GET
'https://api.x.com/2/tweets/search/all?max_results=500&query=covid&next_token=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'
--header 'Authorization: Bearer $BEARER_TOKEN'

この方法を使うことで、next_token が利用可能かどうかを確認しつつ、収集したい投稿数にまだ達していない場合は、新しい next_token を各リクエストで指定して full-archive エンドポイントを呼び出し続けることができます。

以下は、full-archive search エンドポイントを利用する際に役立つリソースです。ぜひフィードバックをお寄せください。このエンドポイントに関するご質問は @XDevelopers や community forums までお寄せください。

追加リソース

• フルアーカイブ検索エンドポイントのAPIリファレンス
• 検索クエリ構築の基本を学ぶ