統合ガイド - X

このガイドでは、Search Posts エンドポイントをアプリケーションに統合するために必要となる重要な概念について説明します。

認証

Method	利用ケース
OAuth 2.0 App-Only	公開ポストのデータ
OAuth 2.0 Authorization Code with PKCE	非公開のメトリクス
OAuth 1.0a User Context	非公開のメトリクス

フルアーカイブ検索

フルアーカイブ検索は、OAuth 2.0 App-Only 認証にのみ対応しています。

プライベートメトリクス (non_public_metrics、organic_metrics、promoted_metrics) は、App-Only 認証のみがサポートされているため、フルアーカイブ検索では利用できません。

クエリの構築

クエリではオペレーターを使って投稿をマッチさせます。これらのオペレーターをブール論理で組み合わせます。

(AI OR "machine learning") lang:en -is:retweet has:links

クエリ長の上限

アクセスレベル	直近検索	全アーカイブ検索
Self-serve	512文字	1,024文字
Enterprise	4,096文字	4,096文字

オペレーターの種類

Type	説明	例
Standalone	単体で使用できる	`#python`, `from:user`
Conjunction-required	Standalone のオペレーターと組み合わせて使用する必要がある	`has:media`, `is:retweet`

クエリを作成する

クエリ構文について詳しく学ぶ

オペレーターリファレンス

利用可能なすべてのオペレーターを確認する

フィールドとexpansions

デフォルトでは、レスポンスには id、text、edit_history_tweet_ids の3つだけが含まれます。追加のデータを取得するには、パラメータを指定してください。

リクエスト例

cURL

curl "https://api.x.com/2/tweets/search/recent?\
query=python&\
tweet.fields=created_at,public_metrics,author_id&\
expansions=author_id,attachments.media_keys&\
user.fields=username,verified&\
media.fields=url,type" \
  -H "Authorization: Bearer $BEARER_TOKEN"

from xdk import Client

client = Client(bearer_token="YOUR_BEARER_TOKEN")

# 最近の投稿を検索
for page in client.posts.search_recent(
    query="python",
    tweet_fields=["created_at", "public_metrics", "author_id"],
    expansions=["author_id", "attachments.media_keys"],
    user_fields=["username", "verified"],
    media_fields=["url", "type"],
    max_results=100
):
    for post in page.data:
        print(f"{post.text} - Likes: {post.public_metrics.like_count}")

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

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

// 最近の投稿を検索
const paginator = client.posts.searchRecent("python", {
  tweetFields: ["created_at", "public_metrics", "author_id"],
  expansions: ["author_id", "attachments.media_keys"],
  userFields: ["username", "verified"],
  mediaFields: ["url", "type"],
  maxResults: 100,
});

for await (const page of paginator) {
  page.data?.forEach((post) => {
    console.log(`${post.text} - Likes: ${post.public_metrics?.like_count}`);
  });
}

利用可能なexpansions

Expansion	戻り値
`author_id`	投稿者のユーザーオブジェクト
`attachments.media_keys`	添付されたメディアオブジェクト
`attachments.poll_ids`	添付された投票オブジェクト
`referenced_tweets.id`	引用または返信先の投稿
`geo.place_id`	場所オブジェクト
`entities.mentions.username`	メンションされたユーザーオブジェクト

フィールドとexpansionsのガイド

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

ページネーション

検索エンドポイントは結果をページごとに返します。レスポンスに含まれる next_token を使用して、後続のページを取得します。

動作の仕組み

最初のリクエストで max_results を指定する
meta オブジェクト内に next_token があるか確認する
後続のリクエストに next_token を含める
next_token が返されなくなるまで繰り返す

例

cURL

# 最初のリクエスト
curl "https://api.x.com/2/tweets/search/recent?query=python&max_results=100" \
  -H "Authorization: Bearer $BEARER_TOKEN"

# ページネーション用トークンを使った後続リクエスト
curl "https://api.x.com/2/tweets/search/recent?query=python&max_results=100&next_token=NEXT_TOKEN" \
  -H "Authorization: Bearer $BEARER_TOKEN"

from xdk import Client

client = Client(bearer_token="YOUR_BEARER_TOKEN")

# SDK がページネーションを自動で処理します
all_posts = []

for page in client.posts.search_recent(query="python", max_results=100):
    if page.data:
        all_posts.extend(page.data)

print(f"Found {len(all_posts)} posts")

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

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

async function getAllResults(query) {
  const allPosts = [];

  // SDK がページネーションを自動で処理します
  const paginator = client.posts.searchRecent(query, { maxResults: 100 });

  for await (const page of paginator) {
    if (page.data) {
      allPosts.push(...page.data);
    }
  }

  return allPosts;
}

// 使用例
const posts = await getAllResults("python");
console.log(`Found ${posts.length} posts`);

ページネーションガイド

ページネーションの詳細はこちら

ポストの編集

投稿は、30分以内であれば最大5回まで編集できます。検索エンドポイントは常に最新版を返します。

考慮事項

edit_history_tweet_ids には、すべてのポストID (古いものから順) が含まれます
30分の編集可能ウィンドウ経過後に取得された投稿は、最終版を表します
ほぼリアルタイムのユースケースでは、公開されたばかりの投稿が引き続き編集されている可能性があります

ポスト編集の基本

ポストの編集について詳しく学ぶ

ベストプラクティス

条件を具体的にする

複数の演算子を組み合わせて結果を絞り込み、ノイズを減らします。

反復してテストする

まずは広い条件から始めて、結果に基づいて徐々に絞り込みます。

ページネーションを実装する

大規模な結果セットには、適切なページネーションを実装します。

結果をキャッシュする

同じリクエストを繰り返さないように、結果をローカルに保存します。

次のステップ

クエリを作成する

クエリ構文を習得する

オペレーターリファレンス

利用可能なすべてのオペレーター

ページネーション

大規模な結果セットを処理する

APIリファレンス

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

認証

最近の検索

フルアーカイブ検索

クエリの構築

クエリ長の上限

オペレーターの種類

クエリを作成する

オペレーターリファレンス

フィールドとexpansions

リクエスト例

利用可能なexpansions

フィールドとexpansionsのガイド

ページネーション

動作の仕組み

例

ページネーションガイド

ポストの編集

考慮事項

ポスト編集の基本

ベストプラクティス

条件を具体的にする

反復してテストする

ページネーションを実装する

結果をキャッシュする

次のステップ

クエリを作成する

オペレーターリファレンス

ページネーション

APIリファレンス