Entitiesは他のTwitterオブジェクトと密接に関連しています。 Listed below are the various relationships that Entities have, and any additional attributes needed for that relationship.
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
があります。
media
entityTwitter の写真アップロード機能でツイートに添付されたメディアの配列。各メディア 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
|
メディアを抽出した文字位置 |
{ ... "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" } } }] } }
urls
entityツイート文から抽出したURLの配列。 各URL entity は以下の属性を持っています:
url
|
ツイート文から抽出された t.co URL
|
display_url
|
有効な URL ではなく、URLの代わりに表示する文字列 |
expanded_url
|
解決済み URL |
indices
|
URLから抽出した文字位置 |
{ ... "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": [] } }
user_mentions
entityツイート文から抽出したTwitterスクリーンネームの配列。各ユーザーメンションentity は以下の属性を持っています:
id
|
ユーザー ID (int 形式) |
id_str
|
ユーザー ID (string 形式) |
screen_name
|
ユーザーのスクリーンネーム |
name
|
ユーザーのフルネーム |
indices
|
ユーザーメンションを抽出した文字位置 |
{ ... "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] }] } }
hashtags
entityツイート文から抽出したハッシュタグの配列。各ハッシュタグ entity は以下の属性を持っています:
text
|
ハッシュタグ文 |
indices
|
ハッシュタグを抽出した文字位置 |
{ ... "text": "Loved #devnestSF" "entities": { "hashtags": [ "text": "devnestSF" "indices": [ 6, 16 ] ], "symbols": [], "urls": [], "user_mentions": [] } }
symbols
entityツイート文から抽出した、ドル記号から始まる financial symbols の配列。 ハッシュタグと同様に、この entity は以下の属性を持っています:
text
|
シンボル文 |
indices
|
シンボルを抽出した文字位置 |
{ ... "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 型の値が返されます。ここで取得される動画形式は、将来変更される可能性があります。 ベストプラクティスとして、開発者は取得した全ての値を確認して自分のプラットフォームに最も適した形式を使うようにしてください。このフィールドはデータ内に動画が存在する場合にのみ表示されます。 |
{ "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" } ] } }
Twitter API の観点から言うと、リツイートとは、オリジナルのツイートを埋め込み型retweeted_status
オブジェクトとして内部に保持した特別なツイートです。
一貫性を保持するため、最上位のリツイートオブジェクトにもtext
プロパティと関連するentities
を持っています。
リツイートのtext
属性は、先頭に“RT @username: ”と付いてオリジナルのツイート文で構成されています。
表示する文字数が140文字を超過してしまう場合は、この文は切り捨てられて省略記号 “…” が追加されます。その結果、例えばハッシュタグエントリが切り捨てられた場合などでは、
最上位のentities
が不正になったりエラーとなったりすることがあります。
結論として、retweeted_status
が存在する場合は、retweeted_status
内のオリジナルツイートからテキスト文、entities、オリジナルのツイート主、日付といった情報を直接取得するのが良いでしょう。
{ ... "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
内のtext
とentities
では、オリジナルのツイートを切り捨てずに完全な状態で保持しています。
したがって、リツイートは入れ子のオブジェクトの情報を使用することを推奨します。
Top-level entities
for Retweets are consistent with the original Tweet ones.
我々はオリジナルの retweeted_status
が保持している entities
の情報を使用することを強く推奨しますが、
あなたが最上位entities
の情報を使用し続けるのであれば、来年初めに我々が実施する仕様変更によってそれがどのような表示になるのか、以下の例で検証してください。
このリツイートサンプルでプログラムを確認すると、仕様変更の結果をイメージできるでしょう。
{ ... "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] }] } } }
最上位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 の並び順は常に保証されるものではないので注意してください。
{ ... "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] }] } } }
User オブジェクトのEntities には、ユーザーが設定したプロフィールURL上に表示されるURLとフィールドの説明文が記載されています。
このentityには hashtags
や user_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.
{ "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との関連で若干の違いがあります。
ツイート上で共有されたメディアと違い、ダイレクトメッセージ上で共有されたメディアは閲覧するのに承認が必要です。 認証済みのtwitter.comセッションを経由するか、 OAuth 1.0Aを使ったユーザーのアクセストークンでリクエストを署名することで承認が得られます。
また、ツイート上でメディアURLはメディア entities内にのみありますが、ダイレクトメール上でメディア URLsはメディアentities内と urls entities内にあります。
{ "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でダイレクトメッセージを送る際にメディアを添付することはできないので注意してください。