公式X API v2からSorsa API v3へ移行する
既存のTwitter/X API v2連携をSorsa API v3へ移すためのリファレンスです。認証、エンドポイントの対応、レスポンス形式、ページネーション、HTTPメソッド、検索構文、エラー処理、curl・Python・JavaScriptのコード例を説明します。
Sorsa APIは読み取り専用です。投稿、DM、「いいね」、フォローなどの書き込みも行う連携では、書き込み用に公式APIキーを残し、読み取り部分だけを移行してください。新規アカウントにはカード不要の無料100リクエストがあり、本番を切り替える前に対応する機能を検証できます。
注: 費用比較と手順に沿った例は、ブログのTwitter/X APIからの移行:開発者向け完全ガイドを参照してください。
変更点の概要
認証
公式APIは、アプリ専用リクエストにOAuth 2.0 Bearerトークン、ユーザーの権限で行うリクエストにOAuth 1.0a User Contextを使います。ApiKeyヘッダーで渡します。ダッシュボードでキーを発行してください。
エンドポイントの対応
ユーザー
GET /info-batchは1リクエストで最大100ユーザー名またはIDに対応します。?usernames=a&usernames=bのようにクエリパラメーターを繰り返します。GET /followersとGET /followsは、自己紹介、フォロワー数、認証状態を含む完全なプロフィールを1ページ最大200件返します。
ツイート
tweet_linkには完全なURL(https://x.com/user/status/123)または数値ID("123")を指定できます。POST /tweet-info-bulkは1回最大100ツイートです。POST /tweet-infoの繰り返しから替えると、リクエストを最大100分の1に減らせます。POST /user-tweetsには3,200件の上限がありません。next_cursorがなくなるまで取得すると、最初のツイートまでたどれます。過去のデータを参照してください。
検索
/search-tweetsはXのWeb版高度な検索の構文を使います。基本的な語は多くの場合そのまま使えますが、API v2固有の演算子は再利用前に確認してください。検索演算子を参照してください。POST /mentionsには、公式APIにないmin_likes、min_replies、min_retweets、since_date、until_dateがあります。
リスト
コミュニティ
公式X APIはコミュニティのエンドポイントを公開していません。Sorsa独自の機能です。
リクエストの詳細と提供状況はリストとコミュニティを参照してください。移行前に現在の対応状況を確認します。
アクションの確認
以下は1回の呼び出しで参加・行動の有無を調べる機能です。公式APIに同等機能はなく、同じ処理には一覧全体の取得とクライアント側の検索が必要です。
マーケティングキャンペーンの確認を参照してください。
分析(Sorsa独自)
暗号資産関連のアカウント(インフルエンサー、プロジェクト、VC)の一部を索引化したデータです。Sorsa Scoreと暗号資産分析を参照してください。
ユーティリティ
ID変換を参照してください。
レスポンス形式の変更
移行で最も大きい変更点です。公式v2はdata、includes、metaで包まれますが、Sorsaはフラットなオブジェクトで、投稿者情報を各ツイートに直接含めます。
ユーザープロフィール
公式X API v2(フィールド選択あり):ツイート
公式X API v2(expansions=author_idあり):
フィールドの対応
ユーザーのフィールド
ツイートのフィールド
ページネーション
公式APIはクエリにpagination_tokenを渡し、meta.next_tokenを返します。Sorsaは両方向で同じnext_cursorを使います。
GETではクエリパラメーターとして渡します。
next_cursorは最上位にあります。
next_cursorがない、またはnullなら次のページはありません。詳細はページネーションを参照してください。
HTTPメソッドの違い
公式APIではGETでも、SorsaではPOSTの機能があります。
基本的に、ツイート内容、検索、コミュニティはJSON本文付きの
POSTです。ユーザー識別子を取る/user-tweetsもPOSTです。ユーザー、リスト、ユーティリティは、クエリまたはパスのパラメーターを使うGETです。例外の/check-commentはツイートリンクを取りますがGETです。不明な場合は各リファレンスを確認してください。
コード移行の例
ユーザープロフィールを取得する
移行前(公式API):ツイートを検索する
移行前:全フォロワーを順に取得する
移行前:検索構文
SorsaはXのWeb版高度な検索の構文を使い、公式API v2の演算子とは異なります。基本キーワード、フレーズ、from:、to:など使えるものは維持し、API固有のフィルターを変換して結果をテストしてください。たとえば、ネイティブリツイートの除外は-filter:nativeretweetsです。
完全なリファレンス:検索演算子。
/mentionsには、サーバー側のmin_likes、min_replies、min_retweets、since_date、until_dateもあります。メンションの追跡を参照してください。
エラー処理
公式APIは、構造化されたerrors配列を返します。
400、401、403、404、429、500です。エラーコードを参照してください。
429では待機して再試行します。上限は全エンドポイント共通で毎秒20リクエストです。個別の時間枠を追う必要はありません。レート制限を参照してください。
両方のAPIに対応した再試行ラッパー:
移行チェックリスト
Authorization: Bearer ...をApiKey: ...に替える。- OAuth 1.0aの署名処理(コンシューマーキー、アクセストークン、署名生成)を取り除く。
- ベースURLを
https://api.x.com/2からhttps://api.sorsa.io/v3に替える。 - 上記の表で全エンドポイントのパスを対応させる。
- ツイート、検索、コメント、引用、リツイートしたユーザーの取得をGETからPOSTに替える。
tweet.fields、user.fields、media.fields、expansionsを削除する。- パーサーを変更し、
data・includes・metaの外枠を取り出す処理をなくす。 - フィールド名を変更する(
name→display_name、text→full_textなど)。 public_metricsの外枠をなくし、指標へ直接アクセスする。pagination_token・next_tokenをnext_cursorに替える。{ "message": "..." }に合わせてエラー処理を変える。- レート制限を、個別の時間枠なしの共通20件/秒へ調整する。
- API Playgroundで主要なエンドポイントをテストする。
GET /key-usage-infoで割り当て量を監視する。- 投稿・DMなどの書き込みが必要なら公式APIキーを保持する。