<< 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.  [COMING SOON]
  • 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.  [COMING SOON]
  • 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 [COMING SOON]:

• 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 uses conventions laid forth in GeoJSON which looks like 

"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" : {}. 
• Currently, all geolocated information will be removed after seven days. 

 

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>

<!-- Not yet part of the current payload.  [COMING SOON] -->

<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> <!-- Not yet part of the current payload.  [COMING SOON] -->

<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!