X Trends
Xのトレンドは、数値WOEIDごとに取得できる公開トピックを地域単位で切り出したスナップショットで、取得元の名前、順位、クエリ、説明、取得時刻がまとめて保持されます。この構造は地域ごとのトピック発見や繰り返しの観測に役立ち、各レコードが過去のトレンド推移ではなく取得時点の状態を反映していることも明確になります。
X Trends API の主な機能
- 地域単位の取得1つ以上の既知の数値WOEIDについて現在の公開トレンドをリクエストし、元の識別子を extra.woeid に保持します。
- 取得元の順位を保持取得元の順位が利用可能な場合は、SocQが算出したスコアに置き換えることなく metrics.rank に保持します。
- トレンドの有用な文脈取得元のクエリや説明が提供されている場合は、トレンド名とあわせて受け取れます。
- 地域ごとの個別上限送信したWOEIDごとに results_limit を個別に適用し、各地域で現在取得可能なトレンドセットを1回ずつ取得します。
X Trends API のパラメータ
| パラメータ | 必須 | 説明 |
|---|---|---|
woeids | 必須 | 必須。1つ以上の既知のX地域識別子の配列です。各値は空でない数値文字列で指定します。 |
results_limit | 任意 | 任意。WOEIDごとに個別に適用される整数の上限です。デフォルトは100で、20から2,000までの値を指定できます。 |
X Trends API の使い方
すでにわかっている数値WOEIDから始めて地域ごとの上限を決め、返されたレコードを取得時点のスナップショットとして扱います。
- 1つ以上の既知のWOEIDを数値文字列として入力します。このエンドポイントは地名からの変換は行いません。
- results_limit を20から2,000までの整数で指定するか、WOEIDごとのデフォルト値100のままにします。
- リクエストを /v1/x/trends に POST し、タスクが成功するまで /v1/tasks/{task_id} をポーリングします。
- data.results.items を読み取り、has_more が true の間はタスク結果の next_cursor をたどります。
curl -X POST "https://api.socq.ai/v1/x/trends" \
-H "Authorization: Bearer $SOCQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{"woeids":["1"],"results_limit":100}'
# Poll GET /v1/tasks/{task_id}
# Read data.results.items and follow next_cursor while has_more is trueX Trends API の主なユースケース
- 特定市場のトピック監視: モニタリングシステムですでに管理している地域識別子について、現在のトレンド名、順位、説明を取得します。
- 定期的な観測スナップショットの作成: 同じWOEIDを任意のスケジュールで実行し、すべての結果に collected_at を保存して後から変化を分析します。
- トピックレビュー用キューの作成: 返された名前、クエリ、順位、説明を使い、アナリストによるレビューや後続の発見ワークフローに回す公開トピックの優先順位を決めます。
X Trends API 活用のヒント
- タスクを送信する前に数値WOEIDを用意してください。地名や自由記述の地域は受け付けません。
- デフォルトの 1 はバックエンドが公開しているリクエスト例に従ったものです。目的の範囲に合った識別子に置き換えてください。
- 現在のトレンドセットはリクエストした件数より少ない場合があるため、results_limit はWOEIDごとの上限として扱ってください。
- 同じトレンド名は1つのタスク内で重複排除されることがあるため、トレンドと地域の対応をすべて保持したい場合は、重なり合う地域を別々のタスクで実行してください。
- 観測時刻には collected_at を使用してください。取得元がトレンドの作成日時を提供していないため、created_at は null です。
- タスク結果のカーソルはすでに保存されたレコードをページ送りするもので、取得元にトレンドの次のページをリクエストするものではありません。
関連API
X Trends API 以外に別の種類の公開Xデータが必要な場合は、これらのAPIをご利用ください。
- Twitter Tweet Scraper API — x.comまたはtwitter.comのステータスURLから、公開ポストのテキスト、投稿者、エンゲージメント、メディア、ハッシュタグ、メンション、会話の関係を取得します。
- Twitter Profile Scraper API — ユーザー名から、公開アカウントの情報、プロフィール文、アバター、カバー画像、アカウントの状態、表示中のオーディエンス統計を取得します。
- Twitter User Tweets Scraper API — ユーザー名から、返信を除く最近の公開ポストを、投稿者、メディア、ハッシュタグ、メンション、エンゲージメントとともに取得します。
- Twitter Search API — 検索式で公開ポストを探します。最新順または話題順の並び替えと、取得件数の上限を指定できます。
- Twitter User Search API — キーワードで公開Xアカウントを検索します。
- X Communities Search API — キーワードでコミュニティを探し、メンバー数と、メンバー・投稿の取得にそのまま使えるリンクを返します。
- X Followers List API
- X Following List API
- X Post Quotes API
- X Post Replies 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