連携ガイド

このガイドでは、User lookup エンドポイントをアプリケーションに連携するために必要な主要概念を説明します。

認証

すべての X API v2 エンドポイントには認証が必要です。ユースケースに合った方式を選択してください:

Method	Best for	プライベートなメトリクスにアクセスできるか
OAuth 2.0 App-Only	サーバー間通信、公開データ	不可
OAuth 2.0 Authorization Code with PKCE	ユーザー向けアプリ	可 (認可済みユーザーのデータについて)
OAuth 1.0a User Context	レガシー連携	可 (認可済みユーザーのデータについて)

App-Only 認証

公開ユーザーデータには Bearer Token を使用します:

cURL

curl "https://api.x.com/2/users/by/username/XDevelopers" \
  -H "Authorization: Bearer $BEARER_TOKEN"

from xdk import Client

client = Client(bearer_token="YOUR_BEARER_TOKEN")

# username でユーザーを取得
response = client.users.get_by_username("XDevelopers")
print(response.data)

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

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

const response = await client.users.getByUsername("XDevelopers");
console.log(response.data);

User Context 認証

認証済みユーザーエンドポイント (/2/users/me) では必須です:

cURL

curl "https://api.x.com/2/users/me" \
  -H "Authorization: Bearer $USER_ACCESS_TOKEN"

from xdk import Client

# OAuth 2.0 ユーザー access token を使用
client = Client(bearer_token="YOUR_USER_ACCESS_TOKEN")

# 認証済みユーザーのプロフィールを取得
response = client.users.get_me()
print(response.data)

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

// OAuth 2.0 ユーザー access token を使用
const client = new Client({ accessToken: "YOUR_USER_ACCESS_TOKEN" });

const response = await client.users.getMe();
console.log(response.data);

/2/users/me エンドポイントは User Context 認証でのみ動作します。App-Only トークンではエラーが返ります。

Fields と expansions

X API v2 はデフォルトでは最小限のデータのみを返します。必要なデータを正確にリクエストするには fields と expansions を使用します。

デフォルトのレスポンス

{
  "data": {
    "id": "2244994945",
    "name": "X Developers",
    "username": "XDevelopers"
  }
}

利用可能なフィールド

user.fields

Field	Description
`created_at`	アカウント作成のタイムスタンプ
`description`	ユーザーの bio
`entities`	bio 内のパース済み URL
`location`	ユーザーが設定した所在地
`pinned_tweet_id`	ピン留めした Post の ID
`profile_image_url`	アバターの URL
`protected`	アカウントが非公開かどうか
`public_metrics`	フォロワー/フォロー中の件数
`url`	Web サイトの URL
`verified`	認証済みステータス
`withheld`	保留情報

tweet.fields (pinned_tweet_id expansion が必要)

Field	Description
`created_at`	Post 作成のタイムスタンプ
`text`	Post の本文
`public_metrics`	エンゲージメントの件数
`entities`	ハッシュタグ、メンション、URL

フィールドを使った例

cURL

curl "https://api.x.com/2/users/by/username/XDevelopers?\
user.fields=created_at,description,public_metrics,verified&\
expansions=pinned_tweet_id&\
tweet.fields=created_at,public_metrics" \
  -H "Authorization: Bearer $BEARER_TOKEN"

from xdk import Client

client = Client(bearer_token="YOUR_BEARER_TOKEN")

# 追加フィールドと expansions 付きでユーザーを取得
response = client.users.get_by_username(
    "XDevelopers",
    user_fields=["created_at", "description", "public_metrics", "verified"],
    expansions=["pinned_tweet_id"],
    tweet_fields=["created_at", "public_metrics"]
)

print(response.data)
print(response.includes)  # 展開されたピン留め Post が含まれます

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

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

const response = await client.users.getByUsername("XDevelopers", {
  userFields: ["created_at", "description", "public_metrics", "verified"],
  expansions: ["pinned_tweet_id"],
  tweetFields: ["created_at", "public_metrics"],
});

console.log(response.data);
console.log(response.includes); // 展開されたピン留め Post が含まれます

expansions 付きのレスポンス

レスポンス例

{
  "data": {
    "id": "2244994945",
    "name": "X Developers",
    "username": "XDevelopers",
    "created_at": "2013-12-14T04:35:55.000Z",
    "verified": true,
    "pinned_tweet_id": "1234567890",
    "public_metrics": {
      "followers_count": 583423,
      "following_count": 2048,
      "tweet_count": 14052
    }
  },
  "includes": {
    "tweets": [
      {
        "id": "1234567890",
        "text": "Welcome to the X Developer Platform!",
        "created_at": "2024-01-15T10:00:00.000Z"
      }
    ]
  }
}

Fields と expansions ガイド

レスポンスのカスタマイズについて詳しく学ぶ

バッチルックアップ

1 度のリクエストで複数のユーザーをルックアップします:

cURL (by IDs)

curl "https://api.x.com/2/users?ids=2244994945,783214,6253282&\
user.fields=username,verified" \
  -H "Authorization: Bearer $BEARER_TOKEN"

curl "https://api.x.com/2/users/by?usernames=XDevelopers,X,XAPI&\
user.fields=username,verified" \
  -H "Authorization: Bearer $BEARER_TOKEN"

from xdk import Client

client = Client(bearer_token="YOUR_BEARER_TOKEN")

# ID で複数ユーザーを取得
response = client.users.get_users(
    ids=["2244994945", "783214", "6253282"],
    user_fields=["username", "verified"]
)
for user in response.data:
    print(f"{user.username}: {user.verified}")

# username で複数ユーザーを取得
response = client.users.get_users_by_usernames(
    usernames=["XDevelopers", "X", "XAPI"],
    user_fields=["username", "verified"]
)
for user in response.data:
    print(f"{user.username}: {user.verified}")

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

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

// ID で複数ユーザーを取得
const byIds = await client.users.getUsers({
  ids: ["2244994945", "783214", "6253282"],
  userFields: ["username", "verified"],
});
byIds.data.forEach((user) => {
  console.log(`${user.username}: ${user.verified}`);
});

// username で複数ユーザーを取得
const byUsernames = await client.users.getUsersByUsernames({
  usernames: ["XDevelopers", "X", "XAPI"],
  userFields: ["username", "verified"],
});
byUsernames.data.forEach((user) => {
  console.log(`${user.username}: ${user.verified}`);
});

バッチリクエストは最大 100 ユーザーに制限されます。より大きなデータセットには複数リクエストを利用してください。

エラー処理

一般的なエラー

Status	Error	Solution
400	Invalid request	パラメータの書式を確認
401	Unauthorized	認証情報を確認
403	Forbidden	App の権限を確認
404	Not Found	ユーザーが存在しないか凍結されている
429	Too Many Requests	待機してから再試行 (レート制限を参照)

凍結・削除されたユーザー

ユーザーが凍結または削除されている場合:

単一ユーザーのルックアップでは 404 が返る
複数ユーザーのルックアップでは、そのユーザーは結果から除外され errors 配列に含まれる

レスポンス例

{
  "data": [
    { "id": "2244994945", "username": "XDevelopers" }
  ],
  "errors": [
    {
      "resource_id": "1234567890",
      "resource_type": "user",
      "title": "Not Found Error",
      "detail": "Could not find user with id: [1234567890]."
    }
  ]
}

非公開ユーザー

フォローしていない非公開アカウントについて:

基本情報 (id、name、username) は取得可能
非公開のコンテンツ (ピン留めした Post) は制限される場合があります
protected: true はアカウントのステータスを示します

ベストプラクティス

バッチリクエスト

マルチユーザーエンドポイントで一度に最大 100 ユーザーを取得し、API 呼び出し回数を減らします。

必要なフィールドのみリクエスト

必要なフィールドのみを指定してレスポンスサイズを最小化します。

ユーザーデータをキャッシュ

ユーザープロフィールをローカルにキャッシュし、繰り返しリクエストを減らします。

エラーを丁寧に処理

バッチレスポンスの部分的なエラーを確認します。

次のステップ

API リファレンス

エンドポイントの詳細ドキュメント

データディクショナリ

利用可能なオブジェクトとフィールドすべて

サンプルコード

動作するコード例

エラー処理

エラーを丁寧に処理する

Getting Started

Products

Fundamentals

Partners & Customers

Resources

認証

App-Only 認証

User Context 認証

Fields と expansions

デフォルトのレスポンス

利用可能なフィールド

フィールドを使った例

expansions 付きのレスポンス

Fields と expansions ガイド

バッチルックアップ

エラー処理

一般的なエラー

凍結・削除されたユーザー

非公開ユーザー

ベストプラクティス

バッチリクエスト

必要なフィールドのみリクエスト

ユーザーデータをキャッシュ

エラーを丁寧に処理

次のステップ

API リファレンス

データディクショナリ

サンプルコード

エラー処理

​認証

​App-Only 認証

​User Context 認証

​Fields と expansions

​デフォルトのレスポンス

​利用可能なフィールド

​フィールドを使った例

​expansions 付きのレスポンス

Fields と expansions ガイド

​バッチルックアップ

​エラー処理

​一般的なエラー

​凍結・削除されたユーザー

​非公開ユーザー

​ベストプラクティス

バッチリクエスト

必要なフィールドのみリクエスト

ユーザーデータをキャッシュ

エラーを丁寧に処理

​次のステップ

API リファレンス

データディクショナリ

サンプルコード

エラー処理

認証

App-Only 認証

User Context 認証

Fields と expansions

デフォルトのレスポンス

利用可能なフィールド

フィールドを使った例

expansions 付きのレスポンス

バッチルックアップ

エラー処理

一般的なエラー

凍結・削除されたユーザー

非公開ユーザー

ベストプラクティス

次のステップ