Expansions

API レスポンスに関連オブジェクトを含める

Expansions を使用すると、1 つの API レスポンスに関連オブジェクトを含めることができます。複数のリクエストを行う代わりに、1 回のリクエストでポストとその投稿者、メディア、あるいは参照先の投稿をまとめて取得できます。

---

expansions の仕組み

expansions を指定すると、API はレスポンスの includes セクションにそのオブジェクト全体を含めます。

curl "https://api.x.com/2/tweets/1234567890?expansions=author_id" \
  -H "Authorization: Bearer $TOKEN"

レスポンス：

{
  "data": {
    "id": "1234567890",
    "text": "Hello world!",
    "author_id": "2244994945"
  },
  "includes": {
    "users": [{
      "id": "2244994945",
      "name": "X Developers",
      "username": "xdevelopers"
    }]
  }
}

data 内の author_id は、includes 内のユーザーオブジェクトに紐づきます。

---

投稿の Expansions

Expansion	Returns	Use case
author_id	ユーザーオブジェクト	投稿の作成者の詳細を取得する
referenced_tweets.id	ポストオブジェクト (複数可)	引用・返信先の投稿を取得する
referenced_tweets.id.author_id	ユーザーオブジェクト (複数可)	参照されている投稿の作成者を取得する
in_reply_to_user_id	ユーザーオブジェクト	返信先ユーザーを取得する
attachments.media_keys	メディアオブジェクト (複数可)	画像、動画、GIF を取得する
attachments.poll_ids	投票オブジェクト	投票の選択肢と投票数を取得する
geo.place_id	場所オブジェクト	位置情報の詳細を取得する
entities.mentions.username	ユーザーオブジェクト (複数可)	メンションされているユーザーを取得する
edit_history_tweet_ids	ポストオブジェクト (複数可)	編集された投稿の以前のバージョンを取得する

---

User expansions

Expansion	Returns	Use case
pinned_tweet_id	ポストオブジェクト	ユーザーの固定されたポストを取得

---

Space expansions

Expansion	Returns	Use case
creator_id	User object	Space の作成者を取得する
host_ids	User object(s)	Space のホストを取得する
speaker_ids	User object(s)	Space のスピーカーを取得する
invited_user_ids	User object(s)	Space に招待されたユーザーを取得する

---

DM の Expansions

Expansion	戻り値	ユースケース
sender_id	User オブジェクト	メッセージの送信者を取得
participant_ids	複数の User オブジェクト	会話の参加ユーザーを取得
attachments.media_keys	Media オブジェクト	添付メディアを取得
referenced_tweets.id	Post オブジェクト	参照されているポストを取得

---

リストの Expansions

Expansion	戻り値	ユースケース
owner_id	Userオブジェクト	リスト所有者を取得

---

フィールドとの併用

Expansions は各オブジェクトについてデフォルトのフィールドを返します。追加のフィールドを取得するには、expansions とフィールドパラメーターを併用してください。

curl "https://api.x.com/2/tweets/1234567890?\
expansions=author_id,attachments.media_keys&\
user.fields=description,public_metrics&\
media.fields=url,alt_text" \
  -H "Authorization: Bearer $TOKEN"

レスポンス:

{
  "data": {
    "id": "1234567890",
    "text": "Check out this image!",
    "author_id": "2244994945",
    "attachments": {
      "media_keys": ["3_1234567890"]
    }
  },
  "includes": {
    "users": [{
      "id": "2244994945",
      "name": "X Developers",
      "username": "xdevelopers",
      "description": "The voice of the X Developer Platform",
      "public_metrics": {
        "followers_count": 570842
      }
    }],
    "media": [{
      "media_key": "3_1234567890",
      "type": "photo",
      "url": "https://pbs.twimg.com/media/example.jpg",
      "alt_text": "Example image"
    }]
  }
}

---

複数のexpansions

複数のexpansions をカンマ区切りのリストとして指定します:

expansions=author_id,referenced_tweets.id,attachments.media_keys

---

共通パターン

ポストの完全なコンテキスト

投稿者、メディア、参照ポストを含むポストを取得します。

expansions=author_id,attachments.media_keys,referenced_tweets.id
tweet.fields=created_at,public_metrics,conversation_id
user.fields=username,name,profile_image_url
media.fields=url,preview_image_url,type

会話スレッド

返信とその投稿者情報を取得します。

expansions=author_id,in_reply_to_user_id,referenced_tweets.id
tweet.fields=conversation_id,in_reply_to_user_id,created_at
user.fields=username,name

固定ポストがあるユーザー

固定ポストが設定されているユーザーのプロフィールを取得します。

expansions=pinned_tweet_id
user.fields=description,public_metrics,verified
tweet.fields=created_at,public_metrics

---

データとincludesのリンク

includes 内のオブジェクトには位置情報が含まれていません。IDを使ってそれらを関連付けます:

# Python example
response = api_call()
post = response["data"]
users = {u["id"]: u for u in response["includes"]["users"]}

# 投稿者を取得
author = users.get(post["author_id"])
print(f"{author['name']} said: {post['text']}")

// JavaScript の例
const { data: post, includes } = response;
const users = Object.fromEntries(
  includes.users.map(u => [u.id, u])
);

const author = users[post.author_id];
console.log(`${author.name} said: ${post.text}`);

---

次のステップ

フィールド

各オブジェクトごとに取得するフィールドを指定します。

データ辞書

オブジェクトスキーマの完全な一覧です。