ポスト (ツイート)
id, text, edit_history_tweet_ids
追加のフィールドを取得するには tweet.fields を、関連オブジェクトを含めるには expansions を使用します。
すべてのポストのフィールド
| フィールド値 | 型 | 説明 | 利用方法 |
|---|---|---|---|
| id (デフォルト) | 文字列 | リクエストしたツイートの一意の識別子。 | 特定のツイートをプログラムから取得するために使用します。 |
| text (デフォルト) | 文字列 | ツイートの実際の UTF-8 テキストです。使用可能な文字の詳細については twitter-text を参照してください。 | キーワード抽出や感情分析・分類に利用できます。 |
| edit_history_tweet_ids (default) | オブジェクト | ツイートのすべてのバージョンを示す一意の識別子の集合です。編集されていないツイートには ID が 1 つだけ付きます。編集履歴のあるツイートには複数の ID が付きます。 | この情報を使用して、ツイートの編集履歴を取得します。 |
| article | オブジェクト | このツイートに含まれる Article のメタデータを保持します。 | Article の本文およびエンティティを取得するために使用します。 |
| attachments | オブジェクト | (存在する場合) このツイートに添付されているメディアの種類を指定します。 | 指定した expansions によって返されるオブジェクトを理解するために利用します。 |
| author_id | 文字列 | このツイートを投稿したユーザーの一意の識別子。 | User オブジェクトをハイドレートしたり、ピアレビュー用データセットを共有したりする際に使用します。 |
| card_uri | 文字列 | このツイートに含まれる Card の URI。 | |
| community_id | 文字列 | このポストが属する Community の一意の識別子。 | |
| context_annotations | 配列 | ツイートのコンテキスト注釈を保持します。 | エンティティ認識・抽出やトピック分析に利用できます。 |
| conversation_id | 文字列 | 会話の起点となるツイート (そのツイートへの直接の返信およびその返信への再返信を含む) のツイート ID。 | この値を使用して、ツイートから会話全体を再構築します。 |
| created_at | 日付 (ISO 8601) | ツイートが作成された日時。 | 時系列分析や、ツイートがいつ作成されたかを把握するために有用です。 |
| display_text_range | 配列 | 表示されるテキスト部分の開始インデックスと終了インデックスを含む配列。 | 長い投稿において、デフォルトでどのテキスト部分が表示されるかを把握するのに役立ちます。 |
| edit_controls | オブジェクト | ツイートがあとどれくらいの時間編集可能か、および残りの編集回数を示します。 | ツイートが編集可能かどうかを判定するために使用します。 |
| entities | object | ツイート本文から解析されたエンティティを含みます。詳細は「Twitter Objects」の entities を参照してください。 | ハッシュタグ、URL、メンションなどに関する追加情報を提供します。 |
| geo | object | ジオタグ付きツイートの位置または場所を示します。 | ジオタグ付きツイートの位置情報を取得するために使用されます。 |
| in_reply_to_user_id | string | 対象のツイートが返信である場合、このフィールドには元のツイートの投稿者 ID が含まれます。 | ツイートが別のツイートへの返信かどうかを判定します。 |
| lang | string | X によって検出された場合の、ツイートの言語です。 | ツイートを使用言語別に分類します。 |
| non_public_metrics | object | リクエスト時点における、そのツイートに対する非公開のエンゲージメント指標です。ユーザーコンテキストでの認証が必要です。 | ツイートに対して生成されたインプレッション数の合計を把握します。 |
| note_tweet | object | 長文ツイート (280文字超) の本文全体を含みます。 | ツイートの全文を取得します。 |
| organic_metrics | object | リクエスト時点における、そのツイートに対してオーガニックコンテキストで計測されたエンゲージメント指標です。ユーザーコンテキストでの認証が必要です。 | ツイートのオーガニックエンゲージメントを測定します。 |
| possibly_sensitive | boolean | コンテンツがセンシティブと見なされる可能性があるかどうかを示します。 | 特定の種類のコンテンツの流通状況を分析します。 |
| promoted_metrics | object | リクエスト時点における、そのツイートに対してプロモーションコンテキストで計測されたエンゲージメント指標です。ユーザーコンテキストでの認証が必要です。 | ツイートがプロモーションされた際のエンゲージメントを測定します。 |
| public_metrics | object | リクエスト時点における、そのツイートに対する公開エンゲージメント指標です。 | ツイートのエンゲージメントを測定します。 |
| referenced_tweets | array | このツイートが参照しているツイート (リツイート、引用ツイート、返信など) の一覧です。 | リツイートなどの会話上の関係性を把握できます。 |
| reply_settings | string | 指定されたツイートに誰が返信できるかを示します。指定可能な値は “everyone”、“mentioned_users”、“followers” です。 | ツイートの会話における返信設定を示します。 |
| withheld | object | 保留されたコンテンツ に関する詳細情報を含みます。 | |
| scopes | object | ツイートのスコープ (範囲) に関する詳細を含みます。 | 誰がそのツイートを閲覧できるかを示します。プロモーションツイートに対してのみ返されます。 |
| media_metadata | 配列 | ツイートに添付されたメディアに関するメタデータを含みます。 | ツイートに添付されたメディアの alt_text などの追加メタデータを取得します。 |
$BEARER_TOKEN を自分で生成した ベアラートークン に置き換えてください。
User
user.fields フィールドパラメータを使用します。
user オブジェクトは、子オブジェクトとして Tweet オブジェクト内にも含まれ、expansion によって展開できます。オブジェクトは、デフォルトフィールドのみを含む簡略化されたオブジェクトを取得するために、?expansions=author_id または ?expansions=in_reply_to_user_id で展開可能です。オブジェクトを完全な形にするために追加のフィールドをリクエストする際は、expansions とフィールドパラメータ user.fields を組み合わせて使用してください。
| フィールド名 | 型 | 説明 | 使用方法 |
|---|---|---|---|
| id (デフォルト) | 文字列 | このユーザーの一意の識別子。"id": "2244994945" | このフィールドを使用すると、特定の X (旧Twitter) ユーザーに関する情報をプログラムから取得できます。 |
| name (デフォルト) | 文字列 | ユーザーが自身のプロフィールで設定している名前です。必ずしも実名とは限りません。通常は最大 50 文字ですが、変更される可能性があります。"name": "Twitter Dev" | |
| username (デフォルト) | 文字列 | このユーザーが自身を識別するために使用する Twitter のスクリーンネーム、ハンドル、または別名です。ユーザー名は一意ですが、変更される可能性があります。通常は最大 15 文字ですが、過去のアカウントにはこれより長い名前を持つものも存在する場合があります。"username": "TwitterDev" | |
| affiliation | オブジェクト | ユーザーの所属に関する詳細情報を含みます。 | ユーザーのアフィリエイトバッジを取得するために使用できます。 |
| confirmed_email | 文字列 | この認証済みユーザーの確認済みメールアドレスです。 | |
| connection_status | 配列 | 認証ユーザーと参照対象のユーザーとの関係 (例: フォロー中、フォローされている、フォローリクエスト送信済み、フォローリクエスト受信済み、ブロック中、ミュート中) のリストを提供します ”connection_status”: [ “follow_request_received”, “follow_request_sent”, “blocking”, “followed_by”, “following”, “muting” ] | 認証ユーザーと照会対象ユーザーとの接続ステータスを確認するために使用できます。 |
| created_at | 日付 (ISO 8601) | ユーザーアカウントがTwitterで作成された日時 (UTC) 。"created_at": "2013-12-14T04:35:55.000Z" | そのユーザーがどのくらいの期間 X (旧Twitter) を利用しているかを把握するために使用できます。 |
| description | 文字列 | ユーザーが入力している場合、そのユーザーのプロフィールの説明 (bio とも呼ばれます) のテキストです。"description": "The voice of the X Dev team and your official source for updates, news, and events, related to the X API." | |
| entities | オブジェクト | ユーザーのプロフィール説明文内で特別な意味を持つテキストに関する詳細を含みます。"entities": { <br/> "url": { <br/> "urls": [ <br/> { <br/> "start": 0, <br/> "end": 23, <br/> "url": "https://t.co/3ZX3TNiZCY", <br/> "expanded_url": "/content/developer-twitter/en/community", <br/> "display_url": "developer.x.com/en/community" <br/> } <br/> ] <br/> }, <br/> "description": { <br/> "urls": [ <br/> { <br/> "start": 0, <br/> "end": 23, <br/> "url": "https://t.co/3ZX3TNiZCY", <br/> "expanded_url": "/content/developer-twitter/en/community", <br/> "display_url": "developer.x.com/en/community" <br/> }, <br/> "hashtags": [ <br/> { <br/> "start": 23, <br/> "end": 30, <br/> "tag": "DevRel" <br/> }, <br/> { <br/> "start": 113, <br/> "end": 130, <br/> "tag": "BlackLivesMatter" <br/> }, <br/> "mentions": [ <br/> { <br/> "start": 0, <br/> "end": 10, <br/> "tag": "TwitterDev" <br/> }, <br/> "cashtags": [ <br/> { <br/> "start": 12, <br/> "end": 16, <br/> "tag": "twtr" <br/> } <br/> ] <br/> } <br/> } | Entities は、description に含まれる hashtag、URL、user mention、cashtag に関する追加情報を提供する JSON オブジェクトです。詳細については、各 entity のリファレンスを参照してください。 すべての user start インデックスは開始位置を含み、すべての user end インデックスは終了位置を含みません。 |
| is_identity_verified | ブール値 | ユーザーが本人確認済みかどうかを示します。 | |
| location | 文字列 | ユーザーが入力している場合、そのユーザーのプロフィールで指定された場所です。これは自由入力の値であるため、必ずしも有効な位置情報を示すとは限りませんが、位置情報クエリを用いた検索時にはあいまいに評価される場合があります。"location": "127.0.0.1" | |
| most_recent_tweet_id | 文字列 | このユーザーの最新のツイートの一意の識別子です。 | ユーザーの最新のツイートを特定するために使用できます。 |
| parody | ブール値 | このユーザーアカウントにパロディラベルが付与されているかどうかを示します。 | |
| pinned_tweet_id | string | このユーザーの固定ツイートの一意の識別子。"pinned_tweet_id": "1255542774432063488" | ユーザーのプロフィール上部にピン留めされているツイートを特定するために使用できます。ユーザーの使用言語を推定する目的で利用される場合もあります。 |
| profile_banner_url | string | このユーザーのプロフィールに表示されるプロフィールバナー画像のURL。"profile_banner_url": "https://pbs.twimg.com/profile_banners/1716450569358098432/1721022977" | このユーザーのプロフィールバナーをダウンロードするために使用できます。 |
| profile_image_url | string | このユーザーのプロフィールに表示されるプロフィール画像のURL。"profile_image_url": "https://pbs.twimg.com/profile_images/1267175364003901441/tBZNFAgA_normal.jpg" | このユーザーのプロフィール画像をダウンロードするために使用できます。 |
| protected | boolean | このユーザーが自分のツイートを非公開にすることを選択しているかどうかを示します (すなわち、このユーザーのツイートが一般に公開されていないかどうかを示します) 。"protected": false | |
| public_metrics | object | このユーザーのアクティビティに関する詳細情報を含みます。"public_metrics": { "followers_count": 507902, "following_count": 1863, "tweet_count": 3561, "listed_count": 1550 } | X ユーザーのリーチや影響力を推定したり、ユーザーの関心領域の広さや、X 上でのエンゲージメントレベルを定量化するために利用できます。 |
| receives_your_dm | boolean | このユーザーが、認証済みユーザーからの DM を受信できるかどうかを示します。 | |
| subscription | object | ユーザーが認証済みユーザーをサブスクライブしているかどうかに関する詳細を含みます。 | |
| subscription_type | string | 認証済みユーザーが保有している X Premium サブスクリプションの種類を表す文字列です。例: None、Basic、Premium、PremiumPlus。対象ユーザーが認証済みユーザー本人でない場合は、常に None が返されます。 | |
| url | string | ユーザーのプロフィールに指定されている URL (存在する場合) 。"url": "https://t.co/3ZX3TNiZCY" | X ユーザーがプロフィール内で指定した URL です。ホームページである場合もありますが、必ずしもそうとは限りません。 |
| verified | boolean | このユーザーが Twitter の認証済みユーザーかどうかを示します。"verified": true | この X ユーザーが認証済みアカウントかどうかを示します。認証済みアカウントであることで、公的関心のあるアカウントが真正であることを他のユーザーに示すことができます。 |
| verified_followers_count | string | ユーザーの認証済みフォロワー数を表す文字列です。 | |
| verified_type | string | ユーザーが持つ認証の種別を表す文字列です。例: “blue”、“business”、“government” | |
| withheld | object | 該当する場合、withheld content の差し止めに関する詳細を含みます。 |
$BEARER_TOKEN は、ご自身で生成した ベアラートークン に必ず置き換えてください。
Space
host_ids、creator_id、speaker_ids、mentioned_user_ids のいずれか少なくとも 1 つを expansions クエリパラメータに追加することで、expansion の対象として指定できます。
ツイートとは異なり、Space は一時的なものであり、終了後、または作成者によってキャンセルされた場合は利用できなくなります。アプリケーションが Space データを扱う際には、常に最新の情報を返し、プラットフォーム上で利用できなくなったデータを削除する責任があります。Spaces lookup endpoints を利用すると、ユーザーの期待や意図を尊重できているかを確認するのに役立ちます。
| Field Value | Type | Description | How it can be used |
|---|---|---|---|
| id (default) | string | リクエストされた Space の一意の識別子。"id": "1zqKVXPQhvZJB" | レスポンスで返される Space を一意に識別します。 |
| state (default) | string | Space が開始済みか、開始予定か、終了済みかを示します。"state": "live" | ライブ中または予約済みの Space をフィルターします。 |
| created_at | date (ISO 8601) | この Space の作成時刻。"created_at": "2021-07-04T23:12:08.000Z" | Space がいつ作成されたかを把握し、時刻でソートします。 |
| creator_id | string | Space の作成者の一意の識別子。"creator_id": "2244994945" | |
| ended_at | date (ISO 8601) | 該当する場合、この Space が終了した時刻。"ended_at": "2021-07-04T00:11:44.000Z" | ライブ Space がいつ終了したかを把握し、実行時間を算出します。 |
| host_ids | array | Space ホストの一意の識別子。"host_ids": ["2244994945", "6253282"] | User オブジェクトを展開し、エンゲージメントを把握します。 |
| lang | string | 検出された場合、Space の言語。"lang": "en" | 言語別に Space を分類します。 |
| is_ticketed | boolean | この Space がチケット制かどうかを示します。"is_ticketed": false | 関心度の高いコンテンツとして強調表示します。 |
| invited_user_ids | array | スピーカーとして招待されたユーザー ID のリスト。"invited_user_ids": ["2244994945", "6253282"] | User オブジェクトを展開し、エンゲージメントを把握します。 |
| participant_count | integer | ホストおよびスピーカーを含む、Space 内のユーザー数。"participant_count": 420 | エンゲージメントを把握し、レポートを作成します。 |
| subscriber_count | integer | Space にリマインダーを設定したユーザー数。"subscriber_count": 36 | イベントへの関心度を把握します。 |
| scheduled_start | date (ISO 8601) | Space の予定開始時刻。"scheduled_start": "2021-07-14T08:00:00.000Z" | カレンダー通知と連携します。 |
| speaker_ids | array | いずれかの時点で話したユーザーのリスト。"speaker_ids": ["2244994945", "6253282"] | User オブジェクトを展開し、エンゲージメントを把握します。 |
| started_at | date (ISO 8601) | Space の実際の開始時刻。"started_at": "2021-07-14T08:00:12.000Z" | Space の開始時刻を把握します。 |
| title | string | Space のタイトル。"title": "Say hello to the Space data object!" | キーワード、ハッシュタグ、メンションを把握します。 |
| topic_ids | array | Space 作成者が選択したトピックの ID。"topic_ids": ["2244994945", "6253282"] | キーワード、ハッシュタグ、メンションを把握します。 |
| updated_at | date (ISO 8601) | Space メタデータの最終更新時刻。"updated_at": "2021-07-11T14:44:44.000Z" | 情報を最新の状態に保ちます。 |
$BEARER_TOKEN を、ご自身で生成したベアラートークンに置き換えてください。
リスト
list.fields パラメータグループを使用します。
List オブジェクトが他のデータオブジェクトの子要素として返されることはありません。ただし、User オブジェクトは user リソースで取得および展開できます。これらのオブジェクトは、expansions クエリパラメータに owner_id を追加することで展開して取得できます。主要な List オブジェクトを補完するために追加フィールドを要求する際は、この展開と list.fields フィールドパラメータを組み合わせて使用し、展開オブジェクトを補完するには user.fields を使用します。
| Field Value | Type | Description | How it can be used |
|---|---|---|---|
| id (default) | string | このリストの一意の識別子。"id": "2244994945" | 特定のリストに関する情報をプログラムから取得するために使用します。 |
| name (default) | string | リスト作成時に指定されたリストの名前。"name": "Twitter Lists" | |
| created_at | date (ISO 8601) | リストが作成された UTC 日時。"created_at": "2013-12-14T04:35:55.000Z" | リストが X 上にいつ作成されたか、どのくらい前から存在しているかを判断できます。 |
| description | string | リストの内容についてユーザーに伝えるための簡潔な説明。"description": "People that are active members of the Bay area cycling community on Twitter." | |
| follower_count | integer | このリストをフォローしているユーザー数。"follower_count": 198 | |
| member_count | integer | このリストに含まれているメンバー数。"member_count": 60 | |
| private | boolean | リストが非公開かどうかを示します。"private": false | |
| owner_id | string | このリストのオーナーの一意の識別子。"owner_id": "1255542774432063488" | このユーザーが他に所有しているリストの特定や、User オブジェクトの展開に使用できます。 |
$BEARER_TOKEN は、生成済みの ベアラートークン に置き換えてください。
メディア
media オブジェクトはどのエンドポイントでも主オブジェクトではありませんが、ツイートオブジェクト内に含まれており、参照・展開できます。オブジェクトは ?expansions=attachments.media_keys を指定することで展開可能で、デフォルトフィールドのみを含む簡略化されたオブジェクトを取得できます。オブジェクトを補完するために追加フィールドをリクエストする場合は、media.fields フィールドパラメータと組み合わせてこの expansions を使用します。
| フィールド値 | 型 | 説明 | 利用方法 |
|---|---|---|---|
| media_key (default) | string | 展開されたメディアコンテンツの一意の識別子。 "media_key": "13_1263145212760805376" | メディアをプログラムから取得するために使用できます |
| type (default) | string | コンテンツの種類 (animated_gif, photo, video)。 "type": "video" | メディアが写真、GIF、動画のどれであるかを分類します |
| url | string | Twitter 上のメディアファイルへの直接 URL。 | 写真の場合に URL フィールドを含む media オブジェクトが返されます |
| duration_ms | integer | type が video の場合に利用可能。動画の長さ (ミリ秒) 。 "duration_ms": 46947 | |
| height | integer | このコンテンツの高さ (ピクセル) 。 "height": 1080 | |
| non_public_metrics | object | リクエスト時点における、メディアコンテンツの非公開エンゲージメント指標。ユーザーコンテキスト認証が必要です。 "non_public_metrics": { "playback_0_count": 1561, "playback_100_count": 116, "playback_25_count": 559, "playback_50_count": 305, "playback_75_count": 183,} | 動画エンゲージメントを把握します。ユーザーが動画の各 4 分の 1 区間までどれだけ再生したかを確認できます。 |
| organic_metrics | object | リクエスト時点における、オーガニックコンテキストで計測されたメディアコンテンツのエンゲージメント指標。ユーザーコンテキスト認証が必要です。 "organic_metrics": { "playback_0_count": 1561, "playback_100_count": 116, "playback_25_count": 559, "playback_50_count": 305, "playback_75_count": 183, "view_count": 629} | オーガニックなメディアエンゲージメントを把握します。 |
| preview_image_url | string | このコンテンツの静的なプレースホルダープレビューへの URL。 "preview_image_url": "https://pbs.twimg.com/media/EYeX7akWsAIP1_1.jpg" | |
| promoted_metrics | object | リクエスト時点における、プロモーションコンテキストで計測されたメディアコンテンツのエンゲージメント指標。ユーザーコンテキスト認証が必要です。 "promoted_metrics": { "playback_0_count": 259, "playback_100_count": 15, "playback_25_count": 113, "playback_50_count": 57, "playback_75_count": 25, "view_count": 124} | ツイートがプロモーションされた際のメディアエンゲージメントを把握します。 |
| public_metrics | object | リクエスト時点における、メディアコンテンツの公開エンゲージメント指標。 "public_metrics": { "view_count": 6865141} | ツイートに添付された動画の総再生回数を把握します。 |
| width | integer | このコンテンツの幅 (ピクセル) 。 "width": 1920 | |
| alt_text | string | アクセシビリティを有効化・支援するための画像の説明。最大 1000 文字まで設定できます。現時点では Alt テキストは画像にのみ追加できます。 "alt_text": "Rugged hills along the Na Pali coast on the island of Kauai" | 視覚障害のあるユーザーなどに備えて、画像の内容を文章で説明するために使用できます。 |
| variants | array | 各 media オブジェクトは、解像度やフォーマットの異なる複数の表示・再生バリアントを持つ場合があります。 "variants": [{ "bit_rate": 632000, "content_type": "video/mp4", "url": "https://video.twimg.com/ext_tw_video/1527322141724532740/pu/vid/320x568/lnBaR2hCqE-R_90a.mp4?tag=12"}] |
attachment.media_keys の展開を指定する必要があります。$BEARER_TOKEN は、必ずご自身で生成した ベアラートークン に置き換えてください。
Poll
?expansions=attachments.poll_ids を指定することで、デフォルトフィールドのみを含む簡略化されたオブジェクトとして展開可能です。オブジェクトを完全な形で取得するために追加のフィールドをリクエストする場合は、expansions とフィールドパラメータ poll.fields を組み合わせて使用してください。
| フィールド値 | Type | 説明 |
|---|---|---|
| id (default) | string | 展開された投票オブジェクトの一意の識別子。 |
{"id": "1199786642791452673"} | ||
| options (default) | array | 参照される投票の各選択肢を表すオブジェクトを含みます。 |
{"options": [ { "position": 1, "label": "“C Sharp”", "votes": 795 }, { "position": 2, "label": "“C Hashtag”", "votes": 156 } ]} | ||
| duration_minutes | integer | この投票の合計期間を指定します。 |
{"duration_minutes": 1440} | ||
| end_datetime | date (ISO 8601) | この投票の終了日時を指定します。 |
{"end_datetime": "2019-11-28T20:26:41.000Z"} | ||
| voting_status | string | この投票がまだ有効で投票受付中か、すでに投票が締め切られているかを示します。 |
{"voting_status": "closed"} |
attachments.poll_id の expansion が必須です。$BEARER_TOKEN はご自身で生成した Bearer Token に必ず置き換えてください。
Place
?expansions=geo.place_id を使用して、デフォルトフィールドのみを含む省略版のオブジェクトとして展開可能です。オブジェクトを補完する追加フィールドをリクエストする場合は、フィールド用パラメータ place.fields を expansions と併用してください。
| Field value | Type | Description | How it can be used |
|---|---|---|---|
| full_name (default) | string | より詳細な形式の場所名。 | ツイートを特定の場所名で分類する |
"full_name": "Manhattan, NY" | |||
| id (default) | string | ツイートに関心地点としてタグ付けされている場合の、その展開された場所の一意の識別子。 | プログラムで場所を取得するために使用 |
"id": "01a9a39529b27f36" | |||
| contained_within | array | 参照されている場所を内包する既知の場所の識別子を返します。 | |
| country | string | この場所が属する国の正式名称。 | ツイートを国名で分類する |
"country": "United States" | |||
| country_code | string | この場所が属する国の ISO Alpha-2 国コード。 | ツイートを国コードで分類する |
"country_code": "US" | |||
| geo | object | GeoJSON 形式の場所の詳細を含みます。 | |
| `json | |||
| ”geo”: | |||
| “type”: “Feature”, | |||
| “bbox”: [ | |||
| -74.026675, | |||
| 40.683935, | |||
| -73.910408, | |||
| 40.877483 | |||
| ], | |||
| “properties”: | |||
| } | |||
| ` | |||
| name | string | この場所の短い名前。 | ツイートを特定の場所名で分類する |
"name": "Manhattan" | |||
| place_type | string | この場所情報が表す情報の特定の種類 (都市名やポイント・オブ・インタレストなど) を指定します。 | ツイートを特定の種類の場所で分類する |
"place_type": "city" |
geo.place_id の expansion パラメータが必須です。必ず $BEARER_TOKEN を、自身で生成した ベアラートークン に置き換えてください。
ダイレクトメッセージイベント
- sender_id - メッセージを送信した、あるいはグループ会話に参加者を招待したアカウントの ID
- partricipants_ids - アカウント ID の配列。ParticipantsJoin および ParticipantsLeave イベントでは、この配列にはイベントを作成したアカウントの ID が 1 件だけ含まれます
- attachments - 送信者によって X にアップロードされたコンテンツのメディア ID を提供します
- referenced_tweets - text フィールド内でツイート URL が検出された場合、そのツイートの ID がレスポンスに含まれます
| Field value | Type | Description | How it can be used |
| id (default) | string | イベントの一意の識別子。 “id”: “1050118621198921728” | v1.1 エンドポイントで利用可能な、特定の会話イベントをプログラムで取得するために使用します。 |
| event_type (default) | string | イベントの種類を表します。現在、次の 3 種類がサポートされています: * MessageCreate * ParticipantsJoin * ParticipantsLeave “event_type”: “MessageCreate” | 会話の履歴を取得する際にメッセージが作成されたタイミングや、グループ会話の場合は参加者が参加・退出したタイミングを把握するために使用します。すべての GET メソッドは、event_type= クエリパラメータを使用して特定のイベント種別でフィルタリングすることをサポートしています。 |
| text (default) | string | ダイレクトメッセージの実際の UTF-8 テキスト。 “text”: “Hello, just you!” | チャットボットでは、メッセージ内容を解析し自動応答を決定するために使用できます。会話検索機能の構築にも利用できます。 |
| entities | object | ダイレクトメッセージのテキストから抽出された entities。 | ハッシュタグ、URL、メンションなどに関する追加情報を提供します。 |
| sender_id | string | イベントを作成したユーザーの ID。レスポンス内でこのオブジェクトを展開するには、expansion として sender_id を含め、関心のある User オブジェクト属性を指定するために user.fields クエリパラメータを使用します。 “sender_id”: “906948460078698496” | MessageCreate または ParticipantsJoin イベントを作成したユーザーの User オブジェクトを取得するために使用します。 |
| participant_ids | array (of strings) | グループ会話に参加・退出する参加者の ID。新しいグループ会話を作成する際にも使用されます。レスポンス内でこのオブジェクトを展開するには、expansion として participant_ids を含め、関心のある User オブジェクト属性を指定するために user.fields クエリパラメータを使用します。 “participant_ids”: [ “906948460078698496” ] | グループ会話に参加・退出する参加者の User オブジェクトを取得するために使用します。 |
| dm_conversation_id | string | イベントが属している会話の一意の識別子。 “dm_conversation_id”: “1584988213961031680” | 会話からイベントをプログラムで取得し、その会話にダイレクトメッセージを追加するために使用します。 |
| created_at | date (ISO 8601) | このイベントの作成時刻 (UTC)。 “created_at”: “2019-06-04T23:12:08.000Z” | ダイレクトメッセージが作成されたタイミング、または会話参加者が参加・退出したタイミングを把握するために使用できます。 |
| referenced_tweets | array | ダイレクトメッセージのテキスト内で言及されているツイートの ID。レスポンス内でこのオブジェクトを展開するには、expansion として referenced_tweets.id を含め、関心のある Tweet オブジェクト属性を指定するために tweet.fields クエリパラメータを使用します。 “referenced_tweets”: [ “id”: “1578868150510456833” ] | ダイレクトメッセージがツイートを参照している場合、これらの ID を使用してそのツイートの詳細を取得できます。 |
| attachments | object | メディアが添付されたダイレクトメッセージについて、アップロードされたコンテンツ (写真、動画、GIF) の media key を提供します。レスポンス内でこのオブジェクトを展開するには、expansion として attachments.media_keys を含め、関心のあるメディアオブジェクト属性を指定するために media.fields クエリパラメータを使用します。現在、添付できるメディアオブジェクトは 1 つのみがサポートされています。 “attachments”: “media_keys”: [ “3_1136048009270239232” ] | ダイレクトメッセージに添付されているメディアオブジェクトを把握するために使用します。 |
- 作成されたタイミングや、どの会話 (dm_conversation) に属しているかといった、基本的なイベント属性。
- ダイレクトメッセージを送信したアカウントの ID と説明。
- 参照されているツイートのテキストと、その投稿日時。
- 参照されているツイート作成者のアカウント ID と説明。
?dm_event.fields=id,sender_id,text,created_at,dm_conversation_id&expansions=sender_id,referenced_tweets.id&tweet.fields=created_at,text,author_id&user.fields=description
コミュニティ
| Field value | Type | Description | |
|---|---|---|---|
| created_at | date (ISO 8601) | コミュニティが作成された時刻。 | |
| id | string | コミュニティの一意の識別子。 | |
| name | string | コミュニティの名前。 | |
| description | string | コミュニティの説明文。指定されている場合のみ含まれます。 | |
| access | string | コミュニティのアクセスレベル。 次のいずれかです: | |
- Public | |||
- Closed | |||
| join_policy | string | コミュニティへの参加ポリシー。 次のいずれかです: | |
- Open | |||
- RestrictedJoinRequestsDisabled | |||
- RestrictedJoinRequestsRequireAdminApproval | |||
- RestrictedJoinRequestsRequireModeratorApproval | |||
- SuperFollowRequired | |||
| member_count | integer | コミュニティに参加しているメンバーの数。 |
$BEARER_TOKEN を自分で生成した ベアラートークン に置き換えてください。
フィールドとexpansionsの使い方
fields を使用せずにリクエストを行うと、X API v2 のデータオブジェクトにはごく少数のデフォルトフィールドのみが含まれます。このガイドでは、レスポンスで追加のオブジェクトやフィールドを受け取れるように、リクエストで fields と expansions のクエリパラメータを使用する方法を説明します。
このガイドでは、次のツイートのスクリーンショットに含まれる複数のフィールドをリクエストしていきます。
スクリーンショットでわかるように、このツイートにはツイートの投稿者、ツイートのメトリクス、作成タイムスタンプ、動画、動画の再生回数など、いくつかの情報が表示されています。また、スクリーンショットには表示されていませんが、リクエスト可能なデータもいくつか存在します。
API へのリクエストを行うと、デフォルトのレスポンスはシンプルで、デフォルトのツイートフィールド (id と text) のみが含まれます。また、利用しているエンドポイントが返すプライマリオブジェクトのみが取得され、そのプライマリオブジェクトに関連する付随データオブジェクトは含まれません。
このシンプルさと fields および expansions パラメータを組み合わせることで、利用目的に応じて必要なフィールドだけをリクエストできるようになります。
追加のフィールドとオブジェクトのリクエスト
- オブジェクトモデルを参照するか、各エンドポイントのAPIリファレンスページに記載されたフィールド一覧を確認し、追加でリクエストしたいフィールドを特定します。 この場合、次の追加フィールドを指定します： attachments、author_id、created_at、public_metrics。
-
上記のフィールドを値として使用し、カンマ区切りのリストで
tweet.fieldsクエリパラメータを指定します：?tweet.fields=attachments,author_id,created_at,public_metrics - 先ほど行った GET /tweets リクエストにクエリパラメータを追加します。
curl --request GET --url 'https://api.x.com/2/tweets?ids=1260294888811347969&tweet.fields=attachments,author_id,created_at,public_metrics' \ --header 'Authorization: Bearer $BEARER_TOKEN'
レスポンス:
- 次に、ツイートに含まれている動画に関連するフィールドをリクエストします。これには、
expansionsパラメータの値としてattachments.media_keysを指定し、リクエストに追加します。
- 最後に、動画の再生回数と長さをリクエストします。これらはデフォルトフィールドではないため、明示的にリクエストする必要があります。リクエストに
media.fieldsパラメータを使用し、カンマ区切りの値としてpublic_metricsとduration_msを指定してください。
curl --request GET --url 'https://api.x.com/2/tweets?ids=1260294888811347969&tweet.fields=attachments,author_id,created_at,public_metrics&expansions=attachments.media_keys&media.fields=duration_ms,public_metrics' --header 'Authorization: Bearer $BEARER_TOKEN'
このリクエストのレスポンスには、ツイートのスクリーンショットに表示されているデータがすべて含まれます。
- ids=1260294888811347969
- tweet.fields=attachments,author_id,created_at,public_metrics
- expansions=attachments.media_keys
- media.fields=public_metrics,duration_ms