SocQを使ってTwitter/Xのコミュニティでの議論を取得し、投稿の本文、投稿者、公開日時、出典をひとまとめに保存します。繰り返し出てくる質問をトピックのアイデアに変え、それぞれの発見に元の投稿を添付しておくことで、後から見直せるようにします。
このチュートリアルでは、投稿の取得にSocQ X Community Posts、説明文とルールの取得にX Communityを使います。サンプルでは、出典を保持したJSONと、コミュニティ単位のCSVを出力します。
結論:
x.com/i/communities/{id}形式のリンクをPOST /v1/x/community-postsに送信してタスクIDを保存し、成功後にすべての結果ページを読み取ります。メタデータは、同じリンクを使ってPOST /v1/x/communityで取得します。各投稿に入力元のコミュニティを紐づけると、メタデータと議論を結び付けられます。
公開コミュニティのURLを入力にする
次の形式のURLを使い、調べたい公開コミュニティのものに置き換えてください。
https://x.com/i/communities/1493446837214187523
数字の部分がコミュニティIDです。2つのコミュニティ用エンドポイントは、どちらも/i/communities/{numeric_id}を含む完全なURLを受け付けます。
コミュニティ名しか分からない場合は、まず公開URLを探し、そのリンクをurlsに指定してください。
送信したURL、数値のコミュニティID、公開日時(published_at)、取得日時(collected_at)を保存します。x.comと、対応しているtwitter.com形式のURLはコミュニティIDで照合し、名前が同じでもIDが異なるコミュニティは別々に管理してください。
Twitter/Xのコミュニティフィードから投稿を取得する
SOCQ_API_KEYを設定し、コミュニティごとに最大40件の投稿に絞ったタスクを送信します。
curl -X POST "https://api.socq.ai/v1/x/community-posts" \
-H "Authorization: Bearer $SOCQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"urls": ["https://x.com/i/communities/1493446837214187523"],
"results_limit": 40
}'
レスポンスにはdata.task_idが含まれます。これを保存し、既存のタスクを照会します。
curl "https://api.socq.ai/v1/tasks/$TASK_ID?limit=100" \
-H "Authorization: Bearer $SOCQ_API_KEY"
タスクがqueued、running、retryingのあいだは、間隔を空けてリクエストしてください。failedのタスクではdata.error_messageが返されます。succeededになると、投稿のレコードはdata.results.itemsに入ります。
Community Postsは、作成日時の順にレコードを返します。いいね数やコメント数で並べたレポートが必要な場合は、取得したレコードをローカルで並べ替え、サンプル内のランキングであることを明記してください。
コミュニティごとの上限を理解する
results_limitの既定値は100で、20から2000までの20の倍数(20、40、60、100など)を指定できます。
この上限は、入力した各コミュニティに適用されます。results_limit=40のURLを2つ送信すると、それぞれ最大40件の投稿をリクエストします。実際の件数は、保存され重複を除いた結果で決まります。
タスク照会のlimitは、1ページあたりに読み取る保存済みレコードの数を指定し、next_cursorは次のページを示します。送信時のresults_limitは、収集の上限を決めます。
取得できるコミュニティデータを把握する
| リソース | 標準フィールド | リサーチの問い |
|---|---|---|
| Community | name, text, rules, join_policy, invites_policy | どのような説明、ルール、参加ポリシーが記録されているか |
| コミュニティの数値 | metrics.members_count, metrics.moderators_count | ソースが報告するメンバー数とモデレーター数はいくつか |
| Community Posts | id, text, author, published_at, media | 取得した期間にどのような議論があるか |
| 投稿の指標 | 取得できるいいね数、コメント数、シェア数、閲覧数 | 取得時点でサンプルの投稿同士をどう比較できるか |
メタデータのリクエストは別になります。
curl -X POST "https://api.socq.ai/v1/x/community" \
-H "Authorization: Bearer $SOCQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{"urls":["https://x.com/i/communities/1493446837214187523"]}'
メタデータは、専用のタスクIDで取得します。メンバー数とモデレーター数はコミュニティの規模を表し、投稿の閲覧数はその投稿が閲覧された回数を記録したものです。アクティブな投稿者数やユニークリーチは、別途測定する必要があります。
nullはソースにその指標が含まれていなかったことを意味し、0は0という値が返されたことを意味します。出力ではこの2つを区別して保存してください。
Pythonでコミュニティ投稿をJSONとCSVにエクスポートする
次のワークフローはPythonの標準ライブラリだけを使います。まず、このタスク用のヘルパーをsocq_collect.pyとして保存します。
import json
import os
import time
from urllib.parse import urlencode
from urllib.request import Request, urlopen
BASE = "https://api.socq.ai/v1"
PENDING = {"queued", "running", "retrying"}
def api(method, path, payload=None):
body = json.dumps(payload).encode("utf-8") if payload is not None else None
request = Request(
BASE + path, data=body, method=method,
headers={
"Authorization": "Bearer " + os.environ["SOCQ_API_KEY"],
"Content-Type": "application/json",
},
)
with urlopen(request, timeout=60) as response:
result = json.load(response)
if result.get("code") != 200:
raise RuntimeError(result)
return result["data"]
def collect(endpoint, payload):
task_id = api("POST", "/" + endpoint, payload)["task_id"]
print("Task:", task_id, flush=True)
path = "/tasks/" + task_id
deadline = time.monotonic() + 600
data = api("GET", path + "?limit=100")
while data["status"] in PENDING:
if time.monotonic() >= deadline:
raise TimeoutError("Resume GET " + path + "; do not resubmit automatically")
time.sleep(2)
data = api("GET", path + "?limit=100")
if data["status"] != "succeeded":
raise RuntimeError(data.get("error_message") or data["status"])
items, seen_cursors = [], set()
while True:
if time.monotonic() >= deadline:
raise TimeoutError("Resume pagination for " + task_id)
page = data["results"]
items.extend(page["items"])
if not page["has_more"]:
return task_id, items
cursor = page.get("next_cursor")
if not cursor or cursor in seen_cursors:
raise RuntimeError("Missing or repeated result cursor")
seen_cursors.add(cursor)
data = api("GET", path + "?" + urlencode({"limit": 100, "cursor": cursor}))
if data["status"] != "succeeded":
raise RuntimeError("Task is not ready for result pagination")
このヘルパーは、各タスクIDを出力し、最大10分間待機したうえで、保存されたすべての結果ページを読み取ります。クライアントがタイムアウトした場合は、IDを控えておき、そのタスクの照会を再開してください。
次に、同じ場所にexport_communities.pyを保存します。
import csv
import json
import sys
from urllib.parse import urlparse
from socq_collect import collect
urls = list(dict.fromkeys(sys.argv[1:]))
if not urls:
raise SystemExit("Usage: python3 export_communities.py COMMUNITY_URL [COMMUNITY_URL...]")
def cell(value):
text = "" if value is None else str(value)
return "'" + text if text.lstrip().startswith(("=", "+", "-", "@")) else text
fields = ["community_id", "community_url", "post_id", "post_url", "text",
"author_id", "author_username", "published_at", "collected_at",
"likes_count", "comments_count", "shares_count", "views_count"]
bundles, seen = [], set()
with open("community-posts.csv", "w", newline="", encoding="utf-8-sig") as output:
writer = csv.DictWriter(output, fieldnames=fields)
writer.writeheader()
for url in urls:
metadata_task, communities = collect("x/community", {"urls": [url]})
posts_task, posts = collect("x/community-posts", {
"urls": [url], "results_limit": 40,
})
bundles.append({
"input_url": url, "metadata_task_id": metadata_task,
"posts_task_id": posts_task, "communities": communities, "posts": posts,
})
# Save completed collections before processing another community.
with open("community-results.json", "w", encoding="utf-8") as saved:
json.dump(bundles, saved, ensure_ascii=False, indent=2)
community_id = urlparse(url).path.rstrip("/").split("/")[-1]
for post in posts:
post_id = post.get("id")
key = (community_id, post_id)
if post_id and key in seen:
continue
if post_id:
seen.add(key)
author = post.get("author") or {}
metrics = post.get("metrics") or {}
row = {
"community_id": community_id, "community_url": url,
"post_id": post_id, "post_url": post.get("url"), "text": post.get("text"),
"author_id": author.get("id"), "author_username": author.get("username"),
"published_at": post.get("published_at"),
"collected_at": post.get("collected_at"),
**{name: metrics.get(name) for name in
("likes_count", "comments_count", "shares_count", "views_count")},
}
writer.writerow({key: cell(value) for key, value in row.items()})
1つ以上の公開コミュニティのURLを指定して実行します。
python3 export_communities.py \
"https://x.com/i/communities/1493446837214187523"
次の2つが出力されます。
community-results.jsonは、各入力URL、2つのタスクID、コミュニティのメタデータ、投稿のレコードを保存します。community-posts.csvは、各コミュニティで返された投稿を1投稿1行で出力し、出典、投稿者、タイムスタンプ、取得できた指標を含みます。
このサンプルでは、コミュニティごとにメタデータ用と投稿用のタスクを別々に作成し、入力元のコミュニティを投稿に紐づけています。これにより、各レコードの収集元が明確になります。まとめて取得したい場合はバッチを使い、投稿ごとの出典を明示する必要がある場合は、ここで示した単一コミュニティのタスクのパターンを使ってください。
重複排除はcommunity_id + post_idで行います。同じコミュニティ内で繰り返された行は統合し、別のコミュニティで観測された同じ投稿は別々に保持します。投稿IDのないレコードは、1件ずつそのまま残します。
プログラムは、各コミュニティの処理が完了するたびにファイルを更新します。後続のリクエストが失敗しても、それまでに完了したコミュニティの分はファイルに残ります。出力をレポートに使う前に、完了した入力と記録されたエラーを確認してください。
スプレッドシート出力の元データとしてJSONを残す
CSVはレビュー担当者にとって扱いやすい形式ですが、データが平坦化されます。入れ子になったルール、メディア、投稿者のフィールドはJSONに残ります。列の構成が変わったら、保存したJSONから別のスプレッドシートを作り直してください。
サンプルでは、引用符、カンマ、複数行のテキストを正しく扱うために、Pythonの標準ライブラリのCSVライターを使っています。BOM付きUTF-8は、一般的なスプレッドシートへの取り込みに役立ちます。数式のように見える公開テキストはCSVでエスケープされ、JSONには元の内容がそのまま保存されます。桁数の多い数値のIDは、スプレッドシートで精度が失われないよう、テキストとして取り込んでください。
コミュニティの議論をトピックリサーチに活用する
たとえば、取得した議論の中で繰り返し出てくるオンボーディングの質問は何かを調べてみます。質問ごとにグループ分けし、各カテゴリに根拠となる投稿IDを残しておきます。
まず、コミュニティの説明文とルールを読みます。そのうえで、投稿の本文、公開日時、出典リンクをあわせて確認します。繰り返し出てくる質問、製品への不満、リソースの要望をグループ化し、付けたラベルの隣に根拠となる投稿IDを残してください。
コミュニティ詳細のワークフローで説明文とルールを保存したうえで、アプリケーション側でトピックの分類や要約を実行します。
ローカルで並べ替えたいいね数やコメント数の順位には、「この取得分での順位」と明記し、取得日時とレコード数を添えてください。後の取得で見当たらない投稿は「この取得では確認されなかった」と記録し、削除されたかどうかは、その投稿を個別に照会して調べます。
個別の議論の中身を見る
1つの議論を掘り下げるには、返された投稿のURLをX Thread Contextに送信し、対象の投稿、それ以前の返信チェーンの投稿、返信の関係を読み取ります。
この次のステップについては、Twitterのスレッドコンテキストのチュートリアルをご覧ください。特定の投稿への返信だけが必要な場合は、X Post Repliesを使います。出発点がコミュニティではなくアカウントの場合は、X User Postsを使ってください。
コンテンツの判断の裏付けとして元の投稿を残す
SocQのコミュニティのメタデータと投稿のエンドポイントは、コミュニティの特定、議論の収集、トピックのレビューをつなぎます。このコードは各投稿のコミュニティの出典を保持したままJSONとCSVにエクスポートするため、コンテンツチームは質問の確認、事例の整理、要約の入力データの準備を進められます。
Community Postsを開いて対象のコミュニティを取得する。
参考資料
- SocQ Community Postsのドキュメント — 受け付けるリンク、コミュニティごとの上限、標準の投稿フィールド。
- SocQ Communityのドキュメント — メタデータ、ルール、数値。
よくある質問(FAQ)
複数のXコミュニティから投稿を取得できますか?
はい。urlsに複数のコミュニティのURLを指定できます。結果の上限は各URLに適用されます。Pythonのエクスポート例では、すべての投稿について入力元のコミュニティを明確に残すため、URLごとに別のタスクを使っています。
コミュニティで過去に公開されたすべての投稿が取得できますか?
タスクは、指定したコミュニティからresults_limitを上限として、一部の投稿を読み取ります。返されたレコードが、その取得分の範囲になります。過去の分析を行う場合は、取得を分けて保存し、それぞれの範囲を明記してください。
投稿だけでなく、コミュニティのメンバーもエクスポートできますか?
Communityはメタデータとメンバー数・モデレーター数を返し、Community Postsは投稿を返します。個々のメンバー名簿は別のデータであり、これらのエンドポイントでは返されません。
コミュニティのフィードとユーザーのタイムラインはどう違いますか?
コミュニティのフィードは議論の場に投稿をまとめたもので、ユーザーのタイムラインはアカウントの投稿をまとめたものです。Community Postsにはコミュニティのリンク、User Postsにはユーザー名を使ってください。
「トップ」や「いいね順」で並べ替えられますか?
このエンドポイントは作成日時の順で返します。その取得分での指標によるランキングが必要な場合は、アプリケーション側でサンプルをいいね数やコメント数で並べ替えてください。
ページネーションで新しい投稿が取得できますか?
カーソルは、元のタスクが保存した次のページを読み取ります。新しく観測し直すには新しいタスクを送信し、重複するレコードは投稿IDで処理してください。
コミュニティの移行発表後の投稿はどう取得すればよいですか?
XはコミュニティからXChatへの移行に関する発表を公開しました。対象コミュニティのURLをCommunity Postsに送信し、成功後に返された投稿を読み取ります。空の結果と失敗は別々に記録し、取得日時を残して、保存済みの履歴と新しいクエリの結果を区別してください。