Post Object

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

X 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 Post attributes

X APIs that provide Posts (e.g. the GET statuses/lookup endpoint) may include these additional Post 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 Post objects

In several cases, a Post object will included other nested objects.  If you are working with nested objects, then that JSON payload will contain multiple Post objects, and each Post 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' Post being shared. Extended Posts 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 Post objects. The 'original' Post 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 Post with your followers, and no other new content can be added. Also, a (new) location cannot be provided with a Retweet. While the 'original' Post may have geo-tagged, the Retweet "geo" and "place" objects will always be null.

Even before the introduction of Extended Posts, the root-level "entities" object was in some cases truncated and incomplete due to the "RT @username " string being appended to Post message being Retweeted.  Note that if a Retweet gets Retweeted, the "retweet_status" will still point to the original Post, meaning the intermediate Retweet is not included. Similar behavior is seen when using x.com to 'display' a Retweet. If you copy the unique Post ID assigned to the Retweet 'action', the original Post 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) Post message and entity metadata.

Quote Tweets

Quote Tweets are much like Retweets except that they include a new Post 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 Post objects, and in some cases, three. The Post 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' 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' Post 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 Posts

JSON that describes Extended Posts was introduced when 280-character Posts were launched in November 2017. Post JSON was extended to encapsulate these longer messages, while not breaking the thousands of apps parsing these fundamental X 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 Posts 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 Post 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 Post messages and complete entity metadata. The "extended_tweet" object provides the "full_text" field that contains the complete, untruncated Post message when longer than 140 characters. The "extended_tweet" object also contains an "entities" object with complete arrays of hashtags, links, mentions, etc.

Extended Posts 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 Post message includes three hashtags. Since this is an Extended Post, the "truncated" field is set to true, and the "extended_tweet" object provides complete "full_text" and "entities" Post metadata.

Next Steps

Explore the other sub-objects that a Post contains:

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