Recent search のページネーション
はじめに
- recent search エンドポイントは、クエリに対して少なくとも 1 ページで応答し、追加のページが利用可能な場合は JSON レスポンス内に next_token を提供します。一致する Post を受け取るには、レスポンスにトークンが含まれなくなるまでこの処理を繰り返します。
- next_token は失効しません。同じ next_token 値を使用した複数のリクエストは、リクエストした時期に関係なく同一の結果を受け取ります。
-
Post は UTC タイムゾーンで新しいものから古いものへ（逆時系列）で返されます。これは各ページ内だけでなく、複数ページにまたがっても同様です。
- 最初のレスポンスの先頭の Post が、クエリに一致する最新の Post です。
- 最後のレスポンスの末尾の Post が、クエリに一致する最も古い Post です。
- max_results リクエストパラメータにより、レスポンスごとに返される Post の数を設定できます。デフォルトは 10 件、最大は 100 件です。
- すべてのページネーション実装では、レスポンスのペイロードから next_token を抽出し、それを「次のページ」の検索リクエストに含めます。これらの「次のページ」リクエストの構築方法については、以下を参照してください。
- 履歴取得 - 関心のある期間から一致する Post をリクエストします。これは通常、履歴調査を目的とした一度限りのリクエストです。検索リクエストは start_time および end_time リクエストパラメータに基づいて行うことができます。recent search エンドポイントは、最新の一致する Post から始めて、逆時系列で Post を返します。
- ポーリング - 直近に受信した Post 以降に投稿された一致する Post をリクエストします。これらのユースケースは、ほぼリアルタイムに焦点を当てることが多く、新しい関心のある Post を「リッスン」するために高頻度でリクエストするのが特徴です。recent search エンドポイントは、この「ポーリング」パターンをサポートするために since_id リクエストパラメータを提供します。Post の ID による扱いを容易にするため、until_id リクエストパラメータも利用できます。
過去データの取得
ポーリングとリスニングのユースケース
https://api.x.com/2/tweets/search/recent?query=snow&since_id=12000
追加のデータがあり、next トークンが返される場合でも、結果の最初のページに含まれる newest_id の値だけで十分です。各ページのデータには newest_id と oldest_id が含まれますが、次の定期的なポーリングリクエストに必要なのは最初のページで提供される値のみです。したがって、ポーリング設計を実装する場合や、ID 範囲での Post 検索を行う場合は、ページネーションのロジックがやや複雑になります。
ここで、さらに一致する Post が 18 件あるとします。エンドポイントは、この5分間のデータに対して、最初のレスポンスで完全なデータページと、次のページを取得するための next_token を返します。さらに、5分後の次回のポーリング間隔に必要となる最新の Post の ID も含まれます。