Fields

X API v2 の endpoint には「fields」と呼ばれる一連のパラメータが用意されており、endpoint のレスポンスに含まれる各オブジェクトから必要な data だけを選択できます。

既定では、Post オブジェクトは id と text のみを返し、2022 年 9 月 29 日以降に作成された Posts については edit_history_tweet_ids も返します。Post の作成日時や公開 metrics が必要な場合は、tweet.fields パラメータで明示的に指定してください。これにより、ユースケースに応じて必要な fields のみを要求でき、柔軟にカスタマイズできます。例えば、リクエストに次の query 文字列を含めます。

?tweet.fields=created_at,public_metrics

各オブジェクトには、そのオブジェクトに関連する fields を個別に要求するための専用パラメータがあります。現在利用可能な fields パラメータは次のとおりです。

• Post → tweet.fields
• User → user.fields
• Media → media.fields
• Poll → poll.fields
• Place → place.fields

特定のオブジェクトを主に返す endpoint を使用する場合は、対応する fields パラメータを指定し、取得したい field をカンマ区切りで列挙して値に設定するだけで、レスポンスにそれらの fields を含められます。

​

例

GET /tweets/search/recent endpoint を使用している場合、そのレスポンスには主に Tweet objects が含まれます。fields パラメータを指定しない場合、受け取れるのはデフォルト値である id と text のみです。レスポンスで返される Posts の公開 metrics を取得したい場合は、リクエストに tweet.fields パラメータを含め、値に public_metrics を指定してください。

このリクエストは次のとおりです。このリクエストを使用する場合は、$BEARER_TOKEN を自分の Bearer Token に置き換え、コマンドラインツールで送信してください。

curl --request GET \
  --url 'https://api.x.com/2/tweets/search/recent?query=from%3Atwitterdev&tweet.fields=public_metrics' \
  --header 'Authorization: Bearer $BEARER_TOKEN'

ターミナルでこのリクエストを送信すると、返される各Postsに次のfieldsが含まれます。

{
   "data": {
       "id": "1263150595717730305",
       "public_metrics": {
           "retweet_count": 12,
           "reply_count": 14,
           "like_count": 49,
           "quote_count": 7
       },
       "text": "新しいTweetの設定はもうご覧になりましたか？👀\n\nこのような機能をAPIでどのように、そしてなぜ使うのか、皆さまの声を伺いたいと考えています。詳細をご確認のうえ、ぜひご意見をお聞かせください👇\nhttps://t.co/RtMhhfAcIB https://t.co/8wxeZ9fJER"
   }
}

endpoint から返されるプライマリオブジェクトに関連付けられたセカンダリオブジェクトの特定の fields を取得する場合は、追加で expansions パラメータを指定する必要があります。たとえば、先ほどと同じ GET search/tweets/recent endpoint を使用していて、著者のプロフィールの説明を取得したい場合は、リクエストに expansions=author_id と user.fields=description を指定してください。以下に例を示します。このリクエストを試す場合は、コマンドラインツールに貼り付ける前に $BEARER_TOKEN をご自身の Bearer Token に置き換えてください。

  curl --request GET \
  --url 'https://api.x.com/2/tweets/search/recent?query=from%3Atwitterdev&tweet.fields=public_metrics&expansions=author_id&user.fields=description' \
  --header 'Authorization: Bearer $BEARER_TOKEN'

これをリクエストで指定すると、配信される各Postには以下のfieldsが含まれ、関連するユーザーオブジェクトのデフォルトfieldsおよび指定したfieldsがincludes内で返されます。ユーザーオブジェクトは、tweet.author_id と users.id のfieldsを照合することで、対応するPostに関連付けられます。

{
  "data": [
    {
      "id": "1263150595717730305",
      "author_id": "2244994945",
      "text": "新しい Tweet 設定をご覧になりましたか？👀\n\nAPI でこのような機能をどのように、そしてなぜ使うのかを知りたいと考えています。詳しくはこちらをご確認のうえ、ご意見をお聞かせください👇\nhttps://t.co/RtMhhfAcIB https://t.co/8wxeZ9fJER",
      "public_metrics": {
        "retweet_count": 12,
        "reply_count": 13,
        "like_count": 51,
        "quote_count": 7
      }
    }
  ],
  "includes": {
    "users": [
      {
        "id": "2244994945",
        "username": "TwitterDev",
        "description": "#TwitterDev チームの声であり、#TwitterAPI に関する最新情報、ニュース、イベントの公式情報源です。",
        "name": "Twitter Dev"
      }
    ]
  }
}

特定のサブフィールド（例：public_metrics.retweet_count）はリクエストできない点にご留意ください。トップレベルのフィールド（public_metrics）を指定すると、すべてのサブフィールドが返されます。各endpointのAPIリファレンスページにあるパラメータ表に、リクエスト可能なすべてのfieldsを掲載しています。

すべてのfieldsの一覧はobject modelに記載されています。あるendpointの主要リソースではないオブジェクトでfieldsを取得するには、fieldsと併せてexpansionsパラメータを使用してください。