Tweets¶
Tweets are the basic atomic building block of all things Twitter. Tweets are also known as “status updates.” Tweets can be embedded, replied to, liked, unliked and deleted.
just setting up my twttr
— Jack (@jack) March 21, 2006
Field Guide¶
Consumers of Tweets 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. Please note that Tweets found in Search results vary somewhat in structure from this document.
Field | Type | Description |
---|---|---|
contributors | Collection of Contributors | Deprecated Nullable A collection of brief user objects (usually only one) indicating users who contributed to the authorship of the tweet, on behalf of the official tweet author. This is a legacy value and is not actively used. Example: "contributors":
[
{
"id":819797,
"id_str":"819797",
"screen_name":"episod"
}
]
|
coordinates | Coordinates | Nullable Represents the geographic location of this Tweet as reported by the user or client application. The inner coordinates array is formatted as geoJSON (longitude first, then latitude). Example: "coordinates":
{
"coordinates":
[
-75.14310264,
40.05701649
],
"type":"Point"
}
|
created_at | String | UTC time when this Tweet was created. Example: "created_at":"Wed Aug 27 13:08:45 +0000 2008"
|
current_user_retweet | Object | Perspectival Only surfaces on methods supporting the "current_user_retweet": {
"id": 26815871309,
"id_str": "26815871309"
}
|
entities | Entities | Entities which have been parsed out of the text of the Tweet. Additionally see Entities in Twitter Objects . Example: "entities":
{
"hashtags":[],
"urls":[],
"user_mentions":[]
}
|
favorite_count | Integer | Nullable Indicates approximately how many times this Tweet has been liked by Twitter users. Example: "favorite_count":1138
|
favorited | Boolean | Nullable Perspectival Indicates whether this Tweet has been liked by the authenticating user. Example: "favorited":true
|
filter_level | String | Indicates the maximum value of the filter_level parameter which may be
used and still stream this Tweet. So a value of Example: "filter_level": "medium"
|
geo | Object | Deprecated Nullable Use the coordinates field instead. |
id | Int64 | The integer representation of the unique identifier for this Tweet. This number is greater than 53 bits and some programming
languages may have difficulty/silent defects in interpreting it. Using a signed 64 bit integer for storing this identifier is safe.
Use "id":114749583439036416
|
id_str | String | The string representation of the unique identifier for this Tweet. Implementations should use this rather than the large integer in
"id_str":"114749583439036416"
|
in_reply_to_screen_name | String | Nullable If the represented Tweet is a reply, this field will contain the screen name of the original Tweet’s author. Example: "in_reply_to_screen_name":"twitterapi"
|
in_reply_to_status_id | Int64 | Nullable If the represented Tweet is a reply, this field will contain the integer representation of the original Tweet’s ID. Example: "in_reply_to_status_id":114749583439036416
|
in_reply_to_status_id_str | String | Nullable If the represented Tweet is a reply, this field will contain the string representation of the original Tweet’s ID. Example: "in_reply_to_status_id_str":"114749583439036416"
|
in_reply_to_user_id | Int64 | Nullable If the represented Tweet is a reply, this field will contain the integer representation of the original Tweet’s author ID. This will not necessarily always be the user directly mentioned in the Tweet. Example: "in_reply_to_user_id":819797
|
in_reply_to_user_id_str | String | Nullable If the represented Tweet is a reply, this field will contain the string representation of the original Tweet’s author ID. This will not necessarily always be the user directly mentioned in the Tweet. Example: "in_reply_to_user_id_str":"819797"
|
lang | String | Nullable When present, indicates a BCP 47 language identifier corresponding to the
machine-detected language of the Tweet text, or "lang": "en"
|
place | Places | Nullable When present, indicates that the tweet is associated (but not necessarily originating from) a Place . Example: "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/01fbe706f872cb32.json"
}
|
possibly_sensitive | Boolean | Nullable This field only surfaces when a Tweet contains a link. The meaning of the field doesn’t pertain to the Tweet content itself, but instead it is an indicator that the URL contained in the Tweet may contain content or media identified as sensitive content. Example: "possibly_sensitive":true
|
quoted_status_id | Int64 | This field only surfaces when the Tweet is a quote Tweet. This field contains the integer value Tweet ID of the quoted Tweet. Example: "quoted_status_id":114749583439036416
|
quoted_status_id_str | String | This field only surfaces when the Tweet is a quote Tweet. This is the string representation Tweet ID of the quoted Tweet. Example: "quoted_status_id_str":"114749583439036416"
|
quoted_status | Tweet | This field only surfaces when the Tweet is a quote Tweet. This attribute contains the Tweet object of the original Tweet that was quoted. |
scopes | Object | A set of key-value pairs indicating the intended contextual delivery of the containing Tweet. Currently used by Twitter’s Promoted Products. Example: "scopes":{"followers":false}
|
retweet_count | Int | Number of times this Tweet has been retweeted. Example: "retweet_count":1585
|
retweeted | Boolean | Perspectival Indicates whether this Tweet has been retweeted by the authenticating user. Example: "retweeted":false
|
retweeted_status | Tweet | Users can amplify the broadcast of Tweets authored by other users by retweeting .
Retweets can be distinguished from typical Tweets by the existence of a retweeted_status attribute. This attribute
contains a representation of the original Tweet that was retweeted. Note that retweets of retweets do not show representations of
the intermediary retweet, but only the original Tweet. (Users can also unretweet a
retweet they created by deleting their retweet.) |
source | String | Utility used to post the Tweet, as an HTML-formatted string. Tweets from the Twitter website have a source value of Example: "source":"\u003Ca href=\"http:\/\/itunes.apple.com\/us\/app\/twitter\/id409789998?mt=12\" \u003ETwitter for Mac\u003C\/a\u003E"
|
text | String | The actual UTF-8 text of the status update. See twitter-text for details on what is currently considered valid characters. Example: "text":"Tweet Button, Follow Button, and Web Intents javascript now support SSL http:\/\/t.co\/9fbA0oYy ^TS"
|
truncated | Boolean | Indicates whether the value of the "truncated":true
|
user | Users | The user who posted this Tweet. Perspectival attributes embedded within this object are unreliable. Example: "user":{"statuses_count":3080, "favourites_count":22, "protected":false, "profile_text_color":"437792", "profile_image_url":"..."
"profile_image_url":"...", "name":"Twitter API", "profile_sidebar_fill_color":"a9d9f1", "listed_count":9252, "following":true,
"profile_background_tile":false, "utc_offset":-28800,
"description":"The Real Twitter API. I tweet about API changes. Don't get an answer? It's on my website.",
"location":"San Francisco, CA", "contributors_enabled":true, "verified":true, "profile_link_color":"0094C2",
"followers_count":665829, "url":"http:\/\/dev.twitter.com", "default_profile":false, "profile_sidebar_border_color":"0094C2",
"screen_name":"twitterapi", "default_profile_image":false, "notifications":false, "display_url":null,
"show_all_inline_media":false, "geo_enabled":true, "profile_use_background_image":true, "friends_count":32, "id_str":"6253282",
"entities":{"hashtags":[], "urls":[], "user_mentions":[]}, "expanded_url":null, "is_translator":false, "lang":"en",
"time_zone":"Pacific Time (US & Canada)", "created_at":"Wed May 23 06:01:13 +0000 2007", "profile_background_color":"e8f2f7",
"id":6253282, "follow_request_sent":false, "profile_background_image_url_https":"...", "profile_background_image_url":"...",}
|
withheld_copyright | Boolean | When present and set to “true”, it indicates that this piece of content has been withheld due to a DMCA complaint . Example: "withheld_copyright": true
|
withheld_in_countries | Array of String | When present, indicates a list of uppercase two-letter country codes this content is withheld from. Twitter supports the following non-country values for this field: “XX” - Content is withheld in all countries “XY” - Content is withheld due to a DMCA request. Example: "withheld_in_countries": ["GR", "HK", "MY"]
|
withheld_scope | String | When present, indicates whether the content being withheld is the “status” or a “user.” Example: "withheld_scope": "status"
|
Coordinates¶
Field | Type | Description |
coordinates | Collection of Float | The longitude and latitude of the Tweet’s location, as a collection in the form [longitude, latitude]. Example: "coordinates":[-97.51087576,35.46500176]
|
type | String | The type of data encoded in the coordinates property. This will be “Point” for Tweet coordinates fields. Example: "type": "Point"
|