<< Back to Twitter API Documentation

 

Twitter REST API Method: statuses/update

Updates the authenticating user's status.  Requires the status parameter specified below.  Request must be a POST.  A status update with text identical to the authenticating user's current status will be ignored to prevent duplicates.

URL:

http://twitter.com/statuses/update.format

 

Formats: 

xml, json

 

HTTP Method(s):

POST

 

Requires Authentication (about authentication):

true

 

API rate limited (about rate limiting):

false

 

Parameters:

• status.  Required.  The text of your status update. URL encode as necessary. Statuses over 140 characters will be forceably truncated.
• in_reply_to_status_id.  Optional. 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. Optional. The location's latitude that this tweet refers to.
  • Note: The valid ranges for latitude is -90.0 to +90.0 (North 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 long parameter with this tweet.
• long.  Optional. The location's longitude that this tweet refers to.
  • Note: 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 with this tweet.

 

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 a duplicate update. With each update attempt, the application compares the update text with the authenticating user's last successful update, and ignores any attempts that would result in duplication. Therefore, a user cannot submit the same status twice in a row. The status element in the response will return the id from the previously successful update if a duplicate has been silently ignored.

 

Geolocation:

• Any geolocation 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 XML response uses GeoRSS to encode the latitude and longitude. <georss:point> encodes as latitude, space, and longitude (see the response below for an example).  For JSON, the response mostly uses conventions laid forth in GeoJSON.  Unfortunately, the 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.  This will be repaired in version 2 of the Twitter API.).  Our JSON renders as:

"geo":

{

"type":"Point",

"coordinates":[37.78029, -122.39697]

}

• If there is no geolocated information for a status, then there will be an empty <geo/> or "geo" : {}. 
• 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.

 

Response (about return values): 

          XML example:

<?xml version="1.0" encoding="UTF-8"?>

<status>

<created_at>Tue Apr 07 22:52:51 +0000 2009</created_at>

<id>1472669360</id>

<text>At least I can get your humor through tweets. RT @abdur: I don't mean this in a bad way, but genetically speaking your a cul-de-sac.</text>

<source><a href="http://www.tweetdeck.com/">TweetDeck</a></source>

<truncated>false</truncated>

<in_reply_to_status_id>1472669230</in_reply_to_status_id>

<in_reply_to_user_id>10759032</in_reply_to_user_id>

<favorited>false</favorited>

<in_reply_to_screen_name></in_reply_to_screen_name>

<geo xmlns:georss="http://www.georss.org/georss">

<georss:point>37.78029 -122.39697</georss:point>

</geo>

<user>

<id>1401881</id>

<name>Doug Williams</name>

<screen_name>dougw</screen_name>

<location>San Francisco, CA</location>

<description>Twitter API Support. Internet, greed, users, dougw and opportunities are my passions.</description>

<profile_image_url>http://s3.amazonaws.com/twitter_production/profile_images/59648642/avatar_normal.png</profile_image_url>

<url>http://www.igudo.com</url>

<protected>false</protected>

<followers_count>1027</followers_count>

<profile_background_color>9ae4e8</profile_background_color>

<profile_text_color>000000</profile_text_color>

<profile_link_color>0000ff</profile_link_color>

<profile_sidebar_fill_color>e0ff92</profile_sidebar_fill_color>

<profile_sidebar_border_color>87bc44</profile_sidebar_border_color>

<friends_count>293</friends_count>

<created_at>Sun Mar 18 06:42:26 +0000 2007</created_at>

<favourites_count>0</favourites_count>

<utc_offset>-18000</utc_offset>

<time_zone>Eastern Time (US & Canada)</time_zone>

<profile_background_image_url>http://s3.amazonaws.com/twitter_production/profile_background_images/2752608/twitter_bg_grass.jpg</profile_background_image_url>

<profile_background_tile>false</profile_background_tile>

<statuses_count>3390</statuses_count>

<notifications>false</notifications>

<following>false</following>

<geo_enabled>true</geo_enabled>

<verified>true</verified>

</user>

</status>

 

Usage examples: 

cURL (about cURL):

curl -u user:password -d "status=playing with cURL and the Twitter API" http://twitter.com/statuses/update.xml

 

          Do you have an example to share in the language of your choice? Please share!