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

by Kevin Makice

Don’t have time to reread all the prior poetry about the Twitter API? Fine. Here’s a methods cheat sheet that gives you the basics you will need to program your Twitter application. The hierarchy listed here is based on the server paths used by Twitter—the technical order, based on path and method name—rather than the functional groups I used in Chapter 4, Meet the Twitter API of this book.

Twitter API: Up and Running book cover

This excerpt is from Twitter API: Up and Running . This groundbreaking book provides you with the skills and resources you need to build web applications for Twitter. Perfect for new and casual programmers intrigued by the microblogging, Twitter API: Up and Running carefully explains how each part of Twitter's API works, with detailed examples that show you how to assemble those building blocks into practical and fun web applications.

buy button

Twitter tracks two kinds of rate limits: one for unauthenticated requests (which is not possible for the methods that require authentication), and the other for requests made per account when authentication is used. POST method requests, used whenever you need to make a change to the server, don’t cost anything. There are also a few methods that are exempt from the rate limit.

For more information on the current nuances of using the API, check out the Twitter API FAQ.

Note

In this appendix, I use the .xml format to describe the methods. Remember, you can substitute .json for all of the Twitter API methods and .atom or .rss for some of them.

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_idAccepts 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_nameAccepts 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)

If you enjoyed this excerpt, buy a copy of Twitter API: Up and Running.