Twitter Rest API v1.1
Base URI
Timelines are collections of Tweets, ordered with the most recent first.
Returns the 20 most recent mentions (tweets containing a users’s @screen_name) for the authenticating user.
The timeline returned is the equivalent of the one seen when you view your mentions on twitter.com.
This method can only return up to 800 tweets.
See Working with Timelines for instructions on traversing timelines.
Request parameters
Specifies the number of tweets to try and retrieve, up to a maximum of 200. The value of count is best thought of as a limit to the number of tweets to return because suspended or deleted content is removed after the count has been applied. We include retweets in the count, even if include_rts is not supplied. It is recommended you always send include_rts=1 when using this API method.
Returns results with an ID greater than (that is, more recent than) the specified ID. There are limits to the number of Tweets which can be accessed through the API. If the limit of Tweets has occured since the since_id, the since_id will be forced to the oldest ID available.
Returns results with an ID less than (that is, older than) or equal to the specified ID.
When set to either true, t or 1, each tweet returned in a timeline will include a user object including only the status authors numerical ID. Omit this parameter to receive the complete user object.
This parameter enhances the contributors element of the status response to include the screen_name of the contributor. By default only the user_id of the contributor is included.
The entities node will be disincluded when set to false.
Responses
Body
Returns a collection of the most recent Tweets posted by the user indicated by the screen_name or user_id parameters.
User timelines belonging to protected users may only be requested when the authenticated user either “owns” the timeline or is an approved follower of the owner.
The timeline returned is the equivalent of the one seen when you view a user’s profile on twitter.com.
This method can only return up to 3,200 of a user’s most recent Tweets. Native retweets of other statuses by the user is included in this total, regardless of whether include_rts is set to false when requesting this resource.
See Working with Timelines for instructions on traversing timelines.
See Embeddable Timelines, Embeddable Tweets, and GET statuses/oembed for tools to render Tweets according to Display Requirements.
Request parameters
The ID of the user for whom to return results for.
The screen name of the user for whom to return results for.
Returns results with an ID greater than (that is, more recent than) the specified ID. There are limits to the number of Tweets which can be accessed through the API. If the limit of Tweets has occured since the since_id, the since_id will be forced to the oldest ID available.
Specifies the number of tweets to try and retrieve, up to a maximum of 200 per distinct request. The value of count is best thought of as a limit to the number of tweets to return because suspended or deleted content is removed after the count has been applied. We include retweets in the count, even if include_rts is not supplied. It is recommended you always send include_rts=1 when using this API method.
Returns results with an ID less than (that is, older than) or equal to the specified ID.
When set to either true, t or 1, each tweet returned in a timeline will include a user object including only the status authors numerical ID. Omit this parameter to receive the complete user object.
This parameter will prevent replies from appearing in the returned timeline. Using exclude_replies with the count parameter will mean you will receive up-to count tweets — this is because the count parameter retrieves that many tweets before filtering out retweets and replies. This parameter is only supported for JSON and XML responses.
This parameter enhances the contributors element of the status response to include the screen_name of the contributor. By default only the user_id of the contributor is included.
When set to false, the timeline will strip any native retweets (though they will still count toward both the maximal length of the timeline and the slice selected by the count parameter). Note: If you’re using the trim_user parameter in conjunction with include_rts, the retweets will still contain a full user object.
Responses
Body
API version 1.1 Updated on Wed, 2012-09-05 11:06 Returns a collection of the most recent Tweets and retweets posted by the authenticating user and the users they follow. The home timeline is central to how most users interact with the Twitter service.
Up to 800 Tweets are obtainable on the home timeline. It is more volatile for users that follow many users or follow users who tweet frequently.
See Working with Timelines for instructions on traversing timelines efficiently.
Request parameters
Specifies the number of records to retrieve. Must be less than or equal to 200. Defaults to 20.
Returns results with an ID greater than (that is, more recent than) the specified ID. There are limits to the number of Tweets which can be accessed through the API. If the limit of Tweets has occured since the since_id, the since_id will be forced to the oldest ID available.
Returns results with an ID less than (that is, older than) or equal to the specified ID.
When set to either true, t or 1, each tweet returned in a timeline will include a user object including only the status authors numerical ID. Omit this parameter to receive the complete user object.
This parameter will prevent replies from appearing in the returned timeline. Using exclude_replies with the count parameter will mean you will receive up-to count tweets — this is because the count parameter retrieves that many tweets before filtering out retweets and replies.
This parameter enhances the contributors element of the status response to include the screen_name of the contributor. By default only the user_id of the contributor is included.
The entities node will be disincluded when set to false.
Responses
Body
Returns the most recent tweets authored by the authenticating user that have been retweeted by others. This timeline is a subset of the user’s GET statuses/user_timeline.
See Working with Timelines for instructions on traversing timelines.
Request parameters
Specifies the number of records to retrieve. Must be less than or equal to 100. If omitted, 20 will be assumed.
Returns results with an ID greater than (that is, more recent than) the specified ID. There are limits to the number of Tweets which can be accessed through the API. If the limit of Tweets has occured since the since_id, the since_id will be forced to the oldest ID available.
Returns results with an ID less than (that is, older than) or equal to the specified ID.
When set to either true, t or 1, each tweet returned in a timeline will include a user object including only the status authors numerical ID. Omit this parameter to receive the complete user object.
The tweet entities node will be disincluded when set to false.
The user entities node will be disincluded when set to false.
Responses
Body
Tweets are the atomic building blocks of Twitter, 140-character status updates with additional associated metadata. People tweet for a variety of reasons about a multitude of topics.
{id}{id}{id}.json{id}Returns a collection of the 100 most recent retweets of the tweet specified by the id parameter.
Path variables
The numerical ID of the desired status.
Request parameters
Specifies the number of records to retrieve. Must be less than or equal to 100.
When set to either true, t or 1, each tweet returned in a timeline will include a user object including only the status authors numerical ID. Omit this parameter to receive the complete user object.
Responses
Body
Returns a single Tweet, specified by the id parameter. The Tweet’s author will also be embedded within the tweet.
See Embeddable Timelines, Embeddable Tweets, and GET /statuses/oembed for tools to render Tweets according to Display Requirements.
Request parameters
The numerical ID of the desired Tweet.
When set to either true, t or 1, each tweet returned in a timeline will include a user object including only the status authors numerical ID. Omit this parameter to receive the complete user object.
When set to either true, t or 1, any Tweets returned that have been retweeted by the authenticating user will include an additional current_user_retweet node, containing the ID of the source status for the retweet.
The entities node will be disincluded when set to false.
Responses
About Geo
If there is no geotag for a status, then there will be an empty <geo/> or "geo" : {}. This can only be populated if the user has used the Geotagging API to send a statuses/update.
The JSON response mostly uses conventions laid out in GeoJSON. Unfortunately, the coordinates that Twitter renders are reversed from the GeoJSON specification (GeoJSON specifies a longitude then a latitude, whereas we are currently representing it as a latitude then a longitude). Our JSON renders as:
"geo": { "type":"Point", "coordinates":[37.78029, -122.39697] }
Contributors
If there are no contributors for a Tweet, then there will be an empty or “contributors” : {}. This field will only be populated if the user has contributors enabled on his or her account – this is a beta feature that is not yet generally available to all.
This object contains an array of user IDs for users who have contributed to this status (an example of a status that has been contributed to is this one). In practice, there is usually only one ID in this array. The JSON renders as such “contributors”:[8285392].
Body
Examples
GET https://api.twitter.com/1.1/statuses/show.json?id=210462857140252672 HTTP/1.1
HTTP/1.1 200 OK
Content-Type: application/json
{
"coordinates": null,
"favorited": false,
"truncated": false,
"created_at": "Wed Jun 06 20:07:10 +0000 2012",
"id_str": "210462857140252672",
"entities": {
"urls": [
{
"expanded_url": "https://dev.twitter.com/terms/display-guidelines",
"url": "https://t.co/Ed4omjYs",
"indices": [
76,
97
],
"display_url": "dev.twitter.com/terms/display-\u2026"
}
],
"hashtags": [
{
"text": "Twitterbird",
"indices": [
19,
31
]
}
],
"user_mentions": [
]
},
"in_reply_to_user_id_str": null,
"contributors": [
14927800
],
"text": "Along with our new #Twitterbird, we've also updated our Display Guidelines: https://t.co/Ed4omjYs ^JC",
"retweet_count": 66,
"in_reply_to_status_id_str": null,
"id": 210462857140252672,
"geo": null,
"retweeted": true,
"possibly_sensitive": false,
"in_reply_to_user_id": null,
"place": null,
"user": {
"profile_sidebar_fill_color": "DDEEF6",
"profile_sidebar_border_color": "C0DEED",
"profile_background_tile": false,
"name": "Twitter API",
"profile_image_url": "http://a0.twimg.com/profile_images/2284174872/7df3h38zabcvjylnyfe3_normal.png",
"created_at": "Wed May 23 06:01:13 +0000 2007",
"location": "San Francisco, CA",
"follow_request_sent": false,
"profile_link_color": "0084B4",
"is_translator": false,
"id_str": "6253282",
"entities": {
"url": {
"urls": [
{
"expanded_url": null,
"url": "http://dev.twitter.com",
"indices": [
0,
22
]
}
]
},
"description": {
"urls": [
]
}
},
"default_profile": true,
"contributors_enabled": true,
"favourites_count": 24,
"url": "http://dev.twitter.com",
"profile_image_url_https": "https://si0.twimg.com/profile_images/2284174872/7df3h38zabcvjylnyfe3_normal.png",
"utc_offset": -28800,
"id": 6253282,
"profile_use_background_image": true,
"listed_count": 10774,
"profile_text_color": "333333",
"lang": "en",
"followers_count": 1212963,
"protected": false,
"notifications": null,
"profile_background_image_url_https": "https://si0.twimg.com/images/themes/theme1/bg.png",
"profile_background_color": "C0DEED",
"verified": true,
"geo_enabled": true,
"time_zone": "Pacific Time (US & Canada)",
"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.",
"default_profile_image": false,
"profile_background_image_url": "http://a0.twimg.com/images/themes/theme1/bg.png",
"statuses_count": 3333,
"friends_count": 31,
"following": true,
"show_all_inline_media": false,
"screen_name": "twitterapi"
},
"in_reply_to_screen_name": null,
"source": "web",
"in_reply_to_status_id": null
}{id}Destroys the status specified by the required ID parameter. The authenticating user must be the author of the specified status. Returns the destroyed status if successful.
Path variables
The numerical ID of the desired status.
Request parameters
When set to either true, t or 1, each tweet returned in a timeline will include a user object including only the status authors numerical ID. Omit this parameter to receive the complete user object.
Responses
Returns destroyed status
Body
Updates the authenticating user’s current status, also known as tweeting. To upload an image to accompany the tweet, use POST statuses/update_with_media.
For each update attempt, the update text is compared with the authenticating user’s recent tweets. Any attempt that would result in duplication will be blocked, resulting in a 403 error. Therefore, a user cannot submit the same status twice in a row.
While not rate limited by the API a user is limited in the number of tweets they can create at a time. If the number of updates posted by the user reaches the current allowed limit this method will return an HTTP 403 error.
Request parameters
Whether or not to put a pin on the exact coordinates a tweet has been sent from
When set to either true, t or 1, each tweet returned in a timeline will include a user object including only the status authors numerical ID. Omit this parameter to receive the complete user object.
Request body
The text of your status update, typically up to 140 characters. URL encode as necessary. t.co link wrapping may effect character counts.
There are some special commands in this field to be aware of. For instance, preceding a message with "D " or "M " and following it with a screen name can create a direct message to that user if the relationship allows for it.
The ID of an existing status that the update is in reply to.
Note: This parameter will be ignored unless the author of the tweet this parameter references is mentioned within the status text. Therefore, you must include @username, where username is the author of the referenced tweet, within the update.
The latitude of the location this tweet refers to. This parameter will be ignored unless it is inside the range -90.0 to +90.0 (North is positive) inclusive. It will also be ignored if there isn’t a corresponding long parameter.
The longitude of the location this tweet refers to. The valid ranges for longitude is -180.0 to +180.0 (East is positive) inclusive. This parameter will be ignored if outside that range, if it is not a number, if geo_enabled is disabled, or if there not a corresponding lat parameter.
A place in the world. These IDs can be retrieved from GET geo/reverse_geocode.
Responses
About Geo
Any geo-tagging parameters in the update will be ignored if geo_enabled for the user is false (this is the default setting for all users unless the user has enabled geolocation in their settings) The number of digits passed the decimal separator passed to lat, up to 8, will be tracked so that the lat is returned in a status object it will have the same number of digits after the decimal separator. Please make sure to use to use a decimal point as the separator (and not the decimal comma) for the latitude and the longitude - usage of the decimal comma will cause the geo-tagged portion of the status update to be dropped. For JSON, the response mostly uses conventions described in GeoJSON. Unfortunately, the geo object has coordinates that Twitter renderers are reversed from the GeoJSON specification (GeoJSON specifies a longitude then a latitude, whereas we are currently representing it as a latitude then a longitude. Our JSON renders as:
"geo": { "type":"Point", "coordinates":[37.78217, -122.40062] }
The coordinates object is replacing the geo object (no deprecation date has been set for the geo object yet) – the difference is that the coordinates object, in JSON, is now rendered correctly in GeoJSON. If a place_id is passed into the status update, then that place will be attached to the status. If no place_id was explicitly provided, but latitude and longitude are, we attempt to implicitly provide a place by calling geo/reverse_geocode. Users will have the ability, from their settings page, to remove all the geotags from all their tweets en masse. Currently we are not doing any automatic scrubbing nor providing a method to remove geotags from individual tweets.
Body
{id}.jsonRetweets a tweet. Returns the original tweet with retweet details embedded.
Usage Notes:
This method is subject to update limits. A HTTP 403 will be returned if this limit as been hit. Twitter will ignore attempts to perform duplicate retweets. The retweet_count will be current as of when the payload is generated and may not reflect the exact count. It is intended as an approximation.
Path variables
The numerical ID of the desired status.
Request parameters
When set to either true, t or 1, each tweet returned in a timeline will include a user object including only the status authors numerical ID. Omit this parameter to receive the complete user object.
Request body
None
Responses
Body
Updates the authenticating user’s current status and attaches media for upload. In other words, it creates a Tweet with a picture attached.
Unlike POST statuses/update, this method expects raw multipart data. Your POST request’s Content-Type should be set to multipart/form-data with the media[] parameter .
See Uploading Media for a guide to using this method.
The Tweet text will be rewritten to include the media URL(s), which will reduce the number of characters allowed in the Tweet text. If the URL(s) cannot be appended without text truncation, the tweet will be rejected and this method will return an HTTP 403 error.
Important: In API v1.1, you now use api.twitter.com as the domain instead of upload.twitter.com. We strongly recommend using SSL with this method.
Request body
Important: In API v1.1, you now use api.twitter.com as the domain instead of upload.twitter.com. We strongly recommend using SSL with this method.
Users are limited to a specific daily media upload limit… Requests to this endpoint will return the following headers with information regarding the user’s current media upload limits:
X-MediaRateLimit-Limit- Indicates the total pieces of media the current user may upload before the time indicated inX-MediaRateLimit-Reset.X-MediaRateLimit-Remaining- The remaining pieces of media the current user may upload before the time indicated inX-MediaRateLimit-Reset.X-MediaRateLimit-Reset- A UTC-based timestamp (in seconds) indicating when X-MediaRateLimit-Remaining will reset to the value inX-MediaRateLimit-Limitand the user can resume uploading media.
If the user is over the daily media limit, this method will return an HTTP 403 error. In addition to media upload limits, the user is still limited in the number of statuses they can publish daily. If the user tries to exceed the number of updates allowed, this method will also return an HTTP 403 error, similar to POST statuses/update.
OAuth is handled differently for POST messages. See Uploading Media for more details on this.
Example Request
Note: The OAuth tool does not support multipart requests, so you will not be able to use it to generate an example request to this endpoint. An example request has been included to demonstrate the multipart request format.
POST /1.1/statuses/update_with_media.json HTTP/1.1
Host: api.twitter.com
User-Agent: Go http package
Content-Length: 15532
Authorization: OAuth oauth_consumer_key="...", oauth_nonce="...", oauth_signature="...", oauth_signature_method="HMAC-SHA1", oauth_timestamp="1347058301", oauth_token="...", oauth_version="1.0"
Content-Type: multipart/form-data;boundary=cce6735153bf14e47e999e68bb183e70a1fa7fc89722fc1efdf03a917340
Accept-Encoding: gzip
--cce6735153bf14e47e999e68bb183e70a1fa7fc89722fc1efdf03a917340
Content-Disposition: form-data; name="status"
Hello 2012-09-07 15:51:41.375247 -0700 PDT!
--cce6735153bf14e47e999e68bb183e70a1fa7fc89722fc1efdf03a917340
Content-Type: application/octet-stream
Content-Disposition: form-data; name="media[]"; filename="media.png"
...
--cce6735153bf14e47e999e68bb183e70a1fa7fc89722fc1efdf03a917340--
The text of your status update. URL encode as necessary. t.co link wrapping may affect character counts if the post contains URLs. You must additionally account for the characters_reserved_per_media per uploaded media, additionally accounting for space characters in between finalized URLs.
Note: Request the GET help/configuration endpoint to get the current characters_reserved_per_media and max_media_per_upload values.
Up to max_media_per_upload files may be specified in the request, each named media[]. Supported image formats are PNG, JPG and GIF. Animated GIFs are not supported. This data must be either the raw image bytes or encoded as base64.
Note: Request the GET help/configuration endpoint to get the current max_media_per_upload and photo_size_limit values.
Set to true for content which may not be suitable for every audience.
The ID of an existing status that the update is in reply to.
Note: This parameter will be ignored unless the author of the tweet this parameter references is mentioned within the status text. Therefore, you must include @username, where username is the author of the referenced tweet, within the update.
The latitude of the location this tweet refers to. This parameter will be ignored unless it is inside the range -90.0 to +90.0 (North is positive) inclusive. It will also be ignored if there isn’t a corresponding long parameter.
The longitude of the location this tweet refers to. The valid ranges for longitude is -180.0 to +180.0 (East is positive) inclusive. This parameter will be ignored if outside that range, not a number, geo_enabled is disabled, or if there not a corresponding lat parameter.
A place in the world identified by a Twitter place ID. Place IDs can be retrieved from geo/reverse_geocode.
Whether or not to put a pin on the exact coordinates a tweet has been sent from.
Responses
Body
Find relevant Tweets based on queries performed by your users.
Returns a collection of relevant Tweets matching a specified query.
Please note that Twitter’s search service and, by extension, the Search API is not meant to be an exhaustive source of Tweets. Not all Tweets will be indexed or made available via the search interface.
In API v1.1, the response format of the Search API has been improved to return Tweet objects more similar to the objects you’ll find across the REST API and platform. You may need to tolerate some inconsistencies and variance in perspectival values (fields that pertain to the perspective of the authenticating user) and embedded user objects.
To learn how to use Twitter Search effectively, consult our guide to Using the Twitter Search API. See Working with Timelines to learn best practices for navigating results by since_id and max_id.
Request parameters
A UTF-8, URL-encoded search query of 1,000 characters maximum, including operators. Queries may additionally be limited by complexity.
Returns tweets by users located within a given radius of the given latitude/longitude. The location is preferentially taking from the Geotagging API, but will fall back to their Twitter profile. The parameter value is specified by “latitude,longitude,radius”, where radius units must be specified as either “mi” (miles) or “km” (kilometers). Note that you cannot use the near operator via the API to geocode arbitrary locations; however you can use this geocode parameter to search near geocodes dire
Restricts tweets to the given language, given by an ISO 639-1 code. Language detection is best-effort.
Specify the language of the query you are sending (only ja is currently effective). This is intended for language-specific consumers and the default should work in the majority of cases.
Specifies what type of search results you would prefer to receive. The current default is mixed. Valid values include:
mixed: Include both popular and real time results in the response.recent: return only the most recent results in the responsepopular: return only the most popular results in the response.
The number of tweets to return per page, up to a maximum of 100. Defaults to 15. This was formerly the “rpp” parameter in the old Search API.
Returns tweets generated before the given date. Date should be formatted as YYYY-MM-DD. Keep in mind that the search index may not go back as far as the date you specify here.
Returns results with an ID greater than (that is, more recent than) the specified ID. There are limits to the number of Tweets which can be accessed through the API. If the limit of Tweets has occured since the since_id, the since_id will be forced to the oldest ID available.
Returns results with an ID less than (that is, older than) or equal to the specified ID.
The entities node will be disincluded when set to false.
If supplied, the response will use the JSONP format with a callback of the given name. The usefulness of this parameter is somewhat diminished by the requirement of authentication for requests to this endpoint.
Responses
Body
The longitude and latitude of the Tweet’s location, as an collection in the form of [longitude, latitude].
-97.51087576The type of data encoded in the coordinates property. This will be “Point” for Tweet coordinates fields.
asasdasd
{
"a":2
}If there are no contributors for a status, then there will be an empty or "contributors" : {}. This field will only be populated if the user has contributors enabled on his or her account — this is a beta feature that is not yet generally available to all.
The integer representation of the ID of the user who contributed to this Tweet.
The string representation of the ID of the user who contributed to this Tweet.
The screen name of the user who contributed to this Tweet.
Tweets are the basic atomic building block of all things Twitter. Users tweet Tweets, also known more generically as “status updates.” Tweets can be embedded, replied to, favorited, unfavorited and deleted.
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.
Unused. Future/beta home for status annotations.
An 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. Discussion.
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).
UTC time when this Tweet was created.
Only surfaces on methods supporting the include_my_retweet parameter, when set to true. Details the Tweet ID of the user’s own retweet (if existent) of this Tweet.
Entities which have been parsed out of the text of the Tweet. Additionally see Entities in Twitter Objects.
Indicates approximately how many times this Tweet has been “favorited” by Twitter users.
Indicates whether this Tweet has been favorited by the authenticating user.
Indicates the maximum value of the filter_level parameter which may be used and still stream this Tweet. So a value of medium will be streamed on none, low, and medium streams. See this announcement for more information.
Deprecated. Nullable. Use the “coordinates” field instead.
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_str for fetching the identifier to stay on the safe side. See Twitter IDs, JSON and Snowflake.
The string representation of the unique identifier for this Tweet. Implementations should use this rather than the large integer in id. Discussion.
If the represented Tweet is a reply, this field will contain the screen name of the original Tweet’s author.
If the represented Tweet is a reply, this field will contain the integer representation of the original Tweet’s ID.
If the represented Tweet is a reply, this field will contain the string representation of the original Tweet’s ID.
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.
Nullable. When present, indicates a BCP 47 language identifier corresponding to the machine-detected language of the Tweet text, or “und” if no language could be detected. Example:
"lang": "en"
Note: As of March 15, 2013, this field is available on REST but not Streaming. Keep an eye on the Calendar of API changes for changes. This documentation will be updated once the parameter is generally available.
When present, indicates that the tweet is associated (but not necessarily originating from) a Place.
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.
A set of key-value pairs indicating the intended contextual delivery of the containing Tweet. Currently used by Twitter’s Promoted Products.
Number of times this Tweet has been retweeted. This field is no longer capped at 99 and will not turn into a String for “100+”
Perspectival. Indicates whether this Tweet has been retweeted by the authenticating user.
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.)
Utility used to post the Tweet, as an HTML-formatted string. Tweets from the Twitter website have a source value of web.
The actual UTF-8 text of the status update. See twitter-text for details on what is currently considered valid characters.
Indicates whether the value of the text parameter was truncated, for example, as a result of a retweet exceeding the 140 character Tweet length. Truncated text will end in ellipsis, like this … Since Twitter now rejects long Tweets vs truncating them, the large majority of Tweets will have this set to false.
Note that while native retweets may have their toplevel text property shortened, the original text will be available under the retweeted_status object and the truncated parameter will be set to the value of the original status (in most cases, false).
The user who posted this Tweet. Perspectival attributes embedded within this object are unreliable. See Why are embedded objects stale or inaccurate?.
When present and set to “true”, it indicates that this piece of content has been withheld due to a DMCA complaint.
When present, indicates a list of uppercase two-letter country codes this content is withheld from. See New Withheld Content Fields in API Responses. As announced in More changes to withheld content fields, 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.
["GR", "HK", "MY"]When present, indicates whether the content being withheld is the “status” or a “user.” See New Withheld Content Fields in API Responses.
Places are specific, named locations with corresponding geo coordinates. They can be attached to Tweets by specifying a place_id when tweeting. Tweets associated with places are not necessarily issued from that location but could also potentially be about that location. Places can be searched for. Tweets can also be found by place_id. See About Geo Place Attributes for more information.
Consumers of Places 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.
A bounding box of coordinates which encloses this place.
{“coordinates”:[ [ [2.2241006,48.8155414], [2.4699099,48.8155414], [2.4699099,48.9021461], [2.2241006,48.9021461] ] ], “type”:“Polygon”}
Array of Array of Array of Float
A series of longitude and latitude points, defining a box which will contain the Place entity this bounding box is related to. Each point is an array in the form of [longitude, latitude]. Points are grouped into an array per bounding box. Bounding box arrays are wrapped in one additional array to be compatible with the polygon notation.
1The type of data encoded in the coordinates property. This will be “Polygon” for bounding boxes.
Name of the country containing this place.
Shortened country code representing the country containing this place.
Full human-readable representation of the place’s name.
ID representing this place. Note that this is represented as a string, not an integer.
Short human-readable representation of the place’s name.
The type of location represented by this place.
URL representing the location of additional place metadata for this place.
Place Attributes are metadata about places. An attribute is a key-value pair of arbitrary strings, but with some conventions.
There are a number of well-known place attributes which may, or may not exist in the returned data. These attributes are provided when the place was created in the Twitter places database.
Keys can be no longer than 140 characters in length. Values are unicode strings and are restricted to 2000 characters.
An ID or comma separated list of IDs representing the place in the applications place database.
twitter screen-name, without @
the city the place is in
the administrative region the place is in
the country code
in the preferred local format for the place
official/canonical URL for place
in the preferred local format for the place, include long distance code
Users can be anyone or anything. They tweet, follow, create lists, have a home_timeline, can be mentioned, and can be looked up in bulk.
Consumers of Users 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.
Indicates that the user has an account with “contributor mode” enabled, allowing for Tweets issued by the user to be co-authored by another account. Rarely true.
The UTC datetime that the user account was created on Twitter.
When true, indicates that the user has not altered the theme or background of their user profile.
When true, indicates that the user has not uploaded their own avatar and a default egg avatar is used instead.
The user-defined UTF-8 string describing their account.
Entities which have been parsed out of the url or description fields defined by the user. Read more about User Entities.
0The number of tweets this user has favorited in the account’s lifetime. British spelling used in the field name for historical reasons.
Perspectival. When true, indicates that the authenticating user has issued a follow request to this protected user account.
Deprecated. Perspectival. When true, indicates that the authenticating user is following this user. Some false negatives are possible when set to “false,” but these false negatives are increasingly being represented as “null” instead. See Discussion.
The number of followers this account currently has. Under certain conditions of duress, this field will temporarily indicate 0.
The number of users this account is following (AKA their “followings”). Under certain conditions of duress, this field will temporarily indicate 0.
When true, indicates that the user has enabled the possibility of geotagging their Tweets. This field must be true for the current user to attach geographic data when using POST statuses/update.
Int64 The integer representation of the unique identifier for this User. 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_str for fetching the identifier to stay on the safe side. See Twitter IDs, JSON and Snowflake.
The string representation of the unique identifier for this User. Implementations should use this rather than the large, possibly un-consumable integer in id.
When true, indicates that the user is a participant in Twitter’s translator community.
The BCP 47 code for the user’s self-declared user interface language. May or may not have anything to do with the content of their Tweets.
"lang": "en"
"lang": "msa"
"lang": "zh-cn"
The number of public lists that this user is a member of.
The user-defined location for this account’s profile. Not necessarily a location nor parseable. This field will occasionally be fuzzily interpreted by the Search service.
The name of the user, as they’ve defined it. Not necessarily a person’s name. Typically capped at 20 characters, but subject to change.
Deprecated. May incorrectly report “false” at times. Indicates whether the authenticated user has chosen to receive this user’s tweets by SMS. Discussion
The hexadecimal color chosen by the user for their background.
A HTTP-based URL pointing to the background image the user has uploaded for their profile.
A HTTPS-based URL pointing to the background image the user has uploaded for their profile.
When true, indicates that the user’s profile_background_image_url should be tiled when displayed.
The HTTPS-based URL pointing to the standard web representation of the user’s uploaded profile banner. By adding a final path element of the URL, you can obtain different image sizes optimized for specific displays. In the future, an API method will be provided to serve these URLs so that you need not modify the original URL. For size variations, please see User Profile Images and Banners.
A HTTP-based URL pointing to the user’s avatar image. See User Profile Images and Banners.
A HTTPS-based URL pointing to the user’s avatar image.
The hexadecimal color the user has chosen to display links with in their Twitter UI.
The hexadecimal color the user has chosen to display sidebar borders with in their Twitter UI.
The hexadecimal color the user has chosen to display sidebar backgrounds with in their Twitter UI.
The hexadecimal color the user has chosen to display text with in their Twitter UI.
When true, indicates the user wants their uploaded background image to be used.
When true, indicates that this user has chosen to protect their Tweets. See About Public and Protected Tweets.
The screen name, handle, or alias that this user identifies themselves with. screen_names are unique but subject to change. Use id_str as a user identifier whenever possible. Typically a maximum of 15 characters long, but some historical accounts may exist with longer names.
Indicates that the user would like to see media inline. Somewhat disused.
If possible, the user’s most recent tweet or retweet. In some circumstances, this data cannot be provided and this field will be omitted, null, or empty. Perspectival attributes within tweets embedded within users cannot always be relied upon. See Why are embedded objects stale or inaccurate?.
https://dev.twitter.com/docs/faq/#6981The number of tweets (including retweets) issued by the user.
A string describing the Time Zone this user declares themselves within.
A URL provided by the user in association with their profile.
The offset from GMT/UTC in seconds.
When true, indicates that the user has a verified account. See Verified Accounts.
When present, indicates a textual representation of the two-letter country codes this user is withheld from. See New Withheld Content Fields in API Responses.
When present, indicates whether the content being withheld is the “status” or a “user.” See New Withheld Content Fields in API Responses.
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.
Read Entities in Twitter Objects for a more comprehensive guide to how entities are used throughout Twitter objects.
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.
Represents hashtags which have been parsed out of the Tweet text.
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).
32Name of the hashtag, minus the leading ‘#’ character.
Represents media elements uploaded with the Tweet.
Type of uploaded media.
An object showing available sizes for the media file.
Information for a thumbnail-sized version of the media.
Height in pixels of this size.
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.
Width in pixels of this size.
Information for a large-sized version of the media.
Height in pixels of this size.
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.
Width in pixels of this size.
Information for a medium-sized version of the media.
Height in pixels of this size.
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.
Width in pixels of this size.
Information for a small-sized version of the media.
Height in pixels of this size.
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.
Width in pixels of this size.
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).
15Wrapped URL for the media link. This corresponds with the URL embedded directly into the raw Tweet text, and the values for the indices parameter.
An http:// URL pointing directly to the uploaded media file.
"media_url":"http:\/\/p.twimg.com\/AZVLmp-CIAAbkyy.jpg"
For media in direct messages, media_url is the same https URL as media_url_https and must be accessed via an authenticated twitter.com session or by signing a request with the user’s access token using OAuth 1.0A. You can see more details on the entities in DMs description. It is not possible to directly embed these images in a web page.
URL of the media to display to clients.
ID of the media expressed as a 64-bit integer.
ID of the media expressed as a string.
An expanded version of display_url. Links to the media display page.
An https:// URL pointing directly to the uploaded media file, for embedding on https pages.
"media_url_https":"https:\/\/p.twimg.com\/AZVLmp-CIAAbkyy.jpg"
For media in direct messages, media_url_https must be accessed via an authenticated twitter.com session or by signing a request with the user’s access token using OAuth 1.0A. You can see more details on the entities in DMs description. It is not possible to directly embed these images in a web page.
For Tweets containing media that was originally associated with a different tweet, this ID points to the original Tweet.
For Tweets containing media that was originally associated with a different tweet, this string-based ID points to the original Tweet.
Represents URLs included in the text of a Tweet or within textual fields of a user object.
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.
32Wrapped URL, corresponding to the value embedded directly into the raw Tweet text, and the values for the indices parameter.
Version of the URL to display to clients.
Expanded version of display_url.
Represents other Twitter users mentioned in the text of the Tweet.
Display name of the referenced user.
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.
4Screen name of the referenced user.
ID of the mentioned user, as an integer.
Id of the mentioned user, as a string.