X Communities Search
Xコミュニティは、ユーザーがX上で参加するトピック別のグループで、検索結果では各コミュニティに名前、バナー画像、メンバー数、センシティブな内容として指定されているかどうかのフラグが表示されます。これらの一覧にキーワードを当てると、あるテーマがどこで話題になっているか、どのグループが最も大きいか、どれが開く前から成人向けやセンシティブのラベルを持っているかがわかります。
X Communities Search API の主な機能
- 1つのキーワードで一致するコミュニティをすべて取得bitcoin などの単語やフレーズを query に入れると、Xがそれに対して表示するコミュニティが1行ずつ返ります。
- 名前とバナーname と cover_url で各コミュニティのタイトルとバナー画像がわかり、一覧で見分けたり、自社のインターフェースに表示したりするのに十分です。
- 規模を測るメンバー数metrics.members_count で参加人数がわかるため、ごく小さなグループと数万人規模のコミュニティを検索結果からすぐに見分けられます。
- センシティブな内容のマーカーコミュニティがXでセンシティブとして指定されていると is_nsfw が true になり、成人向けの場がレポートやユーザーに届く前に処理できます。
- 変わらないIDとリンク各行には数値のコミュニティ id と https://x.com/i/communities/<id> 形式の url が含まれ、検索をまたいでも同じままなので、自社データのキーとして使えます。
X Communities Search API のパラメータ
| パラメータ | 必須 | 説明 |
|---|---|---|
query | 必須 | Xコミュニティを検索するキーワードです(例:bitcoin)。 |
results_limit | 任意 | 返すコミュニティの件数です。10〜500の範囲で10の倍数を指定し、デフォルトは20です。 |
X Communities Search API の使い方
キーワードで検索し、一致したコミュニティをページごとに読み取ります。
- {"query": "bitcoin", "results_limit": 20} を /v1/x/search-communities に POST します。
- status が succeeded になるまで GET /v1/tasks/{task_id} をポーリングします。
- results.items から一致したコミュニティを読み取り、has_more が true の間は results.next_cursor で次のページをリクエストします。
curl -X POST "https://api.socq.ai/v1/x/search-communities" \
-H "Authorization: Bearer $SOCQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{"query":"bitcoin","results_limit":20}'
# Each result's url can go straight into X Community Members, X Community Moderators or X Community Posts.X Communities Search API の主なユースケース
- X上でテーマが集まる場所をマッピング: ある市場や趣味の主要な用語で検索し、会話が集まっている場所を示すコミュニティ名、リンク、メンバー数を集めます。
- ニッチ分野の大規模コミュニティを絞り込む: 一致したコミュニティを metrics.members_count で並べ替え、スポンサーシップや投稿、詳しい調査に値する規模の少数のコミュニティを選びます。
- コミュニティ一覧のブランドセーフティ確保: コミュニティの一覧をクライアントと共有したりプロダクト内に表示したりする前に、is_nsfw が true の行をすべて除きます。
- メンバーとモデレーターのエクスポートへの橋渡し: 候補に残した各コミュニティの url を X Community Members や X Community Moderators に渡し、グループの一覧から、そこにいる人々の情報へと進みます。
X Communities Search API 活用のヒント
- 1つのコミュニティが複数のキーワードに一致することがあるため、bitcoin と btc のような近い言い換えでも検索し、結果を id で統合してください。
- コミュニティの成長を追うには、同じ query を定期的に繰り返し、各 id ごとに metrics.members_count を collected_at とともに保存してください。
関連API
X Communities Search API 以外に別の種類の公開Xデータが必要な場合は、これらのAPIをご利用ください。
- Twitter Search API — 検索式で公開ポストを探します。最新順または話題順の並び替えと、取得件数の上限を指定できます。
- X Trends API — 既知の数値WOEIDについて、現在の公開Xトレンドのスナップショットを取得し、元の順位、クエリ、説明、地域情報を返します。
- Twitter User Search API — キーワードで公開Xアカウントを検索します。
- X Community API — コミュニティのリンクから、説明、メンバー数、ルール、参加ポリシーを取得します。
- X Community Posts API — コミュニティで共有された公開ポストを、テキスト、投稿者、インタラクション数とともに取得します。
- X Community Members API — コミュニティのメンバーを、自己紹介とフォロワー数を含むプロフィールとして書き出します。
- Twitter Tweet Scraper API
- Twitter Profile Scraper API
- Twitter User Tweets Scraper 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 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 Moderators API
- X Articles API
- X Spaces API
- Twitter Media Scraper API
- X User Replies API
- Twitter Follow Checker API
- Twitter Video Transcript API