Tweet Object

When using enterprise data products, you will notice that much of the data dictionary is similar to the native format of Tweet data, with some additional enriched metadata.  The base level of the native enriched format uses much of the same object names as the Twitter API v1.1 data format.  The Tweet object has a long list of ‘root-level’ attributes, including fundamental attributes such as id, created_at, and text. Tweet objects will also have nested objects to include the user, entities, and extended_entities. Tweet objects will also have other nested Tweet objects such as retweeted_status, quoted_status and extended_tweet.  The native enriched format will additionally have a matching_rules object.

Tweet Data Dictionary

Below you will find the data dictionary for these ‘root-level’ attributes, as well as links to child object data dictionaries.

"created_at": "Wed Oct 10 20:19:24 +0000 2018"

"id":1050118621198921728

"id_str":"1050118621198921728"

"text":"To make room for more expression, we will now count all emojis as equal—including those with gender‍‍‍ ‍‍and skin t… https://t.co/MkGjXf9aXm"

"source":"Twitter Web Client"

"truncated":true

"in_reply_to_status_id":1051222721923756032

"in_reply_to_status_id_str":"1051222721923756032"

"in_reply_to_user_id":6253282

"in_reply_to_user_id_str":"6253282"

"in_reply_to_screen_name":"twitterapi"

 { "user": {
    "id": 6253282,
    "id_str": "6253282",
    "name": "Twitter API",
    "screen_name": "TwitterAPI",
    "location": "San Francisco, CA",
    "url": "https://developer.twitter.com",
    "description": "The Real Twitter API. Tweets about API changes, service issues and our Developer Platform. Don't get an answer? It's on my website.",
    "verified": true,
    "followers_count": 6129794,
    "friends_count": 12,
    "listed_count": 12899,
    "favourites_count": 31,
    "statuses_count": 3658,
    "created_at": "Wed May 23 06:01:13 +0000 2007",
    "utc_offset": null,
    "time_zone": null,
    "geo_enabled": false,
    "lang": "en",
    "contributors_enabled": false,
    "is_translator": false,
    "profile_background_color": "null",
    "profile_background_image_url": "null",
    "profile_background_image_url_https": "null",
    "profile_background_tile": null,
    "profile_link_color": "null",
    "profile_sidebar_border_color": "null",
    "profile_sidebar_fill_color": "null",
    "profile_text_color": "null",
    "profile_use_background_image": null,
    "profile_image_url": "null",
    "profile_image_url_https": "https://pbs.twimg.com/profile_images/942858479592554497/BbazLO9L_normal.jpg",
    "profile_banner_url": "https://pbs.twimg.com/profile_banners/6253282/1497491515",
    "default_profile": false,
    "default_profile_image": false,
    "following": null,
    "follow_request_sent": null,
    "notifications": null
  }
}

"coordinates":
{
    "coordinates":
    [
        -75.14310264,
        40.05701649
    ],
    "type":"Point"
}

"place":
{
  "attributes":{},
   "bounding_box":
  {
     "coordinates":
     [[
           [-77.119759,38.791645],
           [-76.909393,38.791645],
           [-76.909393,38.995548],
           [-77.119759,38.995548]
     ]],
     "type":"Polygon"
  },
   "country":"United States",
   "country_code":"US",
   "full_name":"Washington, DC",
   "id":"01fbe706f872cb32",
   "name":"Washington",
   "place_type":"city",
   "url":"http://api.twitter.com/1/geo/id/0172cb32.json"
}

"quoted_status_id":1050119905717055488

"quoted_status_id_str":"1050119905717055488"

"is_quote_status":false

"quote_count":33

"reply_count":30

"retweet_count":160

"favorite_count":295

"entities":
{
    "hashtags":[],
    "urls":[],
    "user_mentions":[],
    "media":[],
    "symbols":[]
    "polls":[]
}

"entities":
{
    "media":[]
}

"favorited":true

"retweeted":false

"possibly_sensitive":false

"filter_level": "low"

"lang": "en"

edit_history": {
    "initial_tweet_id": "1283764123"
    "edit_tweet_ids": ["1283764123", "1394263866"]
  }

"edit_controls": {  
     "editable_until_ms": 123
     "edits_remaining": 3   
  }

"matching_rules": " [{
        "tag": "twitterapi emojis",
        "id": 1050118621198921728,
        "id_str": "1050118621198921728"
    }]"

Additional Tweet attributes

Twitter APIs that provide Tweets (e.g. the GET statuses/lookup endpoint) may include these additional Tweet attributes:

"current_user_retweet": {
  "id": 6253282,
  "id_str": "6253282"
}

"scopes":{"followers":false}

"withheld_copyright": true

"withheld_in_countries": ["GR", "HK", "MY"]

"withheld_scope": "status"

Deprecated Attributes

Nested Tweet objects

In several cases, a Tweet object will included other nested objects.  If you are working with nested objects, then that JSON payload will contain multiple Tweet objects, and each Tweet object may contain its own objects. The root-level object will contain information on the type of action taken, i.e. whether it is a Retweet or a Quote Tweet, and may also contain an object that describes the 'original' Tweet being shared. Extended Tweets will include a nested extended object that extends beyond 140 characters, which was used to prevent breaking changes when the update was made in 2017. Each nested object dictionary is described below.

Retweets

Retweets always contain two Tweet objects. The 'original' Tweet being Retweeted is provided in a "retweeted_status" object. The root-level object encapsulates the Retweet itself, including a User object for the account taking the Retweet action and the time of the Retweet. Retweeting is an action to share a Tweet with your followers, and no other new content can be added. Also, a (new) location cannot be provided with a Retweet. While the 'original' Tweet may have geo-tagged, the Retweet "geo" and "place" objects will always be null.

Even before the introduction of Extended Tweets, the root-level "entities" object was in some cases truncated and incomplete due to the "RT @username " string being appended to Tweet message being Retweeted.  Note that if a Retweet gets Retweeted, the "retweet_status" will still point to the original Tweet, meaning the intermediate Retweet is not included. Similar behavior is seen when using twitter.com to 'display' a Retweet. If you copy the unique Tweet ID assigned to the Retweet 'action', the original Tweet is displayed. 

Below is an example structure for a Retweet. Again, when parsing Retweets, it is key to parse the "retweeted_status" object for complete (original) Tweet message and entity metadata.

Quote Tweets

Quote Tweets are much like Retweets except that they include a new Tweet message. These new messages can contain their own set of hashtags, links, and other "entities" metadata. Quote Tweets can also include location information shared by the user posting the Quote Tweet, along with media such as GIFs, videos, and photos.

Quote Tweets will contain at least two Tweet objects, and in some cases, three. The Tweet being Quoted, which itself can be a Quoted Tweet, is provided in a "quoted_status" object. The root-level object encapsulates the Quote Tweet itself, including a User object for the account taking the sharing action and the time of the Quote Tweet.

Note that Quote Tweets can now have photos, GIFs, or videos, added to them using the 'post Tweet' user-interface. When links to externally hosted media are included in the Quote Tweet message, the root-level "entities.urls" will describe those. Media attached to Quote Tweets will appear in the root-level "extended_entities" metadata.

When Quote Tweets were first launched, a shortened link (t.co URL) was appended to the 'original' Tweet message and provided in the root-level "text" field. In addition, metadata for that t.co URL was included in the root-level 'entities.urls' array. In May 2018, we changed this so that the shortened t.co URL to the quoted Tweet will not be included in the root-level "text" field. Second, the metadata for the quoted Tweet will not be included in the "entities.urls" metadata. Instead, URL metadata for the quoted Tweet will be in a new "quoted_status_permalink" object on the root-level (or top-level), so at the same level of the "quoted_status" object.

Below is an example structure for a Quote Tweet using this original formatting. 

Extended Tweets

JSON that describes Extended Tweets was introduced when 280-character Tweets were launched in November 2017. Tweet JSON was extended to encapsulate these longer messages, while not breaking the thousands of apps parsing these fundamental Twitter objects. To provide full backward compatibility, the original 140-character 'text' field, and the entity objects parsed from that, were retained. In the case of Tweets longer than 140 characters, this root-level 'text' field would become truncated and thus incomplete. Since the root-level 'entities' objects contain arrays of key metadata parsed from the 'text' message, such as included hashtags and links, these collections would be incomplete. For example, if a Tweet message was 200 characters long, with a hashtag included at the end, the legacy root-level 'entities.hashtags' array would not include it. 

A new 'extended_tweet' field was introduced to hold the longer Tweet messages and complete entity metadata. The "extended_tweet" object provides the "full_text" field that contains the complete, untruncated Tweet message when longer than 140 characters. The "extended_tweet" object also contains an "entities" object with complete arrays of hashtags, links, mentions, etc.

Extended Tweets are identified with a root-level "truncated" boolean. When true ("truncated": true), the "extended_tweet" fields should be parsed instead of the root-level fields.

Note in the JSON example below that the root-level "text" field is truncated and the root-level "entities.hashtags" array is empty even though the Tweet message includes three hashtags. Since this is an Extended Tweet, the "truncated" field is set to true, and the "extended_tweet" object provides complete "full_text" and "entities" Tweet metadata.

Next Steps

Explore the other sub-objects that a Tweet contains:

• User object and data dictionary
• Entities object and data dictionary
• Extended Entities object and data dictionary
• Tweet geo objects and data dictionaries