/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_likes、min_retweets、min_replies、since_date、until_dateを直接指定できます。/search-tweetsは、ユーザー名のタグを含まないキーワード一致に使います。"Nike" -from:Nike lang:enなら、本文中でブランド名に触れた投稿を取得できます。論理条件、メディアフィルターなど、/mentionsが対応していない演算子が必要な場合もこちらを使います。
よく使うパターン
エンゲージメントで絞り込む
反応を集めたメンションだけを取得します。評判を確認するダッシュボードや広報の監視に便利です。すべてのメンションを取得する(サポート用キュー)
エンゲージメントの条件を外し、時系列順に取得して、反応がない投稿も含めすべてのメンションを集めます。キャンペーン期間を指定した分析
since_dateとuntil_dateでキャンペーン期間を指定し、next_cursorがなくなるまで繰り返し取得します。
新しいメンションを定期的に確認する
繰り返し処理の間で最新のツイート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リクエストです(レート制限)。
- 再起動をまたいで状態を保存しない。 永続的なチェックポイントがないと、再起動時に古いメンションを再通知したり、停止中の投稿を取り逃したりします。