Entities

Entities provide metadata and additional contextual information about content posted on Twitter. Entities are never divorced from the content they describe. In API v1.1, entities are returned wherever Tweets are found in the API. Entities are instrumental in resolving URLs.

Read Entities in Objects for a more comprehensive guide to how entities are used throughout Twitter objects.

Field Guide

Consumers of Entities should tolerate the addition of new fields and variance in ordering of fields with ease. Not all fields appear in all contexts. It is generally safe to consider a nulled field, an empty set, and the absence of a field as the same thing.

FieldTypeDescription
hashtagsArray of ObjectRepresents hashtags which have been parsed out of the Tweet text.

Example:

"hashtags":[{"indices":[32,36],"text":"lol"}]
mediaArray of ObjectRepresents media elements uploaded with the Tweet.

Example:

"media":[{"type":"photo", "sizes":{"thumb":{"h":150, "resize":"crop", "w":150}, "large":{"h":238, "resize":"fit", "w":226}, "medium":{"h":238, "resize":"fit", "w":226}, "small":{"h":238, "resize":"fit", "w":226}}, "indices":[15,35], "url":"http:\/\/t.co\/rJC5Pxsu", "media_url":"http:\/\/p.twimg.com\/AZVLmp-CIAAbkyy.jpg", "display_url":"pic.twitter.com\/rJC5Pxsu", "id":114080493040967680, "id_str":"114080493040967680", "expanded_url": "http:\/\/twitter.com\/yunorno\/status\/114080493036773378\/photo\/1", "media_url_https":"https:\/\/p.twimg.com\/AZVLmp-CIAAbkyy.jpg"}]
urlsArray of ObjectRepresents URLs included in the text of a Tweet or within textual fields of a user object.

Tweet Example:

"urls":[{"indices":[32,52], "url":"http:\/\/t.co\/IOwBrTZR", "display_url":"youtube.com\/watch?v=oHg5SJ\u2026", "expanded_url":"http:\/\/www.youtube.com\/watch?v=oHg5SJYRHA0"}]

User Example:

          "urls":[{"indices":[32,52], "url":"http:\/\/t.co\/IOwBrTZR", "display_url":"youtube.com\/watch?v=oHg5SJ\u2026", "expanded_url":"http:\/\/www.youtube.com\/watch?v=oHg5SJYRHA0"}]
          
user_mentionsArray of ObjectRepresents other Twitter users mentioned in the text of the Tweet.

Example:

"user_mentions":[{"name":"Twitter API", "indices":[4,15], "screen_name":"twitterapi", "id":6253282, "id_str":"6253282"}]

Hashtags

FieldTypeDescription
indicesArray of IntAn array of integers indicating the offsets within the Tweet text where the hashtag begins and ends. The first integer represents the location of the # character in the Tweet text string. The second integer represents the location of the first character after the hashtag. Therefore the difference between the two numbers will be the length of the hashtag name plus one (for the ‘#’ character).

Example:

"indices":[32,36]
textStringName of the hashtag, minus the leading ‘#’ character.

Example:

"text":"lol"

Media

FieldTypeDescription
display_urlStringURL of the media to display to clients.

Example:

"display_url":"pic.twitter.com\/rJC5Pxsu"
expanded_urlStringAn expanded version of display_url. Links to the media display page.

Example:

"expanded_url": "http:\/\/twitter.com\/yunorno\/status\/114080493036773378\/photo\/1"
idInt64ID of the media expressed as a 64-bit integer.

Example:

"id":114080493040967680
id_strStringID of the media expressed as a string.

Example:

"id_str":"114080493040967680"
indicesArray of IntAn array of integers indicating the offsets within the Tweet text where the URL begins and ends. The first integer represents the location of the first character of the URL in the Tweet text. The second integer represents the location of the first non-URL character occurring after the URL (or the end of the string if the URL is the last part of the Tweet text).

Example:

"indices":[15,35]
media_urlStringAn http:// URL pointing directly to the uploaded media file.

Example:

"media_url":"http:\/\/p.twimg.com\/AZVLmp-CIAAbkyy.jpg"

For media in direct messages, media_url is the same https URL as media_url_https and must be accessed via an authenticated twitter.com session or by signing a request with the user’s access token using OAuth 1.0A. It is not possible to directly embed these images in a web page.

media_url_httpsStringAn https:// URL pointing directly to the uploaded media file, for embedding on https pages.

Example:

"media_url_https":"https:\/\/p.twimg.com\/AZVLmp-CIAAbkyy.jpg"

For media in direct messages, media_url_https must be accessed via an authenticated twitter.com session or by signing a request with the user’s access token using OAuth 1.0A. It is not possible to directly embed these images in a web page.

sizesObjectAn object showing available sizes for the media file.

Example:

"sizes":{"thumb":{"h":150, "resize":"crop", "w":150}, "large":{"h":238, "resize":"fit", "w":226}, "medium":{"h":238, "resize":"fit", "w":226}, "small":{"h":238, "resize":"fit", "w":226}}
source_status_idInt64For Tweets containing media that was originally associated with a different tweet, this ID points to the original Tweet.

Example:

"source_status_id": 205282515685081088
source_status_id_strInt64For Tweets containing media that was originally associated with a different tweet, this string-based ID points to the original Tweet.

Example:

  "source_status_id_str": "205282515685081088"
typeStringType of uploaded media.

Example:

"type":"photo"
urlStringWrapped URL for the media link. This corresponds with the URL embedded directly into the raw Tweet text, and the values for the indices parameter.

Example:

"url":"http:\/\/t.co\/rJC5Pxsu"

Size

FieldTypeDescription
hIntHeight in pixels of this size.

Example:

"h":150
resizeStringResizing method used to obtain this size. A value of fit means that the media was resized to fit one dimension, keeping its native aspect ratio. A value of crop means that the media was cropped in order to fit a specific resolution.

Example:

"resize":"crop"
wIntWidth in pixels of this size.

Example:

"w":150

Sizes

FieldTypeDescription
thumbObjectInformation for a thumbnail-sized version of the media.

Example:

"thumb":{"h":150, "resize":"crop", "w":150}
largeObjectInformation for a large-sized version of the media.

Example:

"large":{"h":238, "resize":"fit", "w":226}
mediumObjectInformation for a medium-sized version of the media.

Example:

"medium":{"h":238, "resize":"fit", "w":226}
smallObjectInformation for a small-sized version of the media.

Example:

"small":{"h":238, "resize":"fit", "w":226}

URL

FieldTypeDescription
display_urlStringVersion of the URL to display to clients.

Example:

"display_url":"youtube.com\/watch?v=oHg5SJ\u2026"
expanded_urlStringExpanded version of display_url.

Example:

"expanded_url":"http:\/\/www.youtube.com\/watch?v=oHg5SJYRHA0"
indicesArray of IntAn array of integers representing offsets within the Tweet text where the URL begins and ends. The first integer represents the location of the first character of the URL in the Tweet text. The second integer represents the location of the first non-URL character after the end of the URL.

Example:

"indices":[32,52]
urlStringWrapped URL, corresponding to the value embedded directly into the raw Tweet text, and the values for the
indices
parameter.

Example:

"url":"http:\/\/t.co\/IOwBrTZR"

User Mention

FieldTypeDescription
idInt64ID of the mentioned user, as an integer.

Example:

"id":6253282
id_strStringIf of the mentioned user, as a string.

Example:

"id_str":"6253282"
indicesArray of IntAn array of integers representing the offsets within the Tweet text where the user reference begins and ends. The first integer represents the location of the ‘@’ character of the user mention. The second integer represents the location of the first non-screenname character following the user mention.

Example:

"indices":[4,15]
nameStringDisplay name of the referenced user.

Example:

"name":"Twitter API"
screen_nameStringScreen name of the referenced user.

Example:

"screen_name":"twitterapi"