Twitter Rest API v1.1

This spec is For Speca Platform Demo Purposes ONLY

Base URI

https://api.twitter.com/1.1
API Methods
Timelines

Timelines are collections of Tweets, ordered with the most recent first.

GET /statuses/mentions_timeline
GET /statuses/user_timeline
GET /statuses/home_timeline
GET /statuses/retweets_of_me
Recent mentions
GET /statuses/mentions_timeline

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

count
string optional

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.

Example:
200
since_id
string optional

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.

Example:
12345
max_id
string optional

Returns results with an ID less than (that is, older than) or equal to the specified ID.

Example:
54321
trim_user
boolean optional

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.

Example:
true
contributor_details
boolean optional

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.

Example:
true
include_entities
boolean optional

The entities node will be disincluded when set to false.

Example:
false

Responses

200 OK
Body
Array of Tweet
User timeline
GET /statuses/user_timeline

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

user_id
string optional

The ID of the user for whom to return results for.

Example:
12345
screen_name
string optional

The screen name of the user for whom to return results for.

Example:
noradio
since_id
string optional

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.

Example:
12345
count
string optional

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.

Example:
100
max_id
string optional

Returns results with an ID less than (that is, older than) or equal to the specified ID.

trim_user
boolean optional

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.

Example:
true
exclude_replies
boolean optional

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.

Example:
true
contributor_details
boolean optional

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.

Example:
true
include_rts
boolean optional

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.

Example:
true

Responses

200 OK
Body
Array of Tweet
Home timeline
GET /statuses/home_timeline

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

count
string optional

Specifies the number of records to retrieve. Must be less than or equal to 200. Defaults to 20.

Example:
25
since_id
string optional

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.

Example:
12345
max_id
string optional

Returns results with an ID less than (that is, older than) or equal to the specified ID.

Example:
54321
trim_user
boolean optional

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.

Example:
true
exclude_replies
boolean optional

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.

Example:
true
contributor_details
boolean optional

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.

Example:
true
include_entities
boolean optional

The entities node will be disincluded when set to false.

Example:
true

Responses

200 OK
Body
Array of Tweet
Retweets
GET /statuses/retweets_of_me

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

count
string optional

Specifies the number of records to retrieve. Must be less than or equal to 100. If omitted, 20 will be assumed.

Example:
5
since_id
string optional

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.

Example:
1223
max_id
string optional

Returns results with an ID less than (that is, older than) or equal to the specified ID.

Example:
54321
trim_user
string optional

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.

Example:
"true"
include_entities
string optional

The tweet entities node will be disincluded when set to false.

Example:
"false"
include_user_entities
string optional

The user entities node will be disincluded when set to false.

Example:
"false"

Responses

200 OK
Body
Array of Tweet
Tweets

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.

GET /statuses/retweets/{id}
GET /statuses/show.json
POST /statuses/destroy/{id}
POST /statuses/update.json
POST /statuses/retweet/{id}.json
POST /statuses/update_with_media
Get retweets
GET /statuses/retweets/{id}

Returns a collection of the 100 most recent retweets of the tweet specified by the id parameter.

Path variables

id
string required

The numerical ID of the desired status.

Example:
12345

Request parameters

count
string optional

Specifies the number of records to retrieve. Must be less than or equal to 100.

Example:
12
trim_user
string optional

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.

Example:
1

Responses

200 OK
Body
Array of Tweet
Get tweet
GET /statuses/show.json

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

id
string required

The numerical ID of the desired Tweet.

Example:
123
trim_user
string optional

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.

Example:
"true"
include_my_retweet
string optional

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.

Example:
"true"
include_entities
string optional

The entities node will be disincluded when set to false.

Example:
false

Responses

200 OK

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
}
Delete tweet
POST /statuses/destroy/{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

id
string required

The numerical ID of the desired status.

Request parameters

trim_user
string optional

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.

Example:
1

Responses

200 OK

Returns destroyed status

Body
Create tweet
POST /statuses/update.json

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

display_coordinates
boolean optional

Whether or not to put a pin on the exact coordinates a tweet has been sent from

Example:
true
trim_user
boolean optional

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.

Example:
true

Request body

Object
status
string

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.

Example:
Maybe he'll finally find his keys. @peterfalk
in_reply_to_status_id
number

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.

Example:
12
lat
number

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.

Example:
37.7821120598956
long
number

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.

Example:
-122.400612831116
place_id
string

A place in the world. These IDs can be retrieved from GET geo/reverse_geocode.

Example:
df51dec6f4ee2b2c

Responses

201 Created

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
Retweet a tweet
POST /statuses/retweet/{id}.json

Retweets 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

id
string required

The numerical ID of the desired status.

Example:
123

Request parameters

trim_user
string optional

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.

Example:
true

Request body

None

Responses

200 OK
Body
Create tweet with media
POST /statuses/update_with_media

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 in X-MediaRateLimit-Reset.
  • X-MediaRateLimit-Remaining - The remaining pieces of media the current user may upload before the time indicated in X-MediaRateLimit-Reset.
  • X-MediaRateLimit-Reset - A UTC-based timestamp (in seconds) indicating when X-MediaRateLimit-Remaining will reset to the value in X-MediaRateLimit-Limit and 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--
Object
status
string

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.

Example:
Hello 2012-09-07 15:51:41.375247 -0700 PDT
media[]
string

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.

possibly_sensitive
string

Set to true for content which may not be suitable for every audience.

in_reply_to_status_id
string

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.

lat
string

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.

Example:
37.7821120598956
long
string

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.

place_id
string

A place in the world identified by a Twitter place ID. Place IDs can be retrieved from geo/reverse_geocode.

Example:
df51dec6f4ee2b2c
display_coordinates
string

Whether or not to put a pin on the exact coordinates a tweet has been sent from.

Example:
true

Responses

200 OK
Body
Search

Find relevant Tweets based on queries performed by your users.

GET /search/tweets
GET /search/tweets

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

q
string optional

A UTF-8, URL-encoded search query of 1,000 characters maximum, including operators. Queries may additionally be limited by complexity.

Example:
@noradio
geocode
string optional

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

Example:
37.781157,-122.398720,1mi
lang
string optional

Restricts tweets to the given language, given by an ISO 639-1 code. Language detection is best-effort.

Example:
eu
locale
string optional

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.

Example:
ja
result_type
string optional

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 response
  • popular: return only the most popular results in the response.
Example:
mixed
count
string optional

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.

Example:
20
until
string optional

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.

Example:
2012-09-01
since_id
string optional

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.

Example:
12345
max_id
string optional

Returns results with an ID less than (that is, older than) or equal to the specified ID.

Example:
54321
include_entities
string optional

The entities node will be disincluded when set to false.

Example:
"false"
callback
string optional

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.

Example:
processTweets

Responses

200 OK
Body
Array of Tweet
Data Reference
Coordinates
Object
coordinates
Array of number

The longitude and latitude of the Tweet's location, as an collection in the form of [longitude, latitude].

Example:
-97.51087576
type
string

The type of data encoded in the coordinates property. This will be "Point" for Tweet coordinates fields.

Example:
Point
Types: Tweet
Contributors

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.

Object
id
string

The integer representation of the ID of the user who contributed to this Tweet.

Example:
819797
id_str
string

The string representation of the ID of the user who contributed to this Tweet.

Example:
819797
screen_name
string

The screen name of the user who contributed to this Tweet.

Example:
"episod"
Types: Tweet
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.

Object
annotations
unknown

Unused. Future/beta home for status annotations.

contributors
Array of Contributors

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.

coordinates

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).

created_at
string

UTC time when this Tweet was created.

Example:
"Wed Aug 27 13:08:45 +0000 2008"
current_user_retweet
Object

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.

id
number
Example:
26815871309
id_str
string
Example:
26815871309
entities
Object

Entities which have been parsed out of the text of the Tweet. Additionally see Entities in Twitter Objects.

hashtags
Array of unknown
urls
Array of unknown
user_mentions
Array of unknown
favorite_count
number

Indicates approximately how many times this Tweet has been "favorited" by Twitter users.

Example:
1
favorited
boolean

Indicates whether this Tweet has been favorited by the authenticating user.

Example:
false
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 medium will be streamed on none, low, and medium streams. See this announcement for more information.

Example:
medium
geo
unknown

Deprecated. Nullable. Use the "coordinates" field instead.

id
number

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.

Example:
1
id_str
string

The string representation of the unique identifier for this Tweet. Implementations should use this rather than the large integer in id. Discussion.

Example:
114749583439036416
in_reply_to_screen_name
string

If the represented Tweet is a reply, this field will contain the screen name of the original Tweet's author.

Example:
twitterapi
in_reply_to_status_id
number

If the represented Tweet is a reply, this field will contain the integer representation of the original Tweet's ID.

Example:
114749583439036420
in_reply_to_status_id_str
string

If the represented Tweet is a reply, this field will contain the string representation of the original Tweet's ID.

Example:
114749583439036416
in_reply_to_user_id
number

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:
1
lang
string

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.

place

When present, indicates that the tweet is associated (but not necessarily originating from) a Place.

possibly_sensitive
boolean

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:
false
scopes
Object

A set of key-value pairs indicating the intended contextual delivery of the containing Tweet. Currently used by Twitter's Promoted Products.

followers
boolean
Example:
false
retweet_count
number

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+"

Example:
1
retweeted
boolean

Perspectival. Indicates whether this Tweet has been retweeted by the authenticating user.

Example:
false
retweeted_status

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 web.

Example:
"\u003Ca href=\"http:\/\/itunes.apple.com\/us\/app\/twitter\/id409789998?mt=12\" rel=\"nofollow\"\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:
Tweet Button, Follow Button, and Web Intents javascript now support SSL http:\/\/t.co\/9fbA0oYy ^TS
truncated
boolean

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).

Example:
false
user

The user who posted this Tweet. Perspectival attributes embedded within this object are unreliable. See Why are embedded objects stale or inaccurate?.

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:
false
withheld_in_countries
Array of string

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.
Example:
["GR", "HK", "MY"]
withheld_scope
string

When present, indicates whether the content being withheld is the "status" or a "user." See New Withheld Content Fields in API Responses.

Example:
status
Place

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.

Object
bounding_box
Object

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"}

coordinates
Array of number

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.

Example:
1
type
string

The type of data encoded in the coordinates property. This will be "Polygon" for bounding boxes.

Example:
Polygon
country
string

Name of the country containing this place.

Example:
United States
country_code
string

Shortened country code representing the country containing this place.

Example:
US
full_name
string

Full human-readable representation of the place's name.

Example:
Washington, DC
id
string

ID representing this place. Note that this is represented as a string, not an integer.

Example:
01fbe706f872cb32
name
string

Short human-readable representation of the place's name.

Example:
Washington
place_type
string

The type of location represented by this place.

Example:
city
url
string

URL representing the location of additional place metadata for this place.

Example:
http://api.twitter.com/1/geo/id/01fbe706f872cb32.json
Types: Tweet
Geo Place Attributes

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.

Object
street_address
string
Example:
795 Folsom St
app:id
string

An ID or comma separated list of IDs representing the place in the applications place database.

Example:
210176
twitter
string

twitter screen-name, without @

Example:
twitter
locality
string

the city the place is in

region
string

the administrative region the place is in

iso3
string

the country code

postl_code
string

in the preferred local format for the place

url
string

official/canonical URL for place

phone
string

in the preferred local format for the place, include long distance code

Types: Place
User

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.

Object
contributors_enabled
boolean

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.

Example:
false
created_at
string

The UTC datetime that the user account was created on Twitter.

Example:
"Mon Nov 29 21:18:15 +0000 2010"
default_profile
boolean

When true, indicates that the user has not altered the theme or background of their user profile.

Example:
false
default_profile_image
boolean

When true, indicates that the user has not uploaded their own avatar and a default egg avatar is used instead.

Example:
false
description
string

The user-defined UTF-8 string describing their account.

Example:
"The Real Twitter API."
entities
Object

Entities which have been parsed out of the url or description fields defined by the user. Read more about User Entities.

url
Object
urls
Array
Object
url
string
Example:
http://dev.twitter.com
expanded_url
unknown
indices
Array of number
Example:
0
description
Object
urls
Array of unknown
favourites_count
number

The number of tweets this user has favorited in the account's lifetime. British spelling used in the field name for historical reasons.

Example:
13
follow_request_sent
boolean

Perspectival. When true, indicates that the authenticating user has issued a follow request to this protected user account.

Example:
false
following
boolean

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.

Example:
false
followers_count
number

The number of followers this account currently has. Under certain conditions of duress, this field will temporarily indicate 0.

Example:
1
friends_count
number

The number of users this account is following (AKA their "followings"). Under certain conditions of duress, this field will temporarily indicate 0.

Example:
32
geo_enabled
boolean

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.

Example:
false
id
number

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.

Example:
18200
id_str
string

The string representation of the unique identifier for this User. Implementations should use this rather than the large, possibly un-consumable integer in id.

Example:
"6253282"
is_translator
boolean

When true, indicates that the user is a participant in Twitter's translator community.

Example:
false
lang
string

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"

Example:
"zh-cn"
listed_count
string

The number of public lists that this user is a member of.

Example:
9274
location
string

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.

Example:
"San Francisco, CA"
name
string

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.

Example:
"Twitter API"
notifications
boolean

Deprecated. May incorrectly report "false" at times. Indicates whether the authenticated user has chosen to receive this user's tweets by SMS. Discussion

Example:
false
profile_background_color
string

The hexadecimal color chosen by the user for their background.

Example:
"e8f2f7"
profile_background_image_url
string

A HTTP-based URL pointing to the background image the user has uploaded for their profile.

Example:
"http:\/\/a2.twimg.com\/profile_background_images\ /229557229\/twitterapi-bg.png"
profile_background_image_url_https
string

A HTTPS-based URL pointing to the background image the user has uploaded for their profile.

Example:
"https:\/\/si0.twimg.com\/profile_background_images\ /229557229\/twitterapi-bg.png"
profile_background_tile
boolean

When true, indicates that the user's profile_background_image_url should be tiled when displayed.

Example:
false
profile_banner_url
string

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.

Example:
"https://si0.twimg.com/profile_banners/819797/1348102824"
profile_image_url
string

A HTTP-based URL pointing to the user's avatar image. See User Profile Images and Banners.

Example:
"http:\/\/a2.twimg.com\/profile_images\/1438634086\ /avatar_normal.png"
profile_image_url_https
string

A HTTPS-based URL pointing to the user's avatar image.

Example:
"https:\/\/si0.twimg.com\/profile_images\/1438634086\ /avatar_normal.png"
profile_link_color
string

The hexadecimal color the user has chosen to display links with in their Twitter UI.

Example:
"0094C2"
profile_sidebar_border_color
string

The hexadecimal color the user has chosen to display sidebar borders with in their Twitter UI.

Example:
"0094C2"
profile_sidebar_fill_color
string

The hexadecimal color the user has chosen to display sidebar backgrounds with in their Twitter UI.

Example:
"a9d9f1"
profile_text_color
string

The hexadecimal color the user has chosen to display text with in their Twitter UI.

Example:
"437792"
profile_use_background_image
boolean

When true, indicates the user wants their uploaded background image to be used.

Example:
false
protected
boolean

When true, indicates that this user has chosen to protect their Tweets. See About Public and Protected Tweets.

Example:
false
screen_name
string

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.

Example:
"twitterapi"
show_all_inline_media
boolean

Indicates that the user would like to see media inline. Somewhat disused.

Example:
false
status

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?.

Example:
https://dev.twitter.com/docs/faq/#6981
statuses_count
number

The number of tweets (including retweets) issued by the user.

Example:
42
time_zone
string

A string describing the Time Zone this user declares themselves within.

Example:
"Pacific Time (US & Canada)"
url
string

A URL provided by the user in association with their profile.

Example:
"http:\/\/dev.twitter.com"
utc_offset
number

The offset from GMT/UTC in seconds.

Example:
-18000
verified
boolean

When true, indicates that the user has a verified account. See Verified Accounts.

Example:
false
withheld_in_countries
string

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.

Example:
"GR, HK, MY"
withheld_scope
string

When present, indicates whether the content being withheld is the "status" or a "user." See New Withheld Content Fields in API Responses.

Example:
"user"
Types: Tweet
Entities

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.

Object
hashtags
Array

Represents hashtags which have been parsed out of the Tweet text.

Object
indices
Array of number

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).

Example:
32
text
string

Name of the hashtag, minus the leading '#' character.

Example:
lol
media
Array

Represents media elements uploaded with the Tweet.

Object
type
string

Type of uploaded media.

Example:
photo
sizes
Object

An object showing available sizes for the media file.

thumb
Object

Information for a thumbnail-sized version of the media.

h
number

Height in pixels of this size.

Example:
150
resize
string

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.

Example:
crop
w
number

Width in pixels of this size.

Example:
150
large
Object

Information for a large-sized version of the media.

h
number

Height in pixels of this size.

Example:
150
resize
string

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.

Example:
crop
w
number

Width in pixels of this size.

Example:
150
medium
Object

Information for a medium-sized version of the media.

h
number

Height in pixels of this size.

Example:
150
resize
string

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.

Example:
crop
w
number

Width in pixels of this size.

Example:
150
small
Object

Information for a small-sized version of the media.

h
number

Height in pixels of this size.

Example:
150
resize
string

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.

Example:
crop
w
number

Width in pixels of this size.

Example:
150
indices
Array of number

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).

Example:
15
url
string

Wrapped URL for the media link. This corresponds with the URL embedded directly into the raw Tweet text, and the values for the indices parameter.

Example:
http://t.co/rJC5Pxsu
media_url
string

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.

Example:
http://p.twimg.com/AZVLmp-CIAAbkyy.jpg
display_url
string

URL of the media to display to clients.

Example:
pic.twitter.com/rJC5Pxsu
id
number

ID of the media expressed as a 64-bit integer.

Example:
114080493040967680
id_str
string

ID of the media expressed as a string.

Example:
114080493040967680
expanded_url
string

An expanded version of display_url. Links to the media display page.

Example:
http://twitter.com/yunorno/status/114080493036773378/photo/1
media_url_https
string

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.

Example:
https://p.twimg.com/AZVLmp-CIAAbkyy.jpg
source_status_id
number

For Tweets containing media that was originally associated with a different tweet, this ID points to the original Tweet.

Example:
205282515685081100
source_status_id_str
string

For Tweets containing media that was originally associated with a different tweet, this string-based ID points to the original Tweet.

Example:
"205282515685081088"
urls
Array

Represents URLs included in the text of a Tweet or within textual fields of a user object.

Object
indices
Array of number

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.

Example:
32
url
string

Wrapped URL, corresponding to the value embedded directly into the raw Tweet text, and the values for the indices parameter.

Example:
http://t.co/IOwBrTZR
display_url
string

Version of the URL to display to clients.

Example:
youtube.com/watch?v=oHg5SJ…
expanded_url
string

Expanded version of display_url.

Example:
http://www.youtube.com/watch?v=oHg5SJYRHA0
user_mentions
Array

Represents other Twitter users mentioned in the text of the Tweet.

Object
name
string

Display name of the referenced user.

Example:
Twitter API
indices
Array of number

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.

Example:
4
screen_name
string

Screen name of the referenced user.

Example:
twitterapi
id
number

ID of the mentioned user, as an integer.

Example:
6253282
id_str
string

Id of the mentioned user, as a string.

Example:
6253282
description
Object
urls
Array of unknown