v1 から v2 への移行

標準 v1.1 タイムラインから X API v2 タイムラインへの移行

v1.1 のタイムラインエンドポイント (statuses/user_timeline および statuses/mentions_timeline) を使用している場合、このガイドの目的は、標準 v1.1 タイムラインエンドポイントと X API v2 タイムラインエンドポイントの類似点と相違点を理解し、既存の連携を新しいバージョンへ移行できるようにすることです。

類似点:
- 認証:
  - OAuth 1.0a User Context (逆時系列のホームタイムライン、ユーザーポストタイムライン、ユーザーのメンションタイムライン)
  - OAuth 2.0 App-Only (ユーザーポストタイムライン)
- 過去データへのアクセス制限: User timeline (ユーザーポストタイムライン) は直近 3200 件のポストにアクセスできます。mentions timeline (ユーザーのメンションタイムライン) は直近 800 件のメンションにアクセスできます。
- ポスト編集履歴およびメタデータのサポート
- レート制限 (ユーザーポストタイムライン)
- リフレッシュポーリング: since_id 以降の新しい結果を取得する機能
- ポスト ID を使ったタイムラインの走査
- 結果の仕様:
  - 結果の順序: 結果は逆時系列で返されます
  - 返信を除外する機能 (ユーザーポストタイムラインのみ)
  - リツイートを除外する機能 (ユーザーポストタイムラインのみ)
相違点
- 新しい認証機能:
  - OAuth 2.0 App-Only (ユーザーのメンションタイムライン)
  - OAuth 2.0 Authorization Code Flow with PKCE (逆時系列のホームタイムライン、ユーザーポストタイムライン、ユーザーのメンションタイムライン)
- アクセス要件: X API v2 の App および Project の要件
- レート制限 (ユーザーのメンションタイムラインおよび逆時系列のホームタイムライン)
- 追加のページネーション方法
  - レスポンスごとに異なる max_results (count)
- レスポンスデータの形式
- リクエストパラメータ
  - v2 のフィールドおよび expansions を含む、リクエストパラメータに基づいたカスタマイズ可能なデータ形式
  - 追加で利用可能なデータ: メトリクス、ポストのアノテーション、投票

類似点

認証 v1.1 の statuses/user_timeline エンドポイントと X API v2 のユーザーポストタイムラインエンドポイントは、OAuth 1.0a User Context と OAuth 2.0 App-Only の両方をサポートしています。そのため、X API v2 のバージョンへ移行しても、同じ認証方式と認可トークンを引き続き使用できます。 履歴アクセス v1.1 の statuses/user_timeline と X API v2 のユーザーポストタイムラインエンドポイントはどちらも、リツイートを含め、最新の 3200 件の投稿を返します。 v1.1 の statuses/mentions_timeline と X API v2 のユーザー言及タイムラインエンドポイントは、最新の 800 件の投稿を返すことができます。 ポスト編集履歴とメタデータのサポート どちらのバージョンも、編集履歴を表すメタデータを提供します。詳細については、filtered stream APIリファレンスと Edit Posts の基本事項ページを参照してください。 レート制限


Standard v1.1	X API v2
user_timeline: OAuth 1.0a User Context では 15 分あたり 900 リクエスト OAuth 2.0 App-Only では 15 分あたり 1500 リクエスト	User Posts timeline: OAuth 1.0a User Context では 15 分あたり 900 リクエスト OAuth 2.0 App-Only では 15 分あたり 1500 リクエスト

since_id を使ったポーリング更新 どちらのバージョンも、since_id を使用して最新の結果をポーリングできます。 ポストIDによるタイムラインの走査 どちらのエンドポイントも、ポストIDの構成方法に基づいて、ポストIDの「タイムスタンプ」を使用してタイムラインを走査する機能を備えています。この機能は概ね同じですが、次の点が異なります。


Standard timelines v1.1	timelines v2
since_id (排他的) max_id (包含的)	since_id (排他的) until_id (同じく排他的。包含的だった max_id と対照的)

レスポンスフィルタリングパラメータ


Standard timelines v1.1	timelines v2
レスポンスフィルタリングパラメータ: * include_rts * exclude_replies	レスポンスフィルタリングパラメータ: * exclude=retweets,replies
例 https://api.x.com/1.1/statuses/user_timeline.json?user_id=2244994945&include_rts=0&&exclude_replies=1	例: https://api.x.com/2/users/2244994945/tweets?max_results=100&exclude=retweets,replies
注意: user_timeline の場合: * include_rts=0 を使用しても、最新の 3200 件という過去の投稿の上限は変わりません	注意: ユーザーポストタイムラインの場合: * exclude=retweets を使用しても、最新の 3200 件という過去の投稿の上限は変わりません * exclude=replies を使用すると、過去の投稿の上限は最新の 800 件の返信に減少します

違い

認証 **v1.1 の statuses/mentions_timeline エンドポイントは OAuth 1.0a User Context のみをサポートします。X API v2 の user mention timeline エンドポイントは OAuth 1.0a User Context、OAuth 2.0 App-Only、OAuth 2.0 Authorization Code with PKCE をサポートします。 ** X API v2 の user Post timeline エンドポイントを使ってプライベートメトリクスやプロモーテッドメトリクスにアクセスする場合は、OAuth 1.0a User Context か OAuth 2.0 Authorization Code with PKCE を使用し、メトリクスにアクセスしたいポストを投稿したユーザーに紐づくユーザーアクセストークンを渡す必要があります。 エンドポイント URL X API v2 の timelines エンドポイントでは、ユーザー ID を表すパスパラメータ :id が必要になる点に注意してください。

Standard v1.1 endpoints:
X API v2 endpoint:

App と Project の要件 X API v2 の各エンドポイントでは、リクエストを認証する際に developer App の認証情報を使用する必要があり、その App は Project に関連付けられている必要があります。X API v1.1 のすべてのエンドポイントでは、単体の App からの認証情報、または Project に関連付けられた App からの認証情報のどちらも使用できます。 レート制限


mentions_timeline: OAuth 1.0a User Context で 15 分あたり 75 リクエスト	user mention timeline: OAuth 1.0a User Context で 15 分あたり 180 リクエスト OAuth 2.0 ベアラートークンで 15 分あたり 450 リクエスト
home_timelime: 15 分あたり 15 リクエストホームタイムラインでは最大 800 件のポストを取得可能	reverse chronological home timeline: 15 分あたり 180 リクエスト直近 7 日間にタイムライン上で作成されたすべてのポストに加え、作成日時にかかわらず最新 800 件のポストを取得できます。

リクエストパラメータ


Standard timelines v1.1	timelines v2
必須: user_id または screen_name	必須: 特定のユーザー ID をパスパラメータで指定
任意: count - リクエストごとに返される結果数の上限を設定 exclude_replies - 結果から返信を除外 Include_rts - 0 に設定すると結果からリツイートを除外 trim_user - 結果から再ハイドレートされたユーザーオブジェクトを除外 tweet_mode - 結果として返されるデータ形式を設定。140 文字を超えるポストには extended を設定 since_id - 結果内の最も古いポスト ID を設定 (下限値は含まない) max_id - 結果内の最新のポスト ID を設定 (上限値を含む)	任意: max_results - リクエストごとに返される結果数の上限を設定 exclude=retweets,replies - 結果からリツイートや返信を除外 tweet.fields - 返すポストオブジェクトのフィールドを設定 user.fields - 返すユーザーオブジェクトのフィールドを設定 place.fields - 返す place オブジェクトのフィールドを設定 media.fields - 返す media オブジェクトのフィールドを設定 poll.fields - 返す poll オブジェクトのフィールドを設定 expansions - 返す拡張フィールドとデータを設定 start_time - 結果の最も早い created_at 時刻を設定 end_time - 結果の最新の created_at 時刻を設定 since_id - 結果の最も古いポスト ID を設定 (下限値は含まない) until_id - 結果内の最新のポスト ID を設定 (上限値は含まない)

レスポンスデータ形式


Standard search v1.1	Search Posts v2
[ tweet object, tweet object ]	“data”: [id,text,id,text], “meta”: “oldest_id”: “1337085692623646724”, “newest_id”: “1334183616172019713”, “previous_token”: “77qpymm88g5h9vqkluldpw91lr0qzfz1sqydh841iz48k”, “result_count”: 10, “next_token”: “7140dibdnow9c7btw3w29gqolns6a1ipl3kzeae41vsxk”

X API v2 JSON 形式 X API v2 では、API が返すオブジェクト (Post や user オブジェクトなど) に対して、新しい JSON 設計を導入しています。X API v2 の形式や、fields および expansions の使い方について詳しくは、ガイドや、より広範なデータディクショナリを参照してください。

JSON のルートレベルでは、Standard エンドポイントは Post オブジェクトを statuses 配列で返しますが、X API v2 は data 配列で返します。
リツイートや引用を「statuses」で参照する代わりに、X API v2 の JSON ではリツイートおよび引用ツイートとして参照します。contributors や user.translator_type のような、多くのレガシー／非推奨フィールドは削除されます。
Post オブジェクト内の favorites と user オブジェクト内の favorites の両方を使う代わりに、X API v2 では like という用語を使用します。
X では、値を持たない JSON 値 (例: null) はペイロードに書き込まないという規約を採用しています。Post および user の属性は、null 以外の値を持つ場合にのみ含まれます。

Standard v1.1 と X API v2 のエンドポイントバージョンの最も大きな違いの 1 つは、ペイロード内で返すフィールドをどのように選択するかです。Standard エンドポイントでは、ペイロード内で返すフィールドまたはフィールドのセットを指定するために使用できるパラメータが複数ありますが、X API v2 バージョンでは、これらのさまざまなパラメータを fields と expansions に簡素化しています。

fields: X API v2 のエンドポイントでは、ペイロードに含めるフィールドを選択できます。たとえば、ポスト、user、Media、Place、Poll オブジェクトには、それぞれ返す (または返さない) ことができるフィールドのリストがあります。
expansions: ポストオブジェクトの JSON ペイロード内で参照されている関連オブジェクトを展開するために使用します。たとえば、すべての Retweet と Reply は他のポストを参照します。expansions=referenced_tweets.id を設定すると、これらのポストオブジェクトは tweet.fields の設定に従って展開されます。users、polls、media などの他のオブジェクトも展開できます。
conversation_id
2 つの新しい annotations フィールド (context と entities を含む)
複数の新しい metrics フィールド

標準 v1.1 のフィールドを新しい v2 のフィールドにマッピングする際に役立つデータ形式移行ガイドを用意しています。このガイドでは、特定のフィールドを返すために v2 リクエストで指定する必要がある、対応する expansions および fields パラメータについても説明しています。

コード例

ユーザーの投稿タイムライン (v2)

cURL

curl "https://api.x.com/2/users/2244994945/tweets?max_results=100&tweet.fields=created_at,public_metrics&exclude=retweets,replies" \
  -H "Authorization: Bearer $BEARER_TOKEN"

from xdk import Client

client = Client(bearer_token="YOUR_BEARER_TOKEN")

# ユーザーの投稿タイムラインを取得
for page in client.posts.get_user_posts(
    "2244994945",
    tweet_fields=["created_at", "public_metrics"],
    exclude=["retweets", "replies"],
    max_results=100
):
    for post in page.data:
        print(f"{post.created_at}: {post.text[:50]}...")

import { Client } from "@xdevplatform/xdk";

const client = new Client({ bearerToken: "YOUR_BEARER_TOKEN" });

// ユーザーの投稿タイムラインを取得
const paginator = client.posts.getUserPosts("2244994945", {
  tweetFields: ["created_at", "public_metrics"],
  exclude: ["retweets", "replies"],
  maxResults: 100,
});

for await (const page of paginator) {
  page.data?.forEach((post) => {
    console.log(`${post.created_at}: ${post.text?.slice(0, 50)}...`);
  });
}

ユーザーのメンションタイムライン (v2)

cURL

curl "https://api.x.com/2/users/2244994945/mentions?max_results=100&tweet.fields=created_at,author_id" \
  -H "Authorization: Bearer $BEARER_TOKEN"

from xdk import Client

client = Client(bearer_token="YOUR_BEARER_TOKEN")

# ユーザーのメンションを取得
for page in client.posts.get_user_mentions(
    "2244994945",
    tweet_fields=["created_at", "author_id"],
    max_results=100
):
    for post in page.data:
        print(f"Mentioned by {post.author_id}: {post.text[:50]}...")

import { Client } from "@xdevplatform/xdk";

const client = new Client({ bearerToken: "YOUR_BEARER_TOKEN" });

// ユーザーのメンションを取得
const paginator = client.posts.getUserMentions("2244994945", {
  tweetFields: ["created_at", "author_id"],
  maxResults: 100,
});

for await (const page of paginator) {
  page.data?.forEach((post) => {
    console.log(`Mentioned by ${post.author_id}: ${post.text?.slice(0, 50)}...`);
  });
}

次のステップ X API v2 Post ルックアップ向けクイックスタートガイドを確認する v2 Post ルックアップ用のAPIリファレンスを確認するタイムラインエンドポイントのサンプルコードを確認する


mentions_timeline: OAuth 1.0a User Context で 15 分あたり 75 リクエスト	user mention timeline: OAuth 1.0a User Context で 15 分あたり 180 リクエスト OAuth 2.0 ベアラートークンで 15 分あたり 450 リクエスト
home_timelime: 15 分あたり 15 リクエストホームタイムラインでは最大 800 件のポストを取得可能	reverse chronological home timeline: 15 分あたり 180 リクエスト直近 7 日間にタイムライン上で作成されたすべてのポストに加え、作成日時にかかわらず最新 800 件のポストを取得できます。

Getting Started

Fundamentals

Partners & Customers

Resources

v1 から v2 への移行

標準 v1.1 タイムラインから X API v2 タイムラインへの移行

類似点

違い

コード例

ユーザーの投稿タイムライン (v2)

ユーザーのメンションタイムライン (v2)

​標準 v1.1 タイムラインから X API v2 タイムラインへの移行

​類似点

​違い

​コード例

​ユーザーの投稿タイムライン (v2)

​ユーザーのメンションタイムライン (v2)

標準 v1.1 タイムラインから X API v2 タイムラインへの移行

類似点

違い

コード例

ユーザーの投稿タイムライン (v2)

ユーザーのメンションタイムライン (v2)