【Twitter API】タイムライン取得に使えるパラメータ集

Twitter APIタイムライン取得に使えるパラメータ集Tips
日本の証券会社で米国株[チャレンジ32か月目]

以前の記事でTwitter APIを利用してのタイムラインの取得と表示の基本をお伝えしました。

【PHP×Twitter API】タイムラインの取得と表示の基本
Twitter APIを利用したPHPでの3種類のタイムラインの取得方法の基本をお伝えします。
munokuno.com
2019.11.23

今回はタイムライン取得時に指定可能なパラメータについてです。

前回の記事と同じくサンプルコードはPHPで記載していますが、指定できるパラメータはどの言語でも同じですので参考になるかと思います。

パラメータの種類

パラメータは全部で11種類ですが、単にリストで紹介しても分かりにくいので以下の5カテゴリに分けて紹介をします。

  • ユーザー指定（ユーザータイムライン専用）
    ユーザータイムラインのみに利用できる取得対象ユーザーを指定するパラメータ
  • ツイート取得範囲を変更する系
    ツイートの取得範囲を変更するために利用するパラメータ
  • ツイートの種類を限定する系
    指定したツイートの種類を取得対象から外すために利用するパラメータ
  • ツイートの情報を削る系
    各ツイートデータの情報を削るために利用するパラメータ
  • ツイートの情報を追加する系
    各ツイートデータに情報を追加するために利用するパラメータ

ユーザー指定（ユーザータイムライン専用）

ユーザータイムラインで取得対象ユーザーを指定するパラメータです。どちらかのパラメータで取得対象を指定しなかった場合は、APIキーの持ち主が取得対象となります。

  • screen_name
  • user_id

screen_name

user_timeline
screen_nameはユーザー名を指しており、「@xxxxx」の@以降の「xxxxx」の部分をパラメータとして指定します。

例えば、私の場合は「@munokuno」（執筆時時点）ですので以下のように指定します。
$timeline = $connection->get("statuses/user_timeline", ["screen_name" => "munokuno"]);

screen_nameは設定によって変更可能なので、次に出てくるuser_idを利用したユーザーの指定の方がロックオン度が高いです

user_id

user_timeline
user_idはツイッターアカウントごとに割り振られた固有のIDです。アカウント作成時に自動的に付与されて、ユーザー自身での変更はできません。screen_nameの変更をして逃げ切りを図ろうとしているユーザーを追いかけるためにはuser_idでの指定が必須です。

自分のユーザーIDは設定の奥深くに潜って確認ができますが、他人のユーザーIDを知るのはひと手間掛かります。screen_nameからuser_idを調べられるサイトもあるようですが、せっかくなので練習がてらscreen_nameで指定して取得したデータからuser_idを探すという方法をおススメします(user->id_strに格納されています)。

例えば、私のユーザーIDは「1140629838878760960」ですので以下のように指定します。
$timeline = $connection->get("statuses/user_timeline", ["user_id" => 1140629838878760960]);

ツイート取得範囲を変更する系

ツイートの取得範囲を変更するために利用するパラメータです。

  • count
  • max_id
  • since_id

count

home_timeline user_timeline mentions_timeline
取得するツイート数を指定するパラメータです。何も指定しない場合は、20ツイートしか取得できませんが、countを使うことで最大200ツイートが一度に取得できるようになります。

例えば、ホームタイムラインで200件のツイートを取得したい場合は以下のように指定します。
$timeline = $connection->get("statuses/home_timeline", ["count" => 200]);

max_id

home_timeline user_timeline mentions_timeline
countのところで説明したように一度に取得できるツイート数の上限は200ツイートとなっています。世界中のツイッタラーが200ツイート以内だったら問題ないのですが、中には鬼のようにツイートをしまくっているユーザーもいます。そんなユーザーの全ツイートを取得したいといった時に有効なのがmax_idパラメータになります。

max_idは取得するツイートの最大のIDを指定するパラメータです。IDが大きい=より新しいツイートなので、最大のIDを指定することで指定したツイートから過去○件分のツイートが取得できるようになります。なお、ページング処理についての詳細は、こちらをご覧ください。

例えば、私の2020年あけおめツイート（ID:1212133572003295232）を含む過去ツイートをユーザータイムラインで取得したい場合は以下のように指定します。
$timeline = $connection->get("statuses/user_timeline", ["user_id" => 1140629838878760960, "max_id" => 1212133572003295232]);

since_id

home_timeline user_timeline mentions_timeline
max_idパラメータでは取得するツイートの最大のIDを指定しました。since_idは取得しないツイートの最大のIDを指定します。since_idを指定することにより、前回取得したタイムライン以降のツイートのみを取得できます。うまく利用できれば無駄なデータ取得を減らすことができます。

since_idよりも新しいツイートが取得ツイート数を超える場合は、注意が必要です。最新のツイートから指定分のツイート数のみが取得されるので、間に取得されていないツイートが発生します。

例えば、私の2020年あけおめツイート（ID:1212133572003295232）以降のツイートをユーザータイムラインで取得したい場合は以下のように指定します。
$timeline = $connection->get("statuses/user_timeline", ["user_id" => 1140629838878760960, "since_id" => 1212133572003295232]);

ツイートの種類を限定する系

指定したツイートの種類を取得対象から外すために利用するパラメータです。

  • include_rts
  • exclude_replies

取得対象からは外れますが、取得ツイート数としてはカウント対象となっているので注意が必要です

include_rts

home_timeline user_timeline
include_rtsパラメータにFalseを指定するとリツイートが取得対象から除外できます。

コメント付きリツイートは除外されず、純粋なリツイートのみが除外対象です

例えば、ホームタイムラインでリツイートを除外する場合は以下のように指定します。
$timeline = $connection->get("statuses/home_timeline", ["include_rts" => False]);

exclude_replies

home_timeline user_timeline mentions_timeline
exclude_repliesパラメータにTrueを指定するとリプライが取得対象から除外できます。

自分のツイートに対するリプライ（自己リプ）も取得されなくなります

mentions_timelineでもパラメータが効くことが確認できましたが、リプライでないのにメンションされているという稀有なツイートだけが残りますのでほぼ無価値です

例えば、ホームタイムラインでリプライを除外する場合は以下のように指定します。
$timeline = $connection->get("statuses/home_timeline", ["exclude_replies" => True]);

ツイートの情報を削る系

各ツイートデータの情報を削るために利用するパラメータです。

  • trim_user
  • include_entities

trim_user

home_timeline user_timeline mentions_timeline
trim_userパラメータにTrueを指定すると取得した各ツイートデータ内にあるツイートユーザー情報がユーザーIDのみになります。プロフィールやフォロー数、フォロワー数も何もかも削除されます。

2020年あけおめツイートで確認したところ、ツイートデータ202行の内、115行が削除されていました。こうかはばつぐんだ！

ハイライト部分が削除されます。

  [0]=>
  object(stdClass)#3 (23) {
    ["created_at"]=>
    string(30) "Tue Dec 31 22:08:58 +0000 2019"
    ["id"]=>
    int(1212133572003295232)
    ["id_str"]=>
    string(19) "1212133572003295232"
    ["text"]=>
    string(336) "明けましておめでとうございます🐼
いやぁ、よく寝ました。スタートダッシュ失敗です😂

正月と言えばお年玉ですが、最近はお年玉にもキャッシュレスの波が来ているようです。
子供のYouTuberがファンから500円ずつもらって500,… https://t.co/af2VmgKl5t"
    ["truncated"]=>
    bool(true)
    ["entities"]=>
    object(stdClass)#8 (4) {
      ["hashtags"]=>
      array(0) {
      }
      ["symbols"]=>
      array(0) {
      }
      ["user_mentions"]=>
      array(0) {
      }
      ["urls"]=>
      array(1) {
        [0]=>
        object(stdClass)#9 (4) {
          ["url"]=>
          string(23) "https://t.co/af2VmgKl5t"
          ["expanded_url"]=>
          string(52) "https://twitter.com/i/web/status/1212133572003295232"
          ["display_url"]=>
          string(29) "twitter.com/i/web/status/1…"
          ["indices"]=>
          array(2) {
            [0]=>
            int(117)
            [1]=>
            int(140)
          }
        }
      }
    }
    ["source"]=>
    string(71) "Twitter Web App"
    ["in_reply_to_status_id"]=>
    NULL
    ["in_reply_to_status_id_str"]=>
    NULL
    ["in_reply_to_user_id"]=>
    NULL
    ["in_reply_to_user_id_str"]=>
    NULL
    ["in_reply_to_screen_name"]=>
    NULL
    ["user"]=>
    object(stdClass)#10 (43) {
      ["id"]=>
      int(1140629838878760960)
      ["id_str"]=>
      string(19) "1140629838878760960"
      ["name"]=>
      string(58) "クノウ=明日から本気出したい底辺ブロガー"
      ["screen_name"]=>
      string(8) "munokuno"
      ["location"]=>
      string(0) ""
      ["description"]=>
      string(424) "好きな言葉はポテンシャル。
趣味と仕事がごちゃごちゃになって、投資・ブログ・マーケティング・プログラミング・コピーライティングなどをやってます。
色々やっているので頑張ってどこかにポテンシャルを感じてください。感性は大事です。Don't think, feel.

檻から出ておりますのでご自由に絡んでください。"
      ["url"]=>
      string(23) "https://t.co/TfmxahAIjp"
      ["entities"]=>
      object(stdClass)#13 (2) {
        ["url"]=>
        object(stdClass)#12 (1) {
          ["urls"]=>
          array(1) {
            [0]=>
            object(stdClass)#11 (4) {
              ["url"]=>
              string(23) "https://t.co/TfmxahAIjp"
              ["expanded_url"]=>
              string(21) "http://bit.ly/2xk5TPT"
              ["display_url"]=>
              string(14) "bit.ly/2xk5TPT"
              ["indices"]=>
              array(2) {
                [0]=>
                int(0)
                [1]=>
                int(23)
              }
            }
          }
        }
        ["description"]=>
        object(stdClass)#14 (1) {
          ["urls"]=>
          array(0) {
          }
        }
      }
      ["protected"]=>
      bool(false)
      ["followers_count"]=>
      int(348)
      ["friends_count"]=>
      int(505)
      ["listed_count"]=>
      int(0)
      ["created_at"]=>
      string(30) "Mon Jun 17 14:38:40 +0000 2019"
      ["favourites_count"]=>
      int(3313)
      ["utc_offset"]=>
      NULL
      ["time_zone"]=>
      NULL
      ["geo_enabled"]=>
      bool(false)
      ["verified"]=>
      bool(false)
      ["statuses_count"]=>
      int(1502)
      ["lang"]=>
      NULL
      ["contributors_enabled"]=>
      bool(false)
      ["is_translator"]=>
      bool(false)
      ["is_translation_enabled"]=>
      bool(false)
      ["profile_background_color"]=>
      string(6) "000000"
      ["profile_background_image_url"]=>
      string(48) "http://abs.twimg.com/images/themes/theme1/bg.png"
      ["profile_background_image_url_https"]=>
      string(49) "https://abs.twimg.com/images/themes/theme1/bg.png"
      ["profile_background_tile"]=>
      bool(false)
      ["profile_image_url"]=>
      string(75) "http://pbs.twimg.com/profile_images/1143167513288531968/Zc3HXrQi_normal.png"
      ["profile_image_url_https"]=>
      string(76) "https://pbs.twimg.com/profile_images/1143167513288531968/Zc3HXrQi_normal.png"
      ["profile_link_color"]=>
      string(6) "ABB8C2"
      ["profile_sidebar_border_color"]=>
      string(6) "000000"
      ["profile_sidebar_fill_color"]=>
      string(6) "000000"
      ["profile_text_color"]=>
      string(6) "000000"
      ["profile_use_background_image"]=>
      bool(false)
      ["has_extended_profile"]=>
      bool(false)
      ["default_profile"]=>
      bool(false)
      ["default_profile_image"]=>
      bool(false)
      ["can_media_tag"]=>
      bool(true)
      ["followed_by"]=>
      bool(false)
      ["following"]=>
      bool(false)
      ["follow_request_sent"]=>
      bool(false)
      ["notifications"]=>
      bool(false)
      ["translator_type"]=>
      string(4) "none"
    }
    ["geo"]=>
    NULL
    ["coordinates"]=>
    NULL
    ["place"]=>
    NULL
    ["contributors"]=>
    NULL
    ["is_quote_status"]=>
    bool(false)
    ["retweet_count"]=>
    int(0)
    ["favorite_count"]=>
    int(22)
    ["favorited"]=>
    bool(false)
    ["retweeted"]=>
    bool(false)
    ["lang"]=>
    string(2) "ja"
  }

例えば、ホームタイムラインでユーザー情報を割愛したい場合は以下のように指定します。
$timeline = $connection->get("statuses/home_timeline", ["trim_user" => True]);

include_entities

home_timeline user_timeline mentions_timeline
include_entitiesパラメータにFalseを指定すると取得した各ツイートデータ内にあるentitiesが除外されます。そもそもentitiesって何ぞやという話ですが、こちらの情報によるとメディア、ハッシュタグ、メンションなどを構造化したデータが入っているらしいです。

非常にややこしいですが、本パラメータをFalseにしてもextended_entitiesは取得されます

試しに画像をつけたツイートで確認したところ、 ツイートデータ204行の内、32行が削除されていました。他の方のツイートなので掲載はしませんが、400行の内の126行が削除されている例もありました。

ハイライト部分が削除されます。

  [0]=>
  object(stdClass)#3 (24) {
    ["created_at"]=>
    string(30) "Thu Dec 26 00:07:22 +0000 2019"
    ["id"]=>
    int(1209989039186563072)
    ["id_str"]=>
    string(19) "1209989039186563072"
    ["text"]=>
    string(344) "1年以上保有して2,000円のクオカードを狙っていたが、想像を超えた値上がりで手放した近鉄エクスプレスよりクオカードが届く。

手放した株から来る配当などを見たときのすまんな感！

NISAで買い戻せばよかったと思うも、現在は売値… https://t.co/jKcn8i412u"
    ["truncated"]=>
    bool(true)
    ["entities"]=>
    object(stdClass)#8 (4) {
      ["hashtags"]=>
      array(0) {
      }
      ["symbols"]=>
      array(0) {
      }
      ["user_mentions"]=>
      array(0) {
      }
      ["urls"]=>
      array(1) {
        [0]=>
        object(stdClass)#9 (4) {
          ["url"]=>
          string(23) "https://t.co/jKcn8i412u"
          ["expanded_url"]=>
          string(52) "https://twitter.com/i/web/status/1209989039186563072"
          ["display_url"]=>
          string(29) "twitter.com/i/web/status/1…"
          ["indices"]=>
          array(2) {
            [0]=>
            int(117)
            [1]=>
            int(140)
          }
        }
      }
    }
    ["source"]=>
    string(84) "Twitter for Android"
    ["in_reply_to_status_id"]=>
    NULL
    ["in_reply_to_status_id_str"]=>
    NULL
    ["in_reply_to_user_id"]=>
    NULL
    ["in_reply_to_user_id_str"]=>
    NULL
    ["in_reply_to_screen_name"]=>
    NULL
    ["user"]=>
    object(stdClass)#10 (43) {
      ["id"]=>
      int(1140629838878760960)
      ["id_str"]=>
      string(19) "1140629838878760960"
      ["name"]=>
      string(58) "クノウ=明日から本気出したい底辺ブロガー"
      ["screen_name"]=>
      string(8) "munokuno"
      ["location"]=>
      string(0) ""
      ["description"]=>
      string(424) "好きな言葉はポテンシャル。
趣味と仕事がごちゃごちゃになって、投資・ブログ・マーケティング・プログラミング・コピーライティングなどをやってます。
色々やっているので頑張ってどこかにポテンシャルを感じてください。感性は大事です。Don't think, feel.

檻から出ておりますのでご自由に絡んでください。"
      ["url"]=>
      string(23) "https://t.co/TfmxahAIjp"
      ["entities"]=>
      object(stdClass)#13 (2) {
        ["url"]=>
        object(stdClass)#12 (1) {
          ["urls"]=>
          array(1) {
            [0]=>
            object(stdClass)#11 (4) {
              ["url"]=>
              string(23) "https://t.co/TfmxahAIjp"
              ["expanded_url"]=>
              string(21) "http://bit.ly/2xk5TPT"
              ["display_url"]=>
              string(14) "bit.ly/2xk5TPT"
              ["indices"]=>
              array(2) {
                [0]=>
                int(0)
                [1]=>
                int(23)
              }
            }
          }
        }
        ["description"]=>
        object(stdClass)#14 (1) {
          ["urls"]=>
          array(0) {
          }
        }
      }
      ["protected"]=>
      bool(false)
      ["followers_count"]=>
      int(349)
      ["friends_count"]=>
      int(505)
      ["listed_count"]=>
      int(0)
      ["created_at"]=>
      string(30) "Mon Jun 17 14:38:40 +0000 2019"
      ["favourites_count"]=>
      int(3315)
      ["utc_offset"]=>
      NULL
      ["time_zone"]=>
      NULL
      ["geo_enabled"]=>
      bool(false)
      ["verified"]=>
      bool(false)
      ["statuses_count"]=>
      int(1504)
      ["lang"]=>
      NULL
      ["contributors_enabled"]=>
      bool(false)
      ["is_translator"]=>
      bool(false)
      ["is_translation_enabled"]=>
      bool(false)
      ["profile_background_color"]=>
      string(6) "000000"
      ["profile_background_image_url"]=>
      string(48) "http://abs.twimg.com/images/themes/theme1/bg.png"
      ["profile_background_image_url_https"]=>
      string(49) "https://abs.twimg.com/images/themes/theme1/bg.png"
      ["profile_background_tile"]=>
      bool(false)
      ["profile_image_url"]=>
      string(75) "http://pbs.twimg.com/profile_images/1143167513288531968/Zc3HXrQi_normal.png"
      ["profile_image_url_https"]=>
      string(76) "https://pbs.twimg.com/profile_images/1143167513288531968/Zc3HXrQi_normal.png"
      ["profile_link_color"]=>
      string(6) "ABB8C2"
      ["profile_sidebar_border_color"]=>
      string(6) "000000"
      ["profile_sidebar_fill_color"]=>
      string(6) "000000"
      ["profile_text_color"]=>
      string(6) "000000"
      ["profile_use_background_image"]=>
      bool(false)
      ["has_extended_profile"]=>
      bool(false)
      ["default_profile"]=>
      bool(false)
      ["default_profile_image"]=>
      bool(false)
      ["can_media_tag"]=>
      bool(true)
      ["followed_by"]=>
      bool(false)
      ["following"]=>
      bool(false)
      ["follow_request_sent"]=>
      bool(false)
      ["notifications"]=>
      bool(false)
      ["translator_type"]=>
      string(4) "none"
    }
    ["geo"]=>
    NULL
    ["coordinates"]=>
    NULL
    ["place"]=>
    NULL
    ["contributors"]=>
    NULL
    ["is_quote_status"]=>
    bool(false)
    ["retweet_count"]=>
    int(0)
    ["favorite_count"]=>
    int(9)
    ["favorited"]=>
    bool(false)
    ["retweeted"]=>
    bool(false)
    ["possibly_sensitive"]=>
    bool(false)
    ["lang"]=>
    string(2) "ja"
  }

例えば、ホームタイムラインでentitiesを割愛したい場合は以下のように指定します。
$timeline = $connection->get("statuses/home_timeline", ["include_entities" => False]);

ツイートの情報を追加する系

各ツイートデータの情報を追加するために利用するパラメータです。

  • tweet_mode
  • contributor_details

tweet_mode

home_timeline user_timeline mentions_timeline
前回の記事「タイムラインの取得と表示の基本」ですでに紹介済みですが、本パラメータは必須です。付与することでfull_textフィールドが取得できるようになります。付与しない場合、ツイートの最後の方が切れる可能性があるので必ず付けるようにしましょう。

例えば、ホームタイムラインでフルのツイートを取得する場合は以下のように指定します。
$timeline = $connection->get("statuses/home_timeline", ["tweet_mode" => "extended"]);

contributor_details

このパラメータは自分で試しても何も起こらず困りました。調査の結果、1つのツイッターアカウントを複数人で使っている場合に関係するパラメータのようです。そもそもそんな機能があるのを知りませんでした。

自分で実験できないため、申し訳ないですが説明は割愛させていただきます。

あとがき

前回記事からかなり間が空いてしまいましたが、なんとかパラメータの記事を書けました。

パラメータによってincludeで指定したりexcludeで指定したりがあり、しかもどちらもパラメータを付けない場合はincludeされていたりして混乱しがちです。もっと分かりやすくならんもんですかね。

コメント