O'Reilly Network: Twitter API Reference: Appendix

Status Methods

Delete a Tweet

Removes a single status update from the Twitter timeline.

Path		`/statuses/destroy/``id``.xml`
Requires authentication		Yes (the account owns the existing update).
Charged against rate limit		No.
HTTP method type		POST or DELETE.
Required parameters
	`id`	Provides the record ID for an existing status update owned by the authenticating user. The `id` parameter is passed as part of the URL request.
Successful output		See the section called “Publishing”.

View Followers

Returns a list of people who follow you.

Path		`/statuses/followers.xml`
Requires authentication		Yes (authenticating user must be allowed by the author to view a private list of followers).
Charged against rate limit		Yes.
HTTP method type		GET.
Optional parameters
	`id`	Indicates the user ID or username of the Twitter account whose follower list you want to view. The `id` parameter is passed as part of the URL request: `/statuses/followers/``id``.xml`.
	`page`	Indicates which page of 100 users to return. The default is 1 (users most recently created).
Successful output		See the section called “The Follow Network”.

View Members Being Followed

Returns a list of people you follow.

Path		`/statuses/friends.xml`
Requires authentication		Yes, if the account is private (authenticating user must be allowed by the author to view the list of friends).
Charged against rate limit		Yes.
HTTP method type		GET.
Optional parameters
	`id`	Indicates the user ID or username of the Twitter account whose following list you want to view. The `id` parameter is passed as part of the URL request: `/statuses/friends/``id``.xml`.
	`page`	Indicates which page of 100 users to return. The default is 1 (users most recently followed).
Successful output		See the section called “The Follow Network”.

Note

There are newer methods that allow you to get the entire list of followers and friends as user IDs. No other information is included in the Twitter API response, but it does save on pagination. See the section called “Get All Followers” and the section called “Get All Friends”.

View a Friends Timeline

Returns the most recent status updates made by people you follow.

Path		`/statuses/friends_timeline.xml`
Requires authentication		Yes.
Charged against rate limit		Yes.
HTTP method type		GET.
Optional parameters
	`since`	Ignores information older than the specified time (which must be within the last 24 hours). The value must be encoded in the format “Mon, 3 Nov 2008 18:39:12 GMT”.
	`since_id`	Returns only the most recent updates (those made since the specified record ID was created).
	`count`	Limits the most recent status updates to the number of records specified. The maximum count is 200, and the default is 20.
	`page`	Indicates which page of 20 items to return. The default is 1 (the most recent status updates).
Successful output		See the section called “The Information Stream”.

View the Public Timeline

Returns the most recent status updates from public accounts with custom pictures.

Path		`/statuses/public_timeline.xml`
Requires authentication		No.
Charged against rate limit		No.
HTTP method type		GET.
Successful output		See the section called “The Information Stream”.

View Replies

Returns the most recent status updates from people who have replied to you.

Path		`/statuses/replies.xml`
Requires authentication		Yes (replies are to the authenticating user).
Charged against rate limit		Yes.
HTTP method type		GET.
Optional parameters
	`since`	Ignores information older than the specified time (which must be within the last 24 hours). The value must be encoded in the format “Mon, 3 Nov 2008 18:39:12 GMT”.
	`since_id`	Returns only the most recent updates (those made since the specified record ID was created).
	`count`	Limits the most recent replies to the number of records specified. The maximum count is 200, and the default is 20.
	`page`	Indicates which page of 20 items to return. The maximum value is currently 40, and the default is 1 (the most recent status updates).
Successful output		See the section called “The Information Stream”.

Show a Tweet

Returns a single status update with the given ID.

Path		`/statuses/show/``id``.xml`
Requires authentication		Yes, if the status update is private (authenticating user must be allowed by the author to view the text).
Charged against rate limit		Yes.
HTTP method type		GET.
Required parameters
	`id`	Provides the record ID for an existing status update owned by the authenticating user. The `id` parameter is passed as part of the URL request.
Successful output		See the section called “The Information Stream”.

Post a Tweet

Creates a new status update authored by you.

Path		`/statuses/update.xml`
Requires authentication		Yes (this account owns the status update).
Charged against rate limit		No.
HTTP method type		POST.
Required parameters
	`status`	Indicates the text used to update the authenticating user’s status. This string is limited to 140 characters after URL encoding.
Optional parameters
	`in_reply_to_status_id`	Provides the record ID of an existing status update to which the new update will be attached.
	`source`	Identifies the name of the tool used to publish the tweet (as in “web” or “twitterrific”).
Successful output		See the section called “Publishing”.

View an Individual Timeline

Returns the most recent status updates for a specific account.

Path		`/statuses/user_timeline/``id``.xml`
Requires authentication		Yes, if the account is private (authenticating user must be allowed by the author to view the timeline).
Charged against rate limit		Yes.
HTTP method type		GET.
Required parameters		None, if authenticated (Twitter assumes the authenticating user is the `id`).
Optional parameters
	`id`	Provides the user ID or username for the Twitter account whose timeline you want to view. The `id` parameter is passed as part of the URL request.
	`since`	Ignores information older than the specified time (which must be within the last 24 hours). The value must be encoded in the format “Mon, 3 Nov 2008 18:39:12 GMT”.
	`since_id`	Returns only the most recent updates (those made since the specified record ID was created).
	`count`	Limits the most recent status updates to the number of records specified. The maximum count is 200, and the default is 20.
	`page`	Indicates which page of 20 items to return. The default is 1 (the most recent status updates).
Successful output		See the section called “The Information Stream”.

Users Methods

Show Member Profile

Returns your profile and statistical details.

Path		`/users/show/``id``.xml`
Requires authentication		Yes, if the account is private (authenticating user must be allowed by the author to view the profile).
Charged against rate limit		Yes.
HTTP method type		GET.
Required parameters		One of the following is required:
	`id` or `email`	Indicates the user ID or username of the Twitter member whose profile you want to view. The `id` parameter is passed as part of the URL request. An email address can be used if you do not know the user ID or username.
	`user_id`	Accepts the user ID of an existing Twitter member as a parameter, to help disambiguate when `screen_name` is a number. This parameter is passed as a query string variable.
	`screen_name`	Accepts the current `screen_name` of the Twitter member. This parameter is passed as a query string variable.
Successful output		See the section called “The Follow Network”.

Direct Message Methods

List Received Messages

Returns the most recent direct messages you have received.

Path		`/direct_messages.xml`
Requires authentication		Yes (list owned by authenticating user).
Charged against rate limit		Yes.
HTTP method type		GET.
Optional parameters
	`since`	Ignores information older than the specified time (which must be within the last 24 hours). The value must be encoded in the format “Mon, 3 Nov 2008 18:39:12 GMT”.
	`since_id`	Returns only the most recent updates (those made since the specified record ID was created).
	`page`	Indicates which page of 20 items to return. The default is 1 (the most recent messages).
	`count`	Limits the most recent messages to the number of records specified.
Successful output		See the section called “Communication”.

Delete a Message

Deletes an existing direct message received by you.

Path		`/direct_messages/destroy/``id``.xml`
Requires authentication		Yes (authenticating user owns the message).
Charged against rate limit		No.
HTTP method type		POST or DELETE.
Required parameters
	`id`	Provides the record ID for an existing message owned by the authenticating user. The `id` parameter is passed as part of the URL request.
Successful output		See the section called “Communication”.

Create a Message

Creates a new direct message sent from you to another user.

Path		`/direct_messages/new.xml`
Requires authentication		Yes (authenticating user authors the message).
Charged against rate limit		No.
HTTP method type		POST.
Required parameters
	`user`	Provides the user ID or username of the intended recipient of this message.
	`text`	The text message sent by the authenticating user. This string is limited to 140 characters after URL encoding.
Successful output		See the section called “Communication”.

List Sent Messages

Returns the most recent direct messages you have sent.

Path		`/direct_messages/sent.xml`
Requires authentication		Yes (list owned by authenticating user).
Charged against rate limit		Yes.
HTTP method type		GET.
Optional parameters
	`since`	Ignores information older than the specified time (which must be within the last 24 hours). The value must be encoded in the format “Mon, 3 Nov 2008 18:39:12 GMT”.
	`since_id`	Returns only the most recent updates (those made since the specified record ID was created).
	`page`	Indicates which page of 20 items to return. The default is 1 (the most recent messages).
	`count`	Limits the most recent messages to the number of records specified.
Successful output		See the section called “Communication”.

Friendship Methods

Follow a Member

Creates a new follow relationship between you and another Twitter member.

Path		`/friendships/create/``id``.xml`
Requires authentication		Yes.
Charged against rate limit		No.
HTTP method type		POST.
Required parameters
	`id`	Provides the user ID or username of an existing Twitter member not already followed by the authenticating user. The `id` parameter is passed as part of the URL request.
	`follow`	Adds device notifications for this friend, in addition to following that member. See the section called “Turn On Notification”.
Successful output		See the section called “The Follow Network”.

Unfollow a Member

Removes an existing follow relationship with another Twitter member.

Path		`/friendships/destroy/``id``.xml`
Requires authentication		Yes.
Charged against rate limit		No.
HTTP method type		POST.
Required parameters
	`id`	Provides the user ID or username of an existing Twitter member already being followed by the authenticating user. The `id` parameter is passed as part of the URL request.
Successful output		See the section called “The Follow Network”.

Confirm a Follow

Verifies whether one Twitter member is following another.

Path		`/friendships/exists.xml`
Requires authentication		Yes.
Charged against rate limit		Yes.
HTTP method type		GET.
Required parameters
	`user_a`	Indicates the user ID or username of the existing Twitter member whom you want to confirm is following `user_b`.
	`user_b`	Provides the user ID or username of the existing Twitter member whom you want to check if `user_a` is following.
Successful output		See the section called “The Follow Network”.

Social Graph Methods

Get All Friends

Returns the full list of people you follow.

Path		`/friends/ids.xml`
Requires authentication		Yes, if the account is private (authenticating user must be allowed by the author to view the list of friends).
Charged against rate limit		Yes.
HTTP method type		GET.
Optional parameters
	`id`	Indicates the user ID or username of the Twitter account whose following list you want to view. The `id` parameter is passed as part of the URL request: `/friends/ids/``id``.xml`.
Successful output		See the section called “The Follow Network”.

Get All Followers

Returns the full list of people who follow you.

Path		`/followers/ids.xml`
Requires authentication		Yes (authenticating user must be allowed by the author to view a private list of followers).
Charged against rate limit		Yes.
HTTP method type		GET.
Optional parameters
	`id`	Indicates the user ID or username of the Twitter account whose follower list you want to view. The `id` parameter is passed as part of the URL request: `/followers/ids/``id``.xml`.
Successful output		See the section called “The Follow Network”.

Account Methods

End a Member Session

Tells Twitter that your application is finished using your access credentials.

Path	`/account/end_session.xml`
Requires authentication	Yes (affects authenticating user).
Charged against rate limit	No.
HTTP method type	POST.
Successful output	See the section called “API Administration”.

Check Rate Limit Status

Checks to see how many hourly hits on the API are left for your account.

Path	`/account/rate_limit_status.xml`
Requires authentication	No. If authenticated, returns the rate limit for that Twitter account. If unauthenticated, returns the rate limit for the IP address used to make the request.
Charged against rate limit	No.
HTTP method type	GET.
Successful output	See the section called “API Administration”.

Update the Delivery Device

Selects a device for you to use to receive updates.

Path		`/account/update_delivery_device.xml`
Requires authentication		Yes (changes device for authenticating user).
Charged against rate limit		No.
HTTP method type		POST.
Required parameters
	`device`	Must be one of the two valid options supported by Twitter, namely `sms` or `im`. To turn off device notifications, the value should be `none`.
Successful output		See the section called “Member Account”.

Warning

There is currently no Twitter support for IM notifications.

Update Member Location

Changes the location information stored in your profile.

Path		`/account/update_location.xml`
Requires authentication		Yes (changes location of authenticating user).
Charged against rate limit		No.
HTTP method type		POST.
Required parameters
	`location`	Provides the text to be displayed in the location field in the authenticating user’s member profile. The text must be encoded.
Successful output		See the section called “Member Account”.

Warning

The update_location method has been deprecated in favor of the update_profile method, which contains an optional parameter for location. To keep your application from breaking in the future, avoid using update_location.

Update Member Profile

Sets the values of selected fields found in the “Account” tab under the settings on the Twitter website.

Path		`/account/update_profile.xml`
Requires authentication		Yes (changes profile for authenticating user).
Charged against rate limit		No.
HTTP method type		POST.
Required parameters		At least one parameter must be included.
Optional parameters		Only the requested parameters are changed.
	`name`	The full name of the person or organization owning the authenticating account. The maximum length is 40 characters.
	`email`	Must be a valid and unique email address of no more than 40 characters in length.
	`url`	The URL link to a website, displayed on the member’s profile web page. The maximum length is 100 characters. “http://” will be added to the beginning of the string, if not already provided.
	`location`	Contains the text to be displayed in the location field in the authenticating user’s member profile. The maximum length is 30 characters. Note: this is an open text field. No geocoding or other normalization is done by Twitter.
	`description`	This text describes the authenticating member. The maximum length is 160 characters.
Successful output		See the section called “Member Account”.

Update Background Image

Changes the background image on the authenticating user’s member profile web page.

Path		`/account/update_profile_background_image.xml`
Requires authentication		Yes (changes the image for authenticating user).
Charged rate limit		No.
HTTP method type		POST.
Required parameters
	`image`	Must contain raw multipart data, not a URL to an image located on the Web. This method accepts GIF, JPG, or PNG images with a maximum of 2,048 pixels. Larger images will be scaled down, provided they are less than 800 KB.
Successful output		See the section called “Member Account”.

Update Profile Colors

Changes the color scheme applied to the authenticating member’s profile page.

Path		`/account/update_profile_colors.xml`
Requires authentication		Yes (changes device for authenticating user).
Charged against rate limit		No.
HTTP method type		POST.
Required parameters		At least one parameter must be included.
Optional parameters		Must be valid hexadecimal values (e.g., #f1c or #ff11cc).
	`profile_background_color`	The background color, visible only if no background image is used for the member profile.
	`profile_text_color`	The color of the primary text in the profile.
	`profile_link_color`	The color of the links used on the page.
	`profile_sidebar_fill_color`	The shading used in the righthand sidebar.
	`profile_sidebar_border_color`	The border colors used for lines in the sidebar.
Successful output		See the section called “Member Account”.

Update Profile Image

Changes the picture associated with the authenticating member’s account and displayed with that user’s tweets.

Path		`/account/update_profile_image.xml`
Requires authentication		Yes (changes image for authenticating user).
Charged against rate limit		No.
HTTP method type		POST.
Required parameters
	`image`	Must contain raw multipart data, not a URL to an image located on the Web. This method accepts GIF, JPG, or PNG images with a maximum of 500 pixels. Larger images will be scaled down, provided they are less than 700 KB.
Successful output		See the section called “Member Account”.

Verify Credentials

Confirms that the supplied user account credentials are valid.

Path	`/account/verify_credentials.xml`
Requires authentication	Yes.
Charged against rate limit	Yes.
HTTP method type	GET.
Successful output	See the section called “API Administration”.

Favorite Methods

View Favorites

Returns a list of all status updates you’ve flagged as favorites.

Path		`/favorites.xml`
Requires authentication		Yes, if the favorites are private (authenticating user must be allowed by the author to view the bookmarks).
Charged against rate limit		Yes.
HTTP method type		GET.
Optional parameters
	`id`	Indicates the user ID or username of the Twitter account whose list of favorite updates you want to view. The `id` parameter is passed as part of the URL request: `/favorites/``id``.xml`.
	`page`	Indicates which page of 20 items to return. The default is 1 (the most recent status updates).
Successful output		See the section called “The Information Stream”.

Create a Favorite

Flags a status update as a favorite.

Path		`/favorites/create/``id``.xml`
Requires authentication		Yes.
Charged against rate limit		No.
HTTP method type		POST.
Required parameters
	`id`	References the ID of an existing status update. The `id` parameter is passed as part of the URL request.
Successful output		See the section called “The Information Stream”.

Delete a Favorite

Removes an existing flag on one of the authenticating member’s favorite status updates.

Path		`/favorites/destroy/``id``.xml`
Requires authentication		Yes.
Charged against rate limit		No.
HTTP method type		POST or DELETE.
Required parameters
	`id`	References the ID of an existing status update that the authenticating user has already made a favorite. The `id` parameter is passed as part of the URL request.
Successful output		See the section called “The Information Stream”.

Notification Methods

Turn On Notification

Tells Twitter to start sending an author’s updates to the preferred device.

Path		`/notifications/follow/``id``.xml`
Requires authentication		Yes (affects authenticating user).
Charged against rate limit		No.
HTTP method type		POST.
Required parameters
	`id`	Provides the user ID or username of another member to be followed by the authenticating user. The `id` parameter is passed as part of the URL request.
Successful output		See the section called “Member Account”.

Turn Off Notification

Tells Twitter to stop sending an author’s updates to the specified device.

Path		`/notifications/leave/``id``.xml`
Requires authentication		Yes (affects authenticating user).
Charged against rate limit		No.
HTTP method type		POST.
Required parameters
	`id`	Provides the user ID or username of another member followed by the authenticating user. The `id` parameter is passed as part of the URL request.
Successful output		See the section called “Member Account”.

Block Methods

Block a Member

Keeps another member from following your updates.

Path		`/blocks/create/``id``.xml`
Requires authentication		Yes.
Charged against rate limit		No.
HTTP method type		POST.
Required parameters
	`id`	Provides the user ID or username of an existing Twitter member not already blocked by the authenticating user. The `id` parameter is passed as part of the URL request.
Successful output		See the section called “The Follow Network”.

Remove a Block

Allows another member to once again follow your updates.

Path		`/blocks/destroy/``id``.xml`
Requires authentication		Yes.
Charged against rate limit		No.
HTTP method type		POST or DELETE.
Required parameters
	`id`	Supplies the user ID or username of an existing Twitter member already blocked by the authenticating user. The `id` parameter is passed as part of the URL request.
Successful output		See the section called “The Follow Network”.

Help Methods

Test

Verifies whether your application’s connection to the Twitter API is working.

Path	`/help/test.xml`
Requires authentication	No.
Charged against rate limit	No.
HTTP method type	GET.
Successful output	See the section called “API Administration”.

Search Methods

Keyword Search

Searches for keyword matches in tweet content.

Path		`search.twitter.com/search.atom?q=``query`
Requires authentication		No.
Charged against rate limit		No.
HTTP method type		GET.
Required parameters
	`q`	Contains the encoded keywords and other parameters used for the search.
Optional parameters
	`since`	Ignores information older than the specified time (which must be within the last 24 hours). The value must be encoded in the format “Mon, 3 Nov 2008 18:39:12 GMT”.
	`since_id`	Returns only the most recent updates (those made since the specified record ID was created).
	`page`	Indicates which page of items to return, with the size of the page determined by `rpp`. The default is 1 (the most recent messages).
	`rpp`	Indicates the size of a given result page. The maximum is 100 items per page, and the default is 16.
	`geocode`	There are three parts to the `geocode` parameter: latitude, longitude, and radius of interest. The resulting comma-delimited string (e.g., “39.123456,-86.345678,10km”) must be URL-encoded. The radius must be specified in units of either `mi` (miles) or `km` (kilometers).
	`lang`	Contains an accepted ISO 639-1 code (e.g., “en”) to indicate the language of all returned tweets.
	`show_user`	When set to `true`, tags the beginning of each tweet returned in the search results with a username and a colon (e.g., “kmakice:Writing”).
	`callback`	(JSON only.) A callback allows a program to pass a reference to a dynamic function on the application side.
Successful output		See the section called “Search”.

Monitor Trends

Returns the current top keyword trends in the public timeline.

Path	`search.twitter.com/trends.json`
Requires authentication	No.
Charged against rate limit	No.
HTTP method type	GET.
Successful output	Ten keywords and search links (JSON output format only)

Twitter API Reference: Appendix - Twitter API: Up and Running

Note

Status Methods

Delete a Tweet

View Followers

View Members Being Followed

Note

View a Friends Timeline

View the Public Timeline

View Replies

Show a Tweet

Post a Tweet

View an Individual Timeline

Users Methods

Show Member Profile

Direct Message Methods

List Received Messages

Delete a Message

Create a Message

List Sent Messages

Friendship Methods

Follow a Member

Unfollow a Member

Confirm a Follow

Social Graph Methods

Get All Friends

Get All Followers

Account Methods

End a Member Session

Check Rate Limit Status

Update the Delivery Device

Warning

Update Member Location

Warning

Update Member Profile

Update Background Image

Update Profile Colors

Update Profile Image

Verify Credentials

Favorite Methods

View Favorites

Create a Favorite

Delete a Favorite

Notification Methods

Turn On Notification

Turn Off Notification

Block Methods

Block a Member

Remove a Block

Help Methods

Test

Search Methods

Keyword Search

Monitor Trends