POST statuses/update

Updated on Wed, 2012-04-18 10:40

Updates the authenticating user's 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.

Resource URL

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

Parameters

status required

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.

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 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 Values: 37.7821120598956

long optional

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 Values: -122.400612831116

place_id optional

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

Example Values: df51dec6f4ee2b2c

display_coordinates optional

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

Example Values: true

trim_user 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 Values: true

include_entities optional

When set to either true, t or 1, each tweet will include a node called "entities,". This node offers a variety of metadata about the tweet in a discreet structure, including: user_mentions, urls, and hashtags. While entities are opt-in on timelines at present, they will be made a default component of output in the future. See Tweet Entities for more detail on entities.

Example Values: true

Extended description

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

Example Request

POST

https://api.twitter.com/1/statuses/update.json

POST Data

status=Maybe%20he%27ll%20finally%20find%20his%20keys.%20%23peterfalk&trim_user=true&include_entities=true

  1. {
  2.   "coordinates": null,
  3.   "created_at": "Fri Jun 24 17:43:26 +0000 2011",
  4.   "truncated": false,
  5.   "favorited": false,
  6.   "id_str": "84315710834212866",
  7.   "entities": {
  8.     "urls": [
  9.  
  10.     ],
  11.     "hashtags": [
  12.       {
  13.         "text": "peterfalk",
  14.         "indices": [
  15.           35,
  16.           45
  17.         ]
  18.       }
  19.     ],
  20.     "user_mentions": [
  21.  
  22.     ]
  23.   },
  24.   "in_reply_to_user_id_str": null,
  25.   "contributors": null,
  26.   "text": "Maybe he'll finally find his keys. #peterfalk",
  27.   "retweet_count": 0,
  28.   "id": 84315710834212866,
  29.   "in_reply_to_status_id_str": null,
  30.   "geo": null,
  31.   "retweeted": false,
  32.   "in_reply_to_user_id": null,
  33.   "source": "<a href=\"http://sites.google.com/site/yorufukurou/\" rel=\"nofollow\">YoruFukurou</a>",
  34.   "in_reply_to_screen_name": null,
  35.   "user": {
  36.     "id_str": "819797",
  37.     "id": 819797
  38.   },
  39.   "place": null,
  40.   "in_reply_to_status_id": null
  41. }