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リファレンス
• 検索クエリ構築の基本を学ぶ