v2 のフルアーカイブ検索 endpoint を使用して過去の Posts を取得する

​

はじめに

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

検索機能の全体像は search overview page で確認できます。

これらの Search Posts endpoint は、縦断研究や過去のトピック・イベントの分析など、学術研究者における最も一般的なユースケースの一つに対応しています。

このチュートリアルは、公開されている X の data の完全な履歴を検索するために full-archive search endpoint を利用したい研究者向けのステップバイステップガイドです。ジオタグ付きの Posts を取得するなど、データセットを構築するさまざまな方法や、ある query に対して取得可能な Posts をページングする方法もあわせて説明します。

​

前提条件

現在、この endpoint は Academic Research product track の一部としてのみ提供されています。 この endpoint を利用するには、 アクセスを申請 する必要があります。 このトラックの 申請方法と要件の詳細 をご確認ください。

​

学術用プロジェクトにアプリを接続する

Academic Research の製品トラックの利用が承認されると、 developer portal に Academic Project が表示されます。「Projects and Apps」セクションで「Add App」をクリックし、 X App を Project に接続します。

その後、既存の App を選択してプロジェクトに接続することもできます（下図参照）。

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

これにより、API Key と Bearer Token が発行され、 full-archive search の endpoint への接続に使用できるようになります。

注意

上のスクリーンショットではキーは非表示になっていますが、ご自身の developer portal では、 API Key、API Secret Key、Bearer Token の実際の値を確認できます。これらのキーおよび Bearer Token は、full-archive search の endpoint を呼び出す際に必要になるため、保存してください。

​

フルアーカイブ検索 endpoint への接続

以下の cURL コマンドは、@XDevelopers のハンドルから過去の Posts を取得する方法を示しています。$BEARER_TOKEN をご自身の Bearer Token に置き換え、リクエスト全体をターミナルに貼り付けて、Enter キーを押してください。

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

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

デフォルトでは、直近のPostsは最新10件のみ返されます。1回のリクエストで10件を超えるPostsが必要な場合は、max_results パラメータを使用し、以下のとおり1リクエストあたり最大500件のPostsまで指定できます。

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

​

query の構築

上記の例の呼び出しで示したとおり、query パラメータを使用すると、検索対象の data を指定できます。たとえば、単語「covid」または「coronavirus」を含むすべての Posts を取得したい場合は、かっこ内で OR 演算子を使用し、(covid OR coronavirus) のように query を記述できます。すると、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 という語を含み、リポストではないすべての Posts を取得したい場合は、論理否定（- で表されます）と組み合わせて is:retweet 演算子を使用できます。したがって、query は 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'

次を参照してください サポートされる演算子の完全な一覧をまとめたガイド これはフルアーカイブ検索のendpointでサポートされています。

​

start_time と end_time パラメータを使用して過去の Posts を取得する

full-archive search endpoint を使用する場合、既定では直近30日間の Posts が返されます。30日より前の Posts を取得するには、 API 呼び出しで start_time と end_time パラメータを指定します。これらの パラメータは有効な RFC3339 の日時形式である必要があり、例としては 2020-12-21T13:00:00.00Z です。たとえば、2020年12月の XDevelopers アカウントのすべての Posts を取得する場合、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'

​

ジオタグ付きの過去のPostsを取得する

ジオタグ付きのPostsとは、都市、州、国などの地理情報が紐づけられているPostsを指します。

​

has:geo 演算子の使用

ジオデータを含む Posts を取得するには、has:geo 演算子を使用します。 たとえば、次の cURL リクエストは、ジオデータを持つ @XDevelopers ハンドルの Posts のみを取得します。

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

​

place_country 演算子の使用

同様に、geo データを含む Posts を特定の国に絞り込むには、place_country 演算子を使用します。以下の cURL コマンドは、米国に位置付けられた @XDevelopers ハンドルのすべての Posts を取得します。

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

国は上記の ISO alpha-2 文字コードで指定します。有効な ISO コードはこちらで確認できます。

​

next_token を使用して 500 件を超える過去の Posts を取得する

前述のとおり、デフォルトではフルアーカイブ検索 endpoint への query ごとのリクエストで取得できるのは最大 500 件の Posts です。query で 500 件を超える Posts が取得対象として存在する場合、JSON レスポンスに next_token が含まれます。これを API 呼び出しに付加すると、その query に対して次の Posts を取得できます。なお、next_token は JSON レスポンスの meta オブジェクト内に含まれ、次のようになります:

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

したがって、次のPostsを取得するには、このmetaオブジェクトのnext_tokenの値を使用し、以下のとおり、full-archive search endpointへのAPI呼び出しでnext_tokenにその値を指定してください（Bearer Tokenはご自身のものを、Next Tokenは直前のAPI呼び出しで取得した値を使用します）。

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 の有無を継続的に確認し、収集したい Posts の目標数に達していない場合は、各リクエストで新しい next_token を指定して full-archive endpoint を呼び続けることができます。なお、full-archive search endpoint の利用分は合計のPost上限——つまり、X API の各Projectごとに月あたり取得できる Posts の数——に算入されます。結果をページングする際は、意図せず Post上限 を使い切ってしまわないよう、コードのロジックに留意してください。

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

​

追加リソース

• 全アーカイブ検索 endpoint の API リファレンス
• 検索用の query の作成方法の基本