v2 フルアーカイブ検索エンドポイントで過去のPostを取得する

​

はじめに

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

当社の検索機能の全体像は search overview ページ で確認できます。

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

このチュートリアルでは、研究者が公開 X データの完全な履歴を検索するために full-archive search エンドポイントを使用する手順を段階的に説明します。また、ジオタグ付きの Post を取得するなどのデータセットの構築方法や、クエリに対して利用可能な Post をページングする方法も示します。

​

前提条件

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

​

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

Academic Research のプロダクトトラックの利用が承認されると、開発者ポータルで学術向けProjectが表示されます。「Projects and Apps」セクションで「Add App」をクリックし、X アプリをその Project に接続します。

その後、既存のアプリを選択してプロジェクトに接続できます（以下参照）。

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

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

注意

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

​

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

以下の cURL コマンドは、@XDevelopers のハンドルから過去の Post を取得する方法を示しています。$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が表示されます。

デフォルトでは、直近のPostは最大10件までしか返されません。1リクエストあたりで10件を超えて取得したい場合は、以下のように max_results パラメーターを使用し、1リクエストあたり最大500件のPostを取得できます。

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」を含むすべてのPostを取得したい場合は、丸括弧内で 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」という単語を含むすべてのPostを取得したい場合は、論理NOT（-で表されます）と組み合わせて 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 パラメータを使用して過去のPostを取得する

full-archive search エンドポイントを使用する場合、既定では直近30日間の Postが返されます。30日より前のPostを取得したい場合は、 APIコールで start_time と end_time パラメータを使用できます。これらの パラメータは有効な RFC3339 の日時形式（例: 2020-12-21T13:00:00.00Z）である必要があります。 したがって、2020年12月の XDevelopers アカウントのすべてのPostを取得したい場合、 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'

​

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

ジオタグ付きのPostとは、都市、州、国などの地理情報が付与されているPostを指します。

​

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

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

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

​

place_country 演算子の使用

同様に、ジオデータを含む Post を特定の国に限定するには、 place_country 演算子を使用します。以下の cURL コマンドは、米国の @XDevelopers アカウントからのすべての Post を取得します。

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

国は上記の ISO アルファ2文字コードで指定されています。有効な ISO コードはこちらで確認できます。

​

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

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

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

したがって、次の取得対象となるPostを得るには、このmetaオブジェクトのnext_tokenの値を使用し、以下のとおりフルアーカイブ検索エンドポイントへのAPI呼び出しでnext_tokenにその値を指定してください（Bearer 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 の有無を確認し続けられ、収集したい Post の数にまだ達していない場合は、各リクエストで新しい next_token を指定してフルアーカイブエンドポイントを呼び出し続けることができます。なお、フルアーカイブ検索エンドポイントは、合計の Post cap、つまり X API から 1 か月あたりに取得できる Project ごとの Post 数にカウントされます。結果をページングする際はコードのロジックに注意し、意図せず Post cap を使い切ってしまわないようにしてください。

以下は、フルアーカイブ検索エンドポイントの利用時に役立つリソースです。フィードバックをお待ちしています。ご質問は @XDevelopers または コミュニティフォーラム までお寄せください。

​

追加リソース

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