x/
trends

1つ以上の数値WOEIDについて現在の公開Xトレンドを取得し、取得元の順位、クエリ、説明、地域情報、取得時刻を返します。

X Trends API

WOEID別スナップショット
取得元の順位
地域情報
結果1件あたり0.5クレジット
準備完了
README

SocQ 編集 · 更新

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. 1つ以上の既知のWOEIDを数値文字列として入力します。このエンドポイントは地名からの変換は行いません。
  2. results_limit を20から2,000までの整数で指定するか、WOEIDごとのデフォルト値100のままにします。
  3. リクエストを /v1/x/trends に POST し、タスクが成功するまで /v1/tasks/{task_id} をポーリングします。
  4. 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 true

X Trends API の主なユースケース

  • 特定市場のトピック監視: モニタリングシステムですでに管理している地域識別子について、現在のトレンド名、順位、説明を取得します。
  • 定期的な観測スナップショットの作成: 同じWOEIDを任意のスケジュールで実行し、すべての結果に collected_at を保存して後から変化を分析します。
  • トピックレビュー用キューの作成: 返された名前、クエリ、順位、説明を使い、アナリストによるレビューや後続の発見ワークフローに回す公開トピックの優先順位を決めます。

X Trends API 活用のヒント

  • タスクを送信する前に数値WOEIDを用意してください。地名や自由記述の地域は受け付けません。
  • デフォルトの 1 はバックエンドが公開しているリクエスト例に従ったものです。目的の範囲に合った識別子に置き換えてください。
  • 現在のトレンドセットはリクエストした件数より少ない場合があるため、results_limit はWOEIDごとの上限として扱ってください。
  • 同じトレンド名は1つのタスク内で重複排除されることがあるため、トレンドと地域の対応をすべて保持したい場合は、重なり合う地域を別々のタスクで実行してください。
  • 観測時刻には collected_at を使用してください。取得元がトレンドの作成日時を提供していないため、created_at は null です。
  • タスク結果のカーソルはすでに保存されたレコードをページ送りするもので、取得元にトレンドの次のページをリクエストするものではありません。

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のデータを、対応する他のソーシャルプラットフォームの公開データと組み合わせられます。

X Trends API — よくある質問

X Trends APIは、数値WOEIDごとに現在の公開Xトレンドのスナップショットを取得するためのプログラムインターフェースです。

1つ以上の既知の地域識別子を数値文字列で指定します。このエンドポイントは都市名や国名をWOEIDに変換しません。

デフォルトは100で、20から2,000までの整数を指定でき、WOEIDごとに個別に適用されます。取得元が提供する現在のトレンドが指定した上限より少ない場合もあります。

レコードには、id と text としてのトレンド名、存在する場合は取得元の順位、collected_at、および取得可能な場合は WOEID、クエリ、説明を含む extra フィールドが含まれます。

できません。リクエストした各WOEIDの現在のスナップショットを返します。履歴を作成するには、定期的に実行した結果を自社のシステムに保存してください。

保存されるレコードは、タスク内で正規化されたトレンド名によって重複排除されます。同じ名前が複数の送信地域に現れた場合、最初に保存されたレコードには extra.woeid の値が1つしか残らないことがあります。

正常に保存された正規化トレンド1件につき0.5 SocQクレジットです。見積もりには送信したすべてのWOEIDの results_limit が使われ、タスクの精算後に事前に引き当てた未使用分のクレジットは返金されます。