Twitter Search
Xの検索結果は、クエリに対して選ばれた公開ポストで、各ポストの言語、投稿者、メディア、エンティティ、会話の文脈、表示中のエンゲージメントを含みます。すべてのレコードにクエリを付けて保持しておくと、定期的なトピック調査、ローンチ時のソーシャルリスニング、結果セットの比較を検証しやすくなります。
Twitter Search API の主な機能
- 1つの検索式から発見空でないキーワードまたは検索式を送信し、該当する公開Xポストを構造化レコードに変換します。
- 2つの調査スタイルに合わせた並び順最近のポストを追うなら latest、注目度の高いポストを確認するなら top を使用します。デフォルトは latest です。
- 実用的な検索結果の上限20から2,000までの範囲で20単位で結果数を指定し、検索で取得する最大件数を設定します。
- クエリを保持した検索結果本文、投稿者、エンゲージメント、メディア、エンティティ、タイムスタンプ、関係フィールドを、extra.search_query と collected_at とあわせて返します。
Twitter Search API のパラメータ
| パラメータ | 必須 | 説明 |
|---|---|---|
query | 必須 | 必須。該当する公開ポストを見つけるための、空でないキーワードまたはXポストの検索式です。 |
results_limit | 任意 | 任意。取得する結果数の上限です。デフォルトは20で、20から2,000までの20の倍数を指定できます。 |
sort_by | 任意 | 任意。並び順で、最近のポストは latest、注目度の高いポストは top を指定します。デフォルトは latest です。 |
Twitter Search API の使い方
調べたい内容を正確な検索式にまとめ、目的に合った並び順を選び、取得したポストとともにクエリを保存します。
- 探したいXポストに対応する、焦点を絞った空でない検索式を1つ作成します。
- latest または top を選び、results_limit を20から2,000までの範囲で20単位で指定します。
- リクエストを /v1/x/search に POST し、完了するまで /v1/tasks/{task_id} をポーリングします。
- data.results.items を保存し、has_more が false になるまで next_cursor をたどります。
curl -X POST "https://api.socq.ai/v1/x/search" \
-H "Authorization: Bearer $SOCQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{"query":"artificial intelligence","results_limit":40,"sort_by":"latest"}'
# Poll GET /v1/tasks/{task_id}
# Read data.results.items and follow next_cursor while has_more is trueTwitter Search API の主なユースケース
- 特定のローンチに関するソーシャルリスニング: 製品名、リリース、カンファレンス、キャンペーンのフレーズで検索し、該当するポストを投稿日時と取得時刻で整理します。
- ブランドや製品の言及の追跡: 特定の名前やフレーズについて、投稿者、本文、表示中のエンゲージメント、ハッシュタグ、メンション、メディアをまとめて把握します。
- 進行中のトピックの把握: 同じ検索式で、latest の結果で新しいポストを追い、top の結果で注目度の高いコンテンツを確認します。
- 定期実行クエリのデータセット管理: すべての検索結果に extra.search_query を保存し、バージョン管理した検索式を再実行して、未取得のポストIDだけを追加します。
Twitter Search API 活用のヒント
- まずは焦点を絞った検索式で始めて結果を確認し、カバー範囲が狭すぎる場合にのみ表現を広げてください。
- 時間が重要なリスニングには latest を、時系列よりも注目度の高いポストを重視する場合は top を選んでください。
- results_limit は20の倍数で指定し、保証される件数ではなく上限として解釈してください。
- 繰り返し取得する結果セットを比較できるよう、検索語を変更するたびにクエリのバージョンを管理してください。
- 発見時の文脈として extra.search_query と collected_at を保持しつつ、ポストの id で重複を排除してください。
関連API
Twitter Search API 以外に別の種類の公開Xデータが必要な場合は、これらのAPIをご利用ください。
- Twitter Tweet Scraper API — x.comまたはtwitter.comのステータスURLから、公開ポストのテキスト、投稿者、エンゲージメント、メディア、ハッシュタグ、メンション、会話の関係を取得します。
- Twitter Profile Scraper API — ユーザー名から、公開アカウントの情報、プロフィール文、アバター、カバー画像、アカウントの状態、表示中のオーディエンス統計を取得します。
- X Post Replies API — XのポストURLから公開返信を取得します。並び順を指定でき、返信テキスト、投稿者、表示中のエンゲージメント、メディア、親ポストの情報を返します。
- X Trends API — 既知の数値WOEIDについて、現在の公開Xトレンドのスナップショットを取得し、元の順位、クエリ、説明、地域情報を返します。
- Twitter User Search API — キーワードで公開Xアカウントを検索します。
- X Communities Search API — キーワードでコミュニティを探し、メンバー数と、メンバー・投稿の取得にそのまま使えるリンクを返します。
- Twitter User Tweets Scraper API
- X Followers List API
- X Following List API
- X Post Quotes API
- X Post Retweeters API
- Twitter Mentions API
- X Community API
- X Community Posts API
- X Thread Context API
- X Account Location API
- X Verified Followers API
- X List Tweets API
- Twitter List Members API
- Twitter List Followers API
- X Community Members API
- X Community Moderators API
- X Articles API
- X Spaces API
- Twitter Media Scraper API
- X User Replies API
- Twitter Follow Checker API
- Twitter Video Transcript API