Entities

API version 1API version 1.1
Updated on Mon, 2012-10-08 10:54

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 will be returned wherever Tweets are found in the API. Entities are instrumental in resolving URLs.

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.

Field Type Description
hashtags Array of Object Represents hashtags which have been parsed out of the Tweet text.

Example: 

"hashtags":[{"indices":[32,36],"text":"lol"}]
media Array of Object Represents 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"}]
urls Array of Object Represents 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_mentions Array of Object Represents 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

Field Type Description
indices Array of Int An 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]
text String Name of the hashtag, minus the leading '#' character.

Example:

"text":"lol"

Media

Field Type Description
display_url String URL of the media to display to clients.

Example:

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

Example:

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

Example:

"id":114080493040967680
id_str String ID of the media expressed as a string.

Example:

"id_str":"114080493040967680"
indices Array of Int An 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_url String An http:// URL pointing directly to the uploaded media file.

Example:

"media_url":"http:\/\/p.twimg.com\/AZVLmp-CIAAbkyy.jpg"
media_url_https String An 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"
sizes Object An 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_id Int64 For 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_str Int64 For 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"
type String Type of uploaded media.

Example:

"type":"photo"
url String Wrapped 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

Field Type Description
h Int Height in pixels of this size.

Example:

"h":150
resize String Resizing 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"
w Int Width in pixels of this size.

Example:

"w":150

Sizes

Field Type Description
thumb Object Information for a thumbnail-sized version of the media.

Example:

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

Example:

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

Example:

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

Example:

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

URL

Field Type Description
display_url String Version of the URL to display to clients.

Example:

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

Example:

"expanded_url":"http:\/\/www.youtube.com\/watch?v=oHg5SJYRHA0"
indices Array of Int An 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]
url String Wrapped 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

Field Type Description
id Int64 ID of the mentioned user, as an integer.

Example:

"id":6253282
id_str String If of the mentioned user, as a string.

Example:

"id_str":"6253282"
indices Array of Int An 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]
name String Display name of the referenced user.

Example:

"name":"Twitter API"
screen_name String Screen name of the referenced user.

Example:

"screen_name":"twitterapi"

Entities for User Objects

Entities for User Objects describe URLs that appear in the user-defined profile URL and description fields. They do not describe hashtags or user_mentions. Unlike Tweet entities, user entities can apply to multiple fields within its parent object — to disambiguate, you'll find a parent nodes called "url" and "description" that indicate which field contains the entitized URL.

In this example, the user's "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. 

"entities": {
  "url": {
    "urls": [
      {
        "expanded_url": null,
        "url": "http://dev.twitter.com",
        "indices": [
          0,
          22
        ]
      }
    ]
  },
  "description": {
    "urls": [

    ]
  }
}

Entities for Retweets

Entities in retweeted objects may be different from the original Tweet, particularly in the case where the original Tweet text was shortened for the retweet version. For example, consider this Tweet: 

{
  ...
  "text": "RT @twitterapi: This is a relatively long Tweet which will get  retweeted by other users.  The hashtag at the end will be cut off #FooBa ...",
  ...
  "retweeted_status": {
    ...
    "text": "This is a relatively long Tweet which will get  retweeted by other users.  The hashtag at the end will be cut off #FooBarBaz",
    ...
  },
  ...
}

The corresponding entities differ, including a truncated hashtag entry for the toplevel entities object. For this reason, you should reference retweeted_status for Tweet information whenever it exists: 

{
  ...
  "entities": {
    "hashtags": [
      {
        "text": "FooBarBaz",
        "indices": [
          113,
          123
        ]
      }
    ],
    "urls": [],
    "user_mentions": []
  },
  ...
  "retweeted_status": {
    ...
    "entities": {
      "hashtags": [
        {
          "text": "FooBa",
          "indices": [
            125,
            131
          ]
        }
      ],
      "urls": [],
      "user_mentions": [
        {
          "screen_name": "TwitterAPI",
          "name": "Twitter API",
          "id": 6253282,
          "id_str": "6253282",
          "indices": [
            3,
            14
          ]
        }
      ]
    },
    ...
  },
  ...
}