POST statuses/update

Updated on Mon, 2014-06-02 14:02

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.

Resource URL

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

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.

possibly_sensitive optional

If you upload Tweet media that might be considered sensitive content such as nudity, violence, or medical procedures, you should set this value to true. See Media setting and best practices for more context. Defaults to false.

Example Values: true

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

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

Example Request

POST	`https://api.twitter.com/1.1/statuses/update.json`
POST Data	`status=Maybe%20he%27ll%20finally%20find%20his%20keys.%20%23peterfalk`

```
{
```
```
  "coordinates": null,
```
```
  "favorited": false,
```

  "created_at": "Wed Sep 05 00:37:15 +0000 2012",

```
  "truncated": false,
```
```
  "id_str": "243145735212777472",
```
```
  "entities": {
```
```
    "urls": [
```
```
 
```
```
    ],
```
```
    "hashtags": [
```
```
      {
```
```
        "text": "peterfalk",
```
```
        "indices": [
```
```
          35,
```
```
          45
```
```
        ]
```
```
      }
```
```
    ],
```
```
    "user_mentions": [
```
```
 
```
```
    ]
```
```
  },
```
```
  "in_reply_to_user_id_str": null,
```

  "text": "Maybe he'll finally find his keys. #peterfalk",

```
  "contributors": null,
```
```
  "retweet_count": 0,
```
```
  "id": 243145735212777472,
```
```
  "in_reply_to_status_id_str": null,
```
```
  "geo": null,
```
```
  "retweeted": false,
```
```
  "in_reply_to_user_id": null,
```
```
  "place": null,
```
```
  "user": {
```
```
    "name": "Jason Costa",
```

    "profile_sidebar_border_color": "86A4A6",

    "profile_sidebar_fill_color": "A0C5C7",

```
    "profile_background_tile": false,
```

    "profile_image_url": "http://a0.twimg.com/profile_images/1751674923/new_york_beard_normal.jpg",

    "created_at": "Wed May 28 00:20:15 +0000 2008",

```
    "location": "",
```
```
    "is_translator": true,
```
```
    "follow_request_sent": false,
```
```
    "id_str": "14927800",
```
```
    "profile_link_color": "FF3300",
```
```
    "entities": {
```
```
      "url": {
```
```
        "urls": [
```
```
          {
```

            "expanded_url": "http://www.jason-costa.blogspot.com/",

            "url": "http://t.co/YCA3ZKY",

```
            "indices": [
```
```
              0,
```
```
              19
```
```
            ],
```

            "display_url": "jason-costa.blogspot.com"

```
          }
```
```
        ]
```
```
      },
```
```
      "description": {
```
```
        "urls": [
```
```
 
```
```
        ]
```
```
      }
```
```
    },
```
```
    "default_profile": false,
```
```
    "contributors_enabled": false,
```
```
    "url": "http://t.co/YCA3ZKY",
```
```
    "favourites_count": 883,
```
```
    "utc_offset": -28800,
```
```
    "id": 14927800,
```

    "profile_image_url_https": "https://si0.twimg.com/profile_images/1751674923/new_york_beard_normal.jpg",

    "profile_use_background_image": true,

```
    "listed_count": 150,
```
```
    "profile_text_color": "333333",
```
```
    "protected": false,
```
```
    "lang": "en",
```
```
    "followers_count": 8760,
```

    "time_zone": "Pacific Time (US & Canada)",

    "profile_background_image_url_https": "https://si0.twimg.com/images/themes/theme6/bg.gif",

```
    "verified": false,
```

    "profile_background_color": "709397",

```
    "notifications": false,
```

    "description": "Platform at Twitter",

```
    "geo_enabled": true,
```
```
    "statuses_count": 5532,
```
```
    "default_profile_image": false,
```
```
    "friends_count": 166,
```

    "profile_background_image_url": "http://a0.twimg.com/images/themes/theme6/bg.gif",

```
    "show_all_inline_media": true,
```
```
    "screen_name": "jasoncosta",
```
```
    "following": false
```
```
  },
```

  "source": "<a href=\"http://jason-costa.blogspot.com\" rel=\"nofollow\">My Shiny App</a>",

```
  "in_reply_to_screen_name": null,
```
```
  "in_reply_to_status_id": null
```
```
}
```

Rate Limited?	No
Authentication	Requires user context
Response Formats	json
HTTP Methods	POST
Resource family	statuses
Response Object	Tweets
API Version	v1.1

POST statuses/update

Resource URL

Parameters

Extended description

Example Request

Resource Information

OAuth tool

Tags