Skip to main content
/mentionsは、指定したユーザー名に言及するツイートを返します。ブランドへのメンションの監視、サポート問い合わせの振り分け、キャンペーンの反応測定、競合の動向把握に使えます。Sorsaの検索エンドポイントの中でも最も多くのフィルターを備え、エンゲージメントのしきい値と日付範囲をリクエスト本文のパラメーターとして直接指定できます。結果は1ページ最大20ツイートです。
注: 実運用向けのコード、複数チャネルの監視パターン、競合分析のワークフローは、ブログのAPIでTwitterメンションを追跡する方法を参照してください。

クイックスタート

ヒント: 画面から試したい場合は、API Playgroundでコードを書かずに/mentionsを実行できます。全アカウントに、カード登録不要の無料リクエスト100件が含まれます。

エンドポイントの仕様

結果が1件でも20件でも、呼び出し1回につき割り当て量を1リクエスト消費します。

レスポンス

各メンションには、全エンゲージメント指標と投稿者プロフィールが含まれます。userは完全なプロフィールです(上の例では読みやすくするため省略しています)。すべてのタイムスタンプはISO 8601形式です。next_cursorがあれば続きがあり、nullまたは存在しなければ終端です。処理方法はページネーション、全フィールドはレスポンス形式を参照してください。

/mentionsと/search-tweetsの使い分け

2つのエンドポイントは異なる用途に対応します。
  • /mentionsは特定のユーザー名(@brand)をタグ付けした投稿に使います。@タグ、返信、言及を取得でき、min_likesmin_retweetsmin_repliessince_dateuntil_dateを直接指定できます。
  • /search-tweetsは、ユーザー名のタグを含まないキーワード一致に使います。"Nike" -from:Nike lang:enなら、本文中でブランド名に触れた投稿を取得できます。論理条件、メディアフィルターなど、/mentionsが対応していない演算子が必要な場合もこちらを使います。
ブランドへの言及を広くカバーするには、両方を並行して実行し、ツイートIDで重複を除去してください。

よく使うパターン

エンゲージメントで絞り込む

反応を集めたメンションだけを取得します。評判を確認するダッシュボードや広報の監視に便利です。

すべてのメンションを取得する(サポート用キュー)

エンゲージメントの条件を外し、時系列順に取得して、反応がない投稿も含めすべてのメンションを集めます。

キャンペーン期間を指定した分析

since_dateuntil_dateでキャンペーン期間を指定し、next_cursorがなくなるまで繰り返し取得します。

新しいメンションを定期的に確認する

繰り返し処理の間で最新のツイートIDを保持し、まだ見ていないメンションだけを取り出します。IDは文字列で返されるため、数値として比較してください。
この最初のページだけを使う例は、起動時に基準を設定し、既存のページの内容は通知しません。投稿が多い場合は、チェックポイントを進める前に未取得の範囲をページネーションで埋めてください。取得範囲を少し重ね、IDで重複を除去すると、遅れて現れる結果にも対応できます。last_seen_idをディスクやRedisに保存して再起動に備え、リクエストをtry/exceptとバックオフで囲んで、一時的なエラーによる停止を防いでください。重複排除とバックオフを含む完全なパターンは、リアルタイム監視を参照してください。

よくある落とし穴

  • サポート用途でmin_likesを高くしすぎる。 「いいね」2件の不具合報告は、500件のミームより重要なことがあります。サポート用キューではmin_likesを0にして、キーワードで振り分けます。
  • 投稿の多いアカウントで1ページしか読まない。 1リクエストは最大20メンションです。1日数百件あるブランドでは、必ずnext_cursorで続きを取得してください。1ページごとに1リクエストを消費するため、予算に含めます。
  • /mentionsだけで網羅できると考える。 @タグ付きの投稿だけが対象です。/search-tweetsと組み合わせて、タグのないブランドへの言及も取得します。
  • 投稿の少ないアカウントを頻繁に確認しすぎる。 メンション数に合わせ、活発なブランドなら15秒ごと、小規模なアカウントなら1〜2分ごとにします。すべてのプランでレート制限は毎秒20リクエストです(レート制限)。
  • 再起動をまたいで状態を保存しない。 永続的なチェックポイントがないと、再起動時に古いメンションを再通知したり、停止中の投稿を取り逃したりします。

次のステップ