Xはブラウザ上では今もタイムラインのように見えます。しかし、公開データの仕様はもっと厳密です。ユーザー名はポストのURLではなく、引用はリポストではなく、返信は引用ではありません。削除されたポストや非公開のポストは、空のレコードになるのではなく、きちんと失敗する必要があります。
このチュートリアルでは、SocQ X APIを使って本番向けのワークフローを構築します。公式APIと公開データAPIの違い、エンドポイントの使い分け、入力値の整え方、非同期タスク、フィールドの意味、更新頻度、責任ある利用までを扱います。
結論: ユーザー名、
x.comまたはtwitter.comのステータスURL、あるいは検索クエリをPOST /v1/x/{resource}に送信し、タスクIDを保存して、/v1/tasks/{id}をポーリングします。リソースを区別する列を持たせずに、引用、リポスト、返信を1つのテーブルにまとめないでください。
公式のX APIか、公開データAPIか
公式のX APIは有料で、権限の許可が必要です。ポストの投稿、ダイレクトメッセージの送信、広告の管理、ユーザーとしてのフォローやいいね、ストリームやその他のアカウント認可が必要な機能を使いたい場合は、公式のX APIが正しい製品です。アクセス条件や料金は変わるため、書き込み系やパートナー向けの製品については、現在の開発者向けドキュメントを正としてください。
SocQは、対応しているプロフィール、既知のポスト、ユーザーのポスト期間、検索、会話のエッジ、トレンドを対象とした、公開データの読み取りレイヤーです。Xのユーザーとして認証することはなく、公式の投稿機能や広告機能の代わりにはなりません。料金とベンダーの位置づけについては、Twitter API代替サービス、Twitter スクレイパーAPI比較、TwitterAPI.ioの代替サービスをご覧ください。エンドポイントを選ぶ前に、アクセスモデルを選んでください。
適切なXエンドポイントを選ぶ
| リソース | エンドポイント | 受け付ける公開入力 | 主な用途 |
|---|---|---|---|
| プロフィール | /v1/x/profiles | ユーザー名(@の有無は問わない) | 公開されているアイデンティティと表示されている数値 |
| ポスト | /v1/x/posts | x.comまたはtwitter.comのステータスURL | 既知のポスト1件 |
| ユーザーのポスト | /v1/x/user-posts | ユーザー名 | アカウントの最近の公開ポスト |
| 検索 | /v1/x/search | クエリ | 最新またはトップの公開ポストの探索 |
| 返信 | /v1/x/post-replies | ステータスURL | 既知のポストへの返信 |
| 引用 | /v1/x/post-quotes | ステータスURL | 既知のポストの引用ポスト |
次のエンドポイントも利用できます。
post-retweeters:公開されているステータスURL向け。followers-listとfollowing-list:ユーザー名向けで、results_limitは200〜2000の範囲で200刻み。trends:数値のWOEID向け。
引用、リポスト、返信は、それぞれ別のリソースです。引用には、それ自体のポスト本文があります。リポストしたユーザーの一覧は、プロフィールの集合です。返信は、会話に属するポストです。これらを同じオブジェクトであるかのようにアップサートしないでください。
ユーザー名、URL、クエリを正規化する
送信された値は保持したうえで、コピーを整形します。
@の有無にかかわらずユーザー名を受け付け、保存するときは正規の形式のユーザー名1つに統一する。x.comとtwitter.comの両方のホストを受け付ける。ポストを対象とするエンドポイントでは、数値の/status/{id}パスを必須にする。- トラッキング用のクエリパラメータを取り除く。ステータスIDが保たれていれば、特定のモバイルやロケールのホストは要求しない。
- ユーザー名は大文字小文字を区別せずに、ポストはステータスIDで重複を排除する。
- 空のクエリとユーザー名は、送信前に弾く。
- 検索式は出自の行に保持し、アナリストが各ポストがデータセットに入った理由を説明できるようにする。
user-postsとsearchは、results_limitを20〜2000の範囲で20刻みで受け付けます。検索のsort_byはlatestまたはtopです。post-repliesでは、sort_byにrelevance、latest、likesも指定できます。
収集タスクを送信する
プロフィールを収集します。
curl -X POST "https://api.socq.ai/v1/x/profiles" \
-H "Authorization: Bearer $SOCQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{"usernames":["openai","@github"]}'
どちらのホスト名でも、既知のポストを収集できます。
curl -X POST "https://api.socq.ai/v1/x/posts" \
-H "Authorization: Bearer $SOCQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{"urls":["https://x.com/X/status/2073395918011789670"]}'
ユーザーのポスト期間を収集します。
curl -X POST "https://api.socq.ai/v1/x/user-posts" \
-H "Authorization: Bearer $SOCQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{"usernames":["openai","github"],"results_limit":40}'
公開ポストを検索します。
curl -X POST "https://api.socq.ai/v1/x/search" \
-H "Authorization: Bearer $SOCQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{"query":"AI lang:en","results_limit":100,"sort_by":"latest"}'
返信と引用は、別々のジョブとして収集します。
curl -X POST "https://api.socq.ai/v1/x/post-replies" \
-H "Authorization: Bearer $SOCQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{"urls":["https://x.com/X/status/2073395918011789670"],"results_limit":20,"sort_by":"latest"}'
curl -X POST "https://api.socq.ai/v1/x/post-quotes" \
-H "Authorization: Bearer $SOCQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{"urls":["https://x.com/X/status/2073395918011789670"],"results_limit":20}'
返されたタスクIDは、リソース名と正規化した入力とあわせて保存してください。
重複を作らずにタスクをポーリングする
curl "https://api.socq.ai/v1/tasks/$TASK_ID?limit=100" \
-H "Authorization: Bearer $SOCQ_API_KEY"
queuedとrunningは正常な状態として扱い、指数バックオフを使います。タスクが成功したらdata.results.itemsを読み取り、has_moreがtrueの間はnext_cursorを使って続きを取得します。
堅牢なワーカーは、次の情報を保存してください。
- バッチIDとSocQのタスクID。
- リソースと、正規化したユーザー名、URL、またはクエリ。
- 送信時刻と完了時刻。
- 最終ステータスとエラーの種別。
- 最後に処理した結果のカーソル。
ワーカーが再起動したからといって、同じ検索を再送信する理由にはなりません。
返されるフィールドを理解する
レコードは、id、platform、resource、type、url、created_at、collected_at、extraを共通で持ちます。
プロフィールには、username、name、description、avatar_url、cover_url、is_verified、is_privateと、表示されている数値が含まれます。保護されたアカウントは、公開データの対象ではありません。
ポストには、公開されている場合に、text、language、author、表示されている数値、media、hashtags、mentionsが含まれます。エンティティのキーにはidを優先して使い、ステータスURLは出自として保持してください。
返信と引用は、ポストと同じ形を再利用します。リポストしたユーザーは、プロフィールと同じ形を再利用します。トレンドは、ロケール単位の探索用の行であり、ポストではありません。
削除されたポストや非公開のポストは、入力またはタスクの境界で失敗する必要があります。空のポストを挿入したり、エンゲージメントを0と偽ったり、collected_atをcreated_atとして流用したりしないでください。
検索結果は、ランク付けされた探索です。latestとtopは、限られた期間に対する異なる並び順であり、完全な過去のアーカイブではありません。
プロフィール、ポスト、検索のためのPythonワーカー
import time
import requests
BASE = "https://api.socq.ai/v1"
HEADERS = {
"Authorization": f"Bearer {SOCQ_API_KEY}",
"Content-Type": "application/json",
}
def collect(resource, payload):
created = requests.post(
f"{BASE}/x/{resource}",
headers=HEADERS,
json=payload,
timeout=30,
)
created.raise_for_status()
task_id = created.json()["data"]["task_id"]
delay = 2
while True:
response = requests.get(
f"{BASE}/tasks/{task_id}",
headers=HEADERS,
timeout=30,
)
response.raise_for_status()
task = response.json()["data"]
if task["status"] == "succeeded":
return task["results"]["items"]
if task["status"] in {"failed", "cancelled"}:
raise RuntimeError(task)
time.sleep(delay)
delay = min(delay * 1.5, 15)
profiles = collect("profiles", {"usernames": ["openai"]})
hits = collect("search", {
"query": "AI lang:en",
"results_limit": 40,
"sort_by": "latest",
})
本番に投入する前に、カーソルによるページネーション、タイムアウトとリトライ可能な5xxレスポンスに対する回数制限付きのリトライ、冪等なアップサートを追加してください。
ポストとメトリクスのスナップショットを分けてモデル化する
ポストの識別情報と、ポストのメトリクスは、変化する速さが異なります。
x_entity
resource
platform_id
canonical_url_or_username
text_or_description
author_id
created_at
first_seen_at
last_seen_at
x_snapshot
resource
platform_id
collected_at
likes_count
replies_count
reposts_count
quotes_count
source_task_id
アップサートはresource + idで行います。引用、返信、元のポストを同じポストテーブルに保存してよいのは、resourceが必須の列として残る場合だけです。リポストしたユーザーは、プロフィールまたはエッジのテーブルに保存してください。
リポストしたユーザーのスナップショットから、引用の増加を計算しないでください。これらのメトリクスは互換ではありません。
保存前に検証する
platformはxと等しいこと。resourceはエンドポイントと一致すること。- リソースがポスト形式の場合、ステータスURLに数値の
/status/のIDが含まれること。 - リソースが
user-postsでフィールドが存在する場合、投稿者のユーザー名は送信したアカウントと一致すること。 - カウントは、負でない数値かnullであること。
- タイムスタンプはパースできること。
- 非公開または削除済みの入力が失敗した場合、成功した空のポストにしてはならない。
無効な行は、生のタスクのペイロードとともに隔離して保管してください。
エンティティごとに更新スケジュールを選ぶ
| エンティティ | 開始時の妥当な頻度 | 理由 |
|---|---|---|
| プロフィール | 週次または月次 | プロフィール文やアイデンティティのフィールドは変化がゆるやか |
| 既知のポスト | アクティブな間は1時間〜1日ごと | 公開メトリクスの変化が速い |
| ユーザーのポスト期間 | モニタリングでは1時間〜1日ごと | タイムラインは範囲が限られ、ランク付けされている |
| 検索 | クエリに合わせたスケジュール | latestとtopはアーカイブではない |
| 返信・引用 | ポストがアクティブな間は1時間ごと | 会話のエッジはまとまって届く |
| フォロワー・フォロー中 | 週次 | リストが大きく、200刻みで取得する |
| トレンド | 1時間ごと、または1日数回 | WOEIDのセットが入れ替わる |
ビジネス上の問いに、より新しいスナップショットが不要なら、収集の頻度を減らしてください。
よくある失敗パターン
ポストのURLで何も返らない
URLが公開されていて、まだ利用可能で、/status/{id}を含んでいることを確認してください。削除されたポストや保護されたポストは、きちんと失敗するはずです。入力レベルのエラーは保持してください。
検索結果が不完全に見える
results_limitはリクエストの上限です。ランキング、インデックス、latestとtopの切り替えのいずれもが、取得されるページを変えます。クエリとソートは、レコードとあわせて保存してください。
引用がリポストとして保存された
これらは別のエンドポイントで、別のオブジェクトです。resourceを主キーに含めてください。
フォロワーのジョブが上限値を拒否する
フォロワーとフォロー中は、200〜2000の範囲で200刻みの値を受け付けます。ユーザーのポストと検索は、20刻みです。
メトリクスがブラウザの表示と一致しない
公開されているカウントはスナップショットです。遅延したり、丸められたり、非表示になったりすることがあります。パーサーを疑う前に、collected_atを比較してください。
同じユーザーが2回出てくる
ユーザー名を正規化し、安定した公開IDを優先してください。アカウント名が変更された場合に備えて、エイリアスのテーブルを保持します。
Xのデータを責任をもって利用する
正当な目的に必要な公開フィールドだけを収集してください。保護されたアカウント、ブロック、ログインの壁、その他のアクセス制御を回避しないでください。センシティブな個人のプロファイリングや、人に重大な影響を与えうる自動化された判断は、安全策なしには行わないでください。
Xのデータは個人データにあたる場合があります。必要に応じて適法な根拠を確立し、保持と削除のルールを定め、APIキーとエクスポートを保護し、Xの現行の利用規約を資格のある専門家とともに確認してください。公開データAPIは、ポストやメディアを再公開するライセンスを与えるものではありません。
よくある質問(FAQ)
XやTwitterのスクレイピングは合法ですか?
一律の答えはありません。管轄、データ、手法、目的、契約、安全策によって異なります。このチュートリアルは法的助言ではありません。
これは公式のX APIの代わりになりますか?
いいえ。投稿、DM、広告、ストリーム、その他の許可が必要な操作には、引き続き公式のアクセスが必要です。SocQは、対応している公開データの読み取りをカバーします。
非公開または削除済みのポストを収集できますか?
いいえ。そうした入力は、きちんと失敗するはずです。保護を回避しないでください。
引用はリポストと同じですか?
いいえ。引用はポストです。リポストしたユーザーはプロフィールです。返信は3つ目のリソースです。
検索は完全な履歴を返しますか?
いいえ。1つのクエリに対して、限られた範囲を並べた結果を返します。
重複排除にはどのキーを使うべきですか?
resource + idを優先してください。公開IDがない場合は、正規化したステータスURLまたはユーザー名にフォールバックします。