Entities in Objects

Entities are intimately related to other Twitter Objects. Listed below are the various relationships that Entities have, and any additional attributes needed for that relationship.

Entities for Tweets

Entities provide structured data from Tweets including resolved URLs, media, hashtags and mentions without having to parse the text to extract that information. Entities are included in all Tweet Objects from both the REST API and Streaming APIs endpoints, located under the entities attribute.

As usual, it is important to be tolerant of new fields and empty/null values in all returns. Entities are included by default, but you can omit them by setting the include_entities parameter to false in your requests.

Below are the details of entities you can find in Tweet Objects:

The media entity

An array of media attached to the Tweet with the Twitter Photo Upload feature. Each media entity comes with the following attributes:

id the media ID (int format)
id_str the media ID (string format)
media_url The URL of the media file (see the sizes attribute for available sizes)
media_url_https The SSL URL of the media file (see the sizes attribute for available sizes)
url The media URL that was extracted
display_url Not a URL but a string to display instead of the media URL
expanded_url The fully resolved media URL
sizes We support different sizes: thumb, small, medium and large. The media_url defaults to medium but you can retrieve the media in different sizes by appending a colon + the size key (for example: http://pbs.twimg.com/media/A7EiDWcCYAAZT1D.jpg:thumb ). Each available size comes with three attributes that describe it: w : the width (in pixels) of the media in this particular size; h : the height (in pixels) of the media in this particular size; and resize : how we resized the media to this particular size (can be crop or fit )
type Only photo for now
indices The character positions the media was extracted from

JSON Example

{
  ...
  "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

An array of URLs extracted from the Tweet text. Each URL entity comes with the following attributes:

url The t.co URL that was extracted from the Tweet text
display_url Not a valid URL but a string to display instead of the URL
expanded_url The resolved URL
indices The character positions the URL was extracted from

JSON Example

{
  ...
  "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\u2026",
      "indices": [80, 103]
    }],
    "user_mentions": []
  }
}

The user_mentions entity

An array of Twitter screen names extracted from the Tweet text. Each user mention entity comes with the following attributes:

id The user ID (int format)
id_str The user ID (string format)
screen_name The user screen name
name The user full name
indices The character positions the user mention was extracted from

JSON Example

{
  ...
  "text": "We\u2019re excited to work closely with the external technical community and continue @twittereng\u2019s 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

An array of hashtags extracted from the Tweet text. Each hashtag entity comes with the following attributes:

text The hashtag text
indices The character positions the hashtag was extracted from

JSON Example

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

The symbols entity

An array of financial symbols starting with the dollar sign extracted from the Tweet text. Similar to hashtags, an entity comes with the following attributes:

text The symbol text
indices The character positions the symbol was extracted from

JSON Example

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

extended_entities

This nested object supports various media types such as multi photos, animated gifs and video. This field also contains a lot of meta data about the type of information that is present in there; such as aspect ratio, variants, sizes, duration, bitrate etc. Each media entity comes with the following attributes:

id the media ID (int format)
id_str the media ID (string format)
indices The character positions the media was extracted from
media_url The URL of the media file (see the sizes attribute for available sizes)
media_url_https The SSL URL of the media file (see the sizes attribute for available sizes)
url The media URL that was extracted
display_url Not a URL but a string to display instead of the media URL
expanded_url The fully resolved media URL
type Values may be photo, multi photos, animated gif or video.
sizes We support different sizes: thumb, small, medium and large. The media_url defaults to medium but you can retrieve the media in different sizes by appending a colon + the size key (for example: http://pbs.twimg.com/media/A7EiDWcCYAAZT1D.jpg:thumb ). Each available size comes with three attributes that describe it: w : the width (in pixels) of the media in this particular size; h : the height (in pixels) of the media in this particular size; resize : how we resized the media to this particular size (can be crop or fit )
ext_alt_text Descriptive alt text for the image for accessibility (if added)
video_info Contains information about aspect ratio. The aspect ratio of the video, as a simplified fraction of width and height in a 2-element array. Typical values are [4, 3] or [16, 9]. This field is present only when there is a video in the payload.
duration_millis The length of the video, in milliseconds. This field is present only when there is a video in the payload.
variants Different encodings/streams of the video. At least one variant is returned for each video entry. Video formats returned via the API are subject to change. As a best practice, developers should scan all returned values and use the most appropriate format for their given platform. This field is present only when there is a video in the payload.
additional_media_info Contains additional media info provided by the publisher, such as title, description and embeddable flag. Video content is made available only to Twitter official clients when embeddable=false. If embeddable=false and there is no video in the Tweet response, the t.co link should be included in the result displayed to the user, so that the user can open the video in a Twitter owned property by clicking the link.

extended_entities JSON example for video

{
     "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\/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"
         }
       ]
     },
     "additional_media_info": {
       "title": "What's happening.",
       "description": "Twitter is what's happening",
       "embeddable": true,
     }
   }

Entities for Retweets

From the Twitter API perspective, a Retweet is a special kind of Tweet that contains the original Tweet as an embedded retweeted_status object. For consistency, the top-level Retweet object also has a text property and associated entities.

The Retweet text attribute is composed of the original Tweet text with “RT @username: ” prepended. If the display character count then exceeds 140 characters, this text is truncated and an ellipsis “…” is added. Consequently, some top-level entities might be incorrect or missing, for instance in the case of a truncated hashtag entry.

As a result, the best practice is to retrieve the text, entities, original author and date from the original Tweet in retweeted_status whenever this exists.

JSON Example

{
  ...
  "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\u2026",
  "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\u2026",
        "indices": [115, 138]
      }],
      "user_mentions": [{
        "screen_name": "raffi",
        "name": "Raffi Krikorian",
        "id": 8285392,
        "id_str": "8285392",
        "indices": [36, 42]
      }]
    }
  }
}

In the above example, the URL was truncated in the top-level text and missing from the top-level entities. You will also notice the additional user_mentions top-level entity coming from the “RT @rsarver: ” prefix on the text field.

However, the Tweet text and entities in retweeted_status perfectly reflect the original Tweet with no truncation or incorrect entities, hence our recommendation to rely on this nested object for Retweets.

Upcoming Change

Top-level entities for Retweets are consistent with the original Tweet ones. We strongly recommend using entities from the original retweeted_status, but if you are making use of those top-level entities, below is a detailed example for the changes you will see early next year when we start rolling this out.

Check out this Retweet example to illustrate the change.

JSON Extract Before the Change

{
  ...
  "text": "RT @university: Learn more about the powerful #Linux container engine @docker in this video intro with @solomonstre - http:\/\/t.co\/QJLdA1762\u2026",
  "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]
      }]
    }
  }
}

Details of the Change

Retweet Entities

Since the URL was truncated in the top-level text, 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. The URL entity will contain the entire shortened URL, even though that URL is not fully contained in the Retweet text.

The @TwitterOSS user mention entity was also missing since it was entirely truncated. It will now be included but will only reference the ellipsis character at indices [139, 140]. Please also note that the order of entities is not guaranteed to be ordered by from indices.

JSON Extract After the Change

{
  ...
  "text": "RT @university: Learn more about the powerful #Linux container engine @docker in this video intro with @solomonstre - http:\/\/t.co\/QJLdA1762\u2026",
  "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 for Users

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 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 Example

{
  "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 for Direct Messages

Entities for Direct Messages are very similar to entities for Tweets. However, there are a few differences concerning the media entities.

Unlike media shared in Tweets, media shared in direct messages requires authorization to view. This authorization can be presented via an authenticated twitter.com session or by signing a request with the user’s access token using OAuth 1.0A.

Also, in tweets, media URLs are only in the media entities, but in direct messages, media URLs are in both media and 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"
                }
            }
        }]
    }
    ...
}