サイトのトップへ戻る

Twitter 開発者 ドキュメント日本語訳

オブジェクト内のEntities

Entitiesは他のTwitterオブジェクトと密接に関連しています。 Listed below are the various relationships that Entities have, and any additional attributes needed for that relationship.



Tweetを表すEntities

Entities は、解決済みURLを含むツイート、メディア、ハッシュタグ、メンションを構造化したデータであり、それらの情報を取得する際にわざわざツイート文を解析する必要がありません。 Entities は REST APIエンドポイントとストリーミング APIsエンドポイントで取得する全てのTweet オブジェクトに含まれており、entities属性配下に格納されています。

当たり前のことかもしれませんが、取得したentities を処理する場合は、新たにフィールドが追加されていたりフィールドの値がemptyやnullだった場合でも正常に動作するようプログラムすることが重要です。 REST API v1.1からは、既定でentities は常に取得結果に含まれるようになっていますが、リクエスト時にinclude_entitiesパラメータにfalseを設定することでentities を省略することができるので覚えておいてください。。

以下に、Tweet オブジェクト内に格納されている各entity の詳細を記載します media, urls, user_mentions, hashtags,symbolsがあります。



The media entity

Twitter の写真アップロード機能でツイートに添付されたメディアの配列。各メディア entity は以下の属性を持っています:

id メディア ID (int 形式)
id_str メディア ID (string 形式)
media_url メディアファイルの URL (使用できるサイズについては sizes 属性を参照してください)
media_url_https メディアファイルの SSL URL (使用できるサイズについては sizes 属性を参照してください)
url 抽出されたメディア URL
display_url URL ではなく、メディアURLの代わりに表示する文字列
expanded_url 解決済みのフルのメディア URL
sizes Twitterでは異なる複数のサイズをサポートしています: サムネイルサイズ、小サイズ、中サイズ、大サイズです。media_url は既定では中サイズですが、コロンとサイズキーを追加することで異なるサイズのメディアを取得することができます。 (例えば: http://pbs.twimg.com/media/A7EiDWcCYAAZT1D.jpg:thumb)。使用可能な各サイズは、それを定義するための三つの属性を持っています。:
w:該当サイズにおける、このメディアの横幅 (ピクセル単位)
h:該当サイズにおける、このメディアの高さ (ピクセル単位)
resize: メディアを該当サイズに合わせてサイズ変更する方法 ( cropもしくは fitが設定されます)
type 現状では photo のみ設定されます。
indices メディアを抽出した文字位置

JSON 例

{
  ...
  "text": "Four more years. http:\/\/t.co\/bAJE6Vom",
  "entities": {
    "hashtags": [],
    "symbols": [],
    "urls": [],
    "user_mentions": [],
    "media": [{
      "id": 266031293949698048,
      "id_str": "266031293949698048",
      "indices": [17, 37],
      "media_url": "http:\/\/pbs.twimg.com\/media\/A7EiDWcCYAAZT1D.jpg",
      "media_url_https": "https:\/\/pbs.twimg.com\/media\/A7EiDWcCYAAZT1D.jpg",
      "url": "http:\/\/t.co\/bAJE6Vom",
      "display_url": "pic.twitter.com\/bAJE6Vom",
      "expanded_url": "http:\/\/twitter.com\/BarackObama\/status\/266031293945503744\/photo\/1",
      "type": "photo",
      "sizes": {
        "medium": {
          "w": 600,
          "h": 399,
          "resize": "fit"
        },
        "thumb": {
          "w": 150,
          "h": 150,
          "resize": "crop"
        },
        "small": {
          "w": 340,
          "h": 226,
          "resize": "fit"
        },
        "large": {
          "w": 800,
          "h": 532,
          "resize": "fit"
        }
      }
    }]
  }
}


The urls entity

ツイート文から抽出したURLの配列。 各URL entity は以下の属性を持っています:

url ツイート文から抽出された t.co URL
display_url 有効な URL ではなく、URLの代わりに表示する文字列
expanded_url 解決済み URL
indices URLから抽出した文字位置

JSON 例

{
  ...
  "text": "Today, Twitter is updating embedded Tweets to enable a richer photo experience: https:\/\/t.co\/XdXRudPXH5",
  "entities": {
    "hashtags": [],
    "symbols": [],
    "urls": [{
      "url": "https:\/\/t.co\/XdXRudPXH5",
      "expanded_url": "https:\/\/blog.twitter.com\/2013\/rich-photo-experience-now-in-embedded-tweets-3",
      "display_url": "blog.twitter.com\/2013\/rich-phot…",
      "indices": [80, 103]
    }],
    "user_mentions": []
  }
}


The user_mentions entity

ツイート文から抽出したTwitterスクリーンネームの配列。各ユーザーメンションentity は以下の属性を持っています:

id ユーザー ID (int 形式)
id_str ユーザー ID (string 形式)
screen_name ユーザーのスクリーンネーム
name ユーザーのフルネーム
indices ユーザーメンションを抽出した文字位置

JSON 例

{
  ...
  "text": "We’re excited to work closely with the external technical community and continue @twittereng’s work with open source. cc @TwitterOSS",
  "entities": {
    "hashtags": [],
    "symbols": [],
    "urls": [],
    "user_mentions": [{
      "screen_name": "TwitterEng",
      "name": "Twitter Engineering",
      "id": 6844292,
      "id_str": "6844292",
      "indices": [81, 92]
    }, {
      "screen_name": "TwitterOSS",
      "name": "Twitter Open Source",
      "id": 376825877,
      "id_str": "376825877",
      "indices": [121, 132]
    }]
  }
}


The hashtags entity

ツイート文から抽出したハッシュタグの配列。各ハッシュタグ entity は以下の属性を持っています:

text ハッシュタグ文
indices ハッシュタグを抽出した文字位置

JSON 例

{
  ...
  "text": "Loved #devnestSF"
  "entities": {
    "hashtags": [
      "text": "devnestSF"
      "indices": [
        6,
        16
      ]
    ],
    "symbols": [],
    "urls": [],
    "user_mentions": []
  }
}


The symbols entity

ツイート文から抽出した、ドル記号から始まる financial symbols の配列。 ハッシュタグと同様に、この entity は以下の属性を持っています:

text シンボル文
indices シンボルを抽出した文字位置

JSON 例

{
  ...
  "text": "$PEP or $COKE?",
  "entities": {
    "hashtags": [],
    "symbols": [
      {
        "text": "PEP",
        "indices": [
          0,
          4
        ]
      },
      {
        "text": "COKE",
        "indices": [
          8,
          13
        ]
      }
    ],
    "urls": [],
    "user_mentions": []
  }
}


extended_entities

この入れ子オブジェクトではmulti photos, アニメgif,動画といった様々なメディアタイプをサポートしています。また、このフィールドは後述する情報タイプのメタデータを多く含んでいます。; 縦横比, variants, サイズ, 有効期限, ビットレート など。 各メディア entity は以下の属性を持っています:

id メディア ID (int 形式)
id_str メディア ID (string 形式)
media_url メディアファイルの URL (使用できるサイズについては sizes 属性を参照してください)
media_url_https メディアファイルのSSL URL (使用できるサイズについては sizes 属性を参照してください)
url 抽出したメディア URL
display_url URL ではなく、メディアURLの代わりに表示する文字列
expanded_url 解決済みのフルのメディア URL
sizes Twitterでは異なる複数のサイズをサポートしています: サムネイルサイズ、小サイズ、中サイズ、大サイズです。media_urlは既定では中サイズですが、コロンとサイズキーを追加することで異なるサイズのメディアを取得することができます (例えば: http://pbs.twimg.com/media/A7EiDWcCYAAZT1D.jpg:thumb)。使用可能な各サイズは、それを定義するための三つの属性を持っています。:
w:該当サイズにおける、このメディアの横幅 (ピクセル単位)
h:該当サイズにおける、このメディアの高さ (ピクセル単位)
resize: メディアを該当サイズに合わせてサイズ変更する方法 ( cropもしくは fitが設定されます)
type 現状では photo, multi photos, animated gifs , videos のみ設定されます。
indices メディアを抽出した文字位置
video_info 縦横比についての情報を持っています。動画の縦横比は、横幅と高さの二つを配列に格納した単純なものになっています。通常は[4, 3]や [16, 9]といった値になります。 このフィールドはデータ内に動画が存在する場合にのみ表示されます。
duration_millis 動画のミリ秒単位の長さ。このフィールドはデータ内に動画が存在する場合にのみ表示されます。
variants Different encodings/streams of the video. 各動画ごとに、少なくともどちらか一つのvariant 型の値が返されます。ここで取得される動画形式は、将来変更される可能性があります。 ベストプラクティスとして、開発者は取得した全ての値を確認して自分のプラットフォームに最も適した形式を使うようにしてください。このフィールドはデータ内に動画が存在する場合にのみ表示されます。

動画のextended_entities JSON 例

 {
      "display_url": "pic.twitter.com\/31JoMS50ha",
      "expanded_url": "http:\/\/twitter.com\/twitter\/status\/560070183650213889\/video\/1",
      "features": {
        
      },
      "id": 5.6007013197639e+17,
      "id_str": "560070131976392705",
      "indices": [
        110,
        132
      ],
      "media_url": "http:\/\/pbs.twimg.com\/ext_tw_video_thumb\/560070131976392705\/pu\/img\/TcG_ep5t-iqdLV5R.jpg",
      "media_url_https": "https:\/\/pbs.twimg.com\/ext_tw_video_thumb\/560070131976392705\/pu\/img\/TcG_ep5t-iqdLV5R.jpg",
      "sizes": {
        "large": {
          "h": 576,
          "resize": "fit",
          "w": 1024
        },
        "medium": {
          "h": 337,
          "resize": "fit",
          "w": 600
        },
        "small": {
          "h": 191,
          "resize": "fit",
          "w": 340
        },
        "thumb": {
          "h": 150,
          "resize": "crop",
          "w": 150
        }
      },
      "type": "video",
      "url": "http:\/\/t.co\/31JoMS50ha",
      "video_info": {
        "aspect_ratio": [
          16,
          9
        ],
        "duration_millis": 30033,
        "variants": [
          {
            "bitrate": 2176000,
            "content_type": "video\/mp4",
            "url": "https:\/\/video.twimg.com\/ext_tw_video\/560070131976392705\/pu\/vid\/1280x720\/c4E56sl91ZB7cpYi.mp4"
          },
          {
            "bitrate": 320000,
            "content_type": "video\/mp4",
            "url": "https:\/\/video.twimg.com\/ext_tw_video\/560070131976392705\/pu\/vid\/320x180\/nXXsvs7vOhcMivwl.mp4"
          },
          {
            "bitrate": 832000,
            "content_type": "video\/webm",
            "url": "https:\/\/video.twimg.com\/ext_tw_video\/560070131976392705\/pu\/vid\/640x360\/vmLr5JlVs2kBLrXS.webm"
          },
          {
            "bitrate": 832000,
            "content_type": "video\/mp4",
            "url": "https:\/\/video.twimg.com\/ext_tw_video\/560070131976392705\/pu\/vid\/640x360\/vmLr5JlVs2kBLrXS.mp4"
          },
          {
            "content_type": "application\/x-mpegURL",
            "url": "https:\/\/video.twimg.com\/ext_tw_video\/560070131976392705\/pu\/pl\/r1kgzh5PmLgium3-.m3u8"
          }
        ]
      }
    }


リツイートを表すEntities

Twitter API の観点から言うと、リツイートとは、オリジナルのツイートを埋め込み型retweeted_statusオブジェクトとして内部に保持した特別なツイートです。 一貫性を保持するため、最上位のリツイートオブジェクトにもtextプロパティと関連するentitiesを持っています。

リツイートのtext 属性は、先頭に“RT @username: ”と付いてオリジナルのツイート文で構成されています。 表示する文字数が140文字を超過してしまう場合は、この文は切り捨てられて省略記号 “…” が追加されます。その結果、例えばハッシュタグエントリが切り捨てられた場合などでは、 最上位のentitiesが不正になったりエラーとなったりすることがあります。

結論として、retweeted_statusが存在する場合は、retweeted_status内のオリジナルツイートからテキスト文、entities、オリジナルのツイート主、日付といった情報を直接取得するのが良いでしょう。

JSON 例

{
  ...
  "text": "RT @rsarver: Great, in-depth technical post from @raffi on how they re-architected Twitter to be able to handle 500M tweets\/day https:\/\/t.c…",
  "entities": {
    "hashtags": [],
    "symbols": [],
    "urls": [],
    "user_mentions": [{
      "screen_name": "rsarver",
      "name": "Ryan Sarver",
      "id": 795649,
      "id_str": "795649",
      "indices": [3, 11]
    }, {
      "screen_name": "raffi",
      "name": "Raffi Krikorian",
      "id": 8285392,
      "id_str": "8285392",
      "indices": [49, 55]
    }]
  },
  ...
  "retweeted_status": {
    ...
    "text": "Great, in-depth technical post from @raffi on how they re-architected Twitter to be able to handle 500M tweets\/day https:\/\/t.co\/te5ubjHNsZ",
    "entities": {
      "hashtags": [],
      "symbols": [],
      "urls": [{
        "url": "https:\/\/t.co\/te5ubjHNsZ",
        "expanded_url": "https:\/\/blog.twitter.com\/2013\/new-tweets-per-second-record-and-how",
        "display_url": "blog.twitter.com\/2013\/new-tweet…",
        "indices": [115, 138]
      }],
      "user_mentions": [{
        "screen_name": "raffi",
        "name": "Raffi Krikorian",
        "id": 8285392,
        "id_str": "8285392",
        "indices": [36, 42]
      }]
    }
  }
}

上記の例では、最上位にあるtext内のURLが切り捨てられ、最上位のentitiesからは見えません。 また、user_mentionsに追加されている最上位のentity は、textフィールドの先頭に付いている“RT @rsarver: ”に由来していることにも気づくでしょう。

しかしretweeted_status内のtextentities では、オリジナルのツイートを切り捨てずに完全な状態で保持しています。 したがって、リツイートは入れ子のオブジェクトの情報を使用することを推奨します。



今後の変更

Top-level entities for Retweets are consistent with the original Tweet ones. 我々はオリジナルの retweeted_statusが保持している entitiesの情報を使用することを強く推奨しますが、 あなたが最上位entitiesの情報を使用し続けるのであれば、来年初めに我々が実施する仕様変更によってそれがどのような表示になるのか、以下の例で検証してください。

このリツイートサンプルでプログラムを確認すると、仕様変更の結果をイメージできるでしょう。

変更前のJSON Extract

{
  ...
  "text": "RT @university: Learn more about the powerful #Linux container engine @docker in this video intro with @solomonstre - http:\/\/t.co\/QJLdA1762…",
  "entities": {
    "hashtags": [{
      "text": "Linux",
      "indices": [46, 52]
    }],
    "symbols": [],
    "urls": [],
    "user_mentions": [{
      "screen_name": "university",
      "name": "Twitter University",
      "id": 1665823832,
      "id_str": "1665823832",
      "indices": [3, 14]
    }, {
      "screen_name": "docker",
      "name": "Docker",
      "id": 1138959692,
      "id_str": "1138959692",
      "indices": [70, 77]
    }, {
      "screen_name": "solomonstre",
      "name": "Solomon Hykes",
      "id": 9551792,
      "id_str": "9551792",
      "indices": [103, 115]
    }]
  },
  ...
  "retweeted_status": {
    ...
    "text": "Learn more about the powerful #Linux container engine @docker in this video intro with @solomonstre - http:\/\/t.co\/QJLdA1762Y @TwitterOSS",
    "entities": {
      "hashtags": [{
        "text": "Linux",
        "indices": [30, 36]
      }],
      "symbols": [],
      "urls": [{
        "url": "http:\/\/t.co\/QJLdA1762Y",
        "expanded_url": "http:\/\/youtu.be\/Q5POuMHxW-0",
        "display_url": "youtu.be\/Q5POuMHxW-0",
        "indices": [102, 124]
      }],
      "user_mentions": [{
        "screen_name": "docker",
        "name": "Docker",
        "id": 1138959692,
        "id_str": "1138959692",
        "indices": [54, 61]
      }, {
        "screen_name": "solomonstre",
        "name": "Solomon Hykes",
        "id": 9551792,
        "id_str": "9551792",
        "indices": [87, 99]
      }, {
        "screen_name": "TwitterOSS",
        "name": "Twitter Open Source",
        "id": 376825877,
        "id_str": "376825877",
        "indices": [125, 136]
      }]
    }
  }
}


変更の詳細

Retweet Entities

最上位textのURLは切り捨てられるので、 previously the URL entity would be missing. With this change, the URL entity will be included and its indices will start at the beginning of the URL text, but actually end at the ellipsis character. リツイート文にはURLが完全な状態で入っていなかったとしても、URL entity には短縮URLが完全な状態で格納されています。

@TwitterOSS ユーザーメンション entity は丸ごと切り捨てられているので、欠落している状態です。 It will now be included but will only reference the ellipsis character at indices [139, 140].また、 fromで指定したentities の並び順は常に保証されるものではないので注意してください。

変更後のJSON Extract

{
  ...
  "text": "RT @university: Learn more about the powerful #Linux container engine @docker in this video intro with @solomonstre - http:\/\/t.co\/QJLdA1762…",
  "entities": {
    "hashtags": [{
      "text": "Linux",
      "indices": [46, 52]
    }],
    "symbols": [],
    "urls": [{
      "url": "http://t.co/QJLdA1762Y",
      "expanded_url": "http://youtu.be/Q5POuMHxW-0",
      "display_url": "youtu.be/Q5POuMHxW-0",
      "indices": [118, 140]
    }],
    "user_mentions": [{
      "screen_name": "university",
      "name": "Twitter University",
      "id": 1665823832,
      "id_str": "1665823832",
      "indices": [3, 14]
    }, {
      "screen_name": "docker",
      "name": "Docker",
      "id": 1138959692,
      "id_str": "1138959692",
      "indices": [70, 77]
    }, {
      "screen_name": "solomonstre",
      "name": "Solomon Hykes",
      "id": 9551792,
      "id_str": "9551792",
      "indices": [103, 115]
    }, {
      "screen_name": "TwitterOSS",
      "name": "Twitter Open Source",
      "id": 376825877,
      "id_str": "376825877",
      "indices": [139, 140]
    }]
  },
  ...
  "retweeted_status": {
    ...
    "text": "Learn more about the powerful #Linux container engine @docker in this video intro with @solomonstre - http:\/\/t.co\/QJLdA1762Y @TwitterOSS",
    "entities": {
      "hashtags": [{
        "text": "Linux",
        "indices": [30, 36]
      }],
      "symbols": [],
      "urls": [{
        "url": "http:\/\/t.co\/QJLdA1762Y",
        "expanded_url": "http:\/\/youtu.be\/Q5POuMHxW-0",
        "display_url": "youtu.be\/Q5POuMHxW-0",
        "indices": [102, 124]
      }],
      "user_mentions": [{
        "screen_name": "docker",
        "name": "Docker",
        "id": 1138959692,
        "id_str": "1138959692",
        "indices": [54, 61]
      }, {
        "screen_name": "solomonstre",
        "name": "Solomon Hykes",
        "id": 9551792,
        "id_str": "9551792",
        "indices": [87, 99]
      }, {
        "screen_name": "TwitterOSS",
        "name": "Twitter Open Source",
        "id": 376825877,
        "id_str": "376825877",
        "indices": [125, 136]
      }]
    }
  }
}


ユーザーを表すEntities

User オブジェクトのEntities には、ユーザーが設定したプロフィールURL上に表示されるURLとフィールドの説明文が記載されています。 このentityには hashtagsuser_mentionsは記載されていません。Tweet entitiesと違い、 user entities can apply to multiple fields within its parent object — to disambiguate, you will find a parent nodes called url and description that indicate which field contains the entitized URL.

In this example, the user url field contains a t.co link that is fully expanded within the entities/url/urls[0] node of the response. The user does not have a wrapped URL in their description.

JSON 例

{
  "id": 6253282,
  "id_str": "6253282",
  "name": "Twitter API",
  "screen_name": "twitterapi",
  "location": "San Francisco, CA",
  "description": "The Real Twitter API. I tweet about API changes, service issues and happily answer questions about Twitter and our API. Don't get an answer? It's on my website.",
  "url": "http:\/\/t.co\/78pYTvWfJd",
  "entities": {
    "url": {
      "urls": [{
        "url": "http:\/\/t.co\/78pYTvWfJd",
        "expanded_url": "http:\/\/dev.twitter.com",
        "display_url": "dev.twitter.com",
        "indices": [0, 22]
      }]
    },
    "description": {
      "urls": []
    }
  }
  ...
}


ダイレクトメッセージを表すEntities

ダイレクトメッセージを表すEntities はツイートを表す entities ととても似ています。しかしメディア entitiesとの関連で若干の違いがあります。

ツイート上で共有されたメディアと違い、ダイレクトメッセージ上で共有されたメディアは閲覧するのに承認が必要です。 認証済みのtwitter.comセッションを経由するか、 OAuth 1.0Aを使ったユーザーのアクセストークンでリクエストを署名することで承認が得られます。

また、ツイート上でメディアURLはメディア entities内にのみありますが、ダイレクトメール上でメディア URLsはメディアentities内と urls entities内にあります。

JSON Example

{
    "id": 411031503817039874,
    "id_str": "411031503817039874",
    "text": "test $TWTR @twitterapi #hashtag http:\/\/t.co\/p5dOtmnZyu https:\/\/t.co\/ZSvIEMOPb8",
    "created_at": "Thu Dec 12 07:15:21 +0000 2013",
    "entities": {
        "hashtags": [{
            "text": "hashtag",
            "indices": [23, 31]
        }],
        "symbols": [{
            "text": "TWTR",
            "indices": [5, 10]
        }],
        "urls": [{
            "url": "http:\/\/t.co\/p5dOtmnZyu",
            "expanded_url": "http:\/\/dev.twitter.com",
            "display_url": "dev.twitter.com",
            "indices": [32, 54]
        }, {
            "url": "https:\/\/t.co\/ZSvIEMOPb8",
            "expanded_url": "https:\/\/ton.twitter.com\/1.1\/ton\/data\/dm\/411031503817039874\/411031503833792512\/cOkcq9FS.jpg",
            "display_url": "pic.twitter.com\/ZSvIEMOPb8",
            "indices": [55, 78]
        }],
        "user_mentions": [{
            "screen_name": "twitterapi",
            "name": "Twitter API",
            "id": 6253282,
            "id_str": "6253282",
            "indices": [11, 22]
        }],
        "media": [{
            "id": 411031503833792512,
            "id_str": "411031503833792512",
            "indices": [55, 78],
            "media_url": "https:\/\/ton.twitter.com\/1.1\/ton\/data\/dm\/411031503817039874\/411031503833792512\/cOkcq9FS.jpg",
            "media_url_https": "https:\/\/ton.twitter.com\/1.1\/ton\/data\/dm\/411031503817039874\/411031503833792512\/cOkcq9FS.jpg",
            "url": "https:\/\/t.co\/ZSvIEMOPb8",
            "display_url": "pic.twitter.com\/ZSvIEMOPb8",
            "expanded_url": "https:\/\/ton.twitter.com\/1.1\/ton\/data\/dm\/411031503817039874\/411031503833792512\/cOkcq9FS.jpg",
            "type": "photo",
            "sizes": {
                "medium": {
                    "w": 600,
                    "h": 450,
                    "resize": "fit"
                },
                "large": {
                    "w": 1024,
                    "h": 768,
                    "resize": "fit"
                },
                "thumb": {
                    "w": 150,
                    "h": 150,
                    "resize": "crop"
                },
                "small": {
                    "w": 340,
                    "h": 255,
                    "resize": "fit"
                }
            }
        }]
    }
    ...
}

現状ではPOST direct_messages / newでダイレクトメッセージを送る際にメディアを添付することはできないので注意してください。