Loading...
|
|
REST API DocumentationPage history last edited by Alex Payne 2 weeks, 2 days ago
IntroductionTwitter exposes some of its functionality via an Application Programming Interface (API). This document is a reference for that functionality, and aims to serve as a reference for developers building tools that talk to Twitter.
Table of ContentsConcepts
AuthenticationMany Twitter API methods require authentication. All responses are relative to the context of the authenticating user. For example, an attempt to retrieve information on a protected user who is not friends with the requesting user will fail.
For the time being, HTTP Basic Authentication is the only supported authentication scheme. When authenticating via Basic Auth, use your registered username or email address as the username component. Session cookies and parameter-based login are known to work but are not officially supported.
The OAuth token-based authentication scheme will shortly be offered as an experimental beta release.
RESTful ResourcesThe Twitter API attempts to conform to the design principles of Representational State Transfer (REST). You’ll find that you can simply change the file extension on most any request to get results in the format of your choice. This document notes which formats are available for each method.
Twitter presently supports the following data formats: XML, JSON, and the RSS and Atom syndication formats.
ParametersSome API methods take optional or requisite parameters. Where applicable, we’ve documented those parameters. Remember to convert to UTF-8 and URL encode parameters that take complex strings. Please note that the page parameter begins at 1, not 0.
There are two special parameters in the Twitter API:
HTTP RequestsMethods to retrieve data from the Twitter API require a GET request. Methods that submit, change, or destroy data require a POST. A DELETE request is also accepted for methods that destroy data. API Methods that require a particular HTTP method will return an error if you do not make your request with the correct method.
HTTP HeadersWhere noted, some API methods will return different results based on HTTP headers sent by the client. For example, most methods that allow a since parameter will also respond to an If-Modified-Since header. Where the same behavior can be controlled by both a parameter and an HTTP header, the parameter will take precedence.
HTTP Status CodesThe Twitter API attempts to return appropriate HTTP status codes for every request. Here's what's going on with our various status codes:
Error MessagesWhen the Twitter API returns error messages, it does so in your requested format. For example, an error from an XML method might look like this:
<?xml version="1.0" encoding="UTF-8"?> <hash> <request>/direct_messages/destroy/456.xml</request> <error>No direct message with that ID found.</error> </hash>
Rate LimitingClients are allowed 100 requests per 60 sixty minute time period, starting from their first request. The rate limited is applied to both authenticated and unauthenticated requests. Unauthenticated requests are rate limited by IP, and authenticated requests are tracked by the requesting user ID. POST requests (ex: updating status, sending a direct message) do not count against the rate limit, but some actions may have caps on them to prevent abuse.
Notification that a client has exceeded the rate limit will be sent as JSON or XML when either is the requested format, and otherwise will be sent in plain text. A status code of 400 will be returned when the client has exceeded the rate limit.
If you are developing an application that requires more frequent requests to the Twitter API, please request whitelisting and we'll get back to you, usually within 48 hours or less.
See also the rate_limit_status API call under Account Methods.
Pagination LimitingClients may request up to 3,200 statuses via the page and count parameters. Requests for more than the limit will result in a reply with a status code of 200 and an empty result in the format requested.
EncodingThe Twitter API supports UTF-8 encoding. Please note that angle brackets ("<" and ">") are entity-encoded to prevent Cross-Site Scripting attacks for web-embedded consumers of JSON API output. The resulting encoded entities do count towards the 140 character limit.
When requesting XML, the response is UTF-8 encoded. Symbols and characters outside of the standard ASCII range may be translated to HTML entities. Getting StartedBe Nice to the ServersIn order to keep the API running smoothly, please obey the following guidelines:
The Easiest Way to Play Around with the Twitter APIIf your system has curl (and it should!), you’ve already got a great way to poke around the Twitter API. Here are some examples:
Frequently Asked QuestionsHow do I get “from [my_application]” appended to updates sent from my API application?Just fill out this handy form! Note that you must have a Twitter account and must be signed in. How do I report bugs and request features?You can see the list of existing issues right here. Please check to be sure your issue hasn't already been reported. Star an existing issue to vote for it, or add an example to an issue if it describes your bug. Or, report a new issue if need be. How should my Twitter bot follow users that follow it or inspect direct messages?By default, Twitter sends an email the first time a user follows you or sends you a direct message. For your bot-building pleasure, we've added the following headers to those emails:
How can I keep up with changes to the Twitter API?There are a number of great ways to follow the changes we make to the Twitter API:
How can I reclaim an inactive Twitter account for my project or application?Email username@twitter.com and our support staff will get back to you. Not all inactive usernames are available - we do give users a grace period in which they can restore their accounts after they've deleted them.
Status Methodspublic_timelineReturns the 20 most recent statuses from non-protected users who have set a custom user icon. Does not require authentication. Note that the public timeline is cached for 60 seconds so requesting it more often than that is a waste of resources.
URL: http://twitter.com/statuses/public_timeline.format Formats: xml, json, rss, atom Method(s): GET API limit: Not applicable
friends_timelineReturns the 20 most recent statuses posted by the authenticating user and that user's friends. This is the equivalent of /home on the Web. URL: http://twitter.com/statuses/friends_timeline.format Formats: xml, json, rss, atom Method(s): GET API Limit: 1 per request Parameters:
user_timelineReturns the 20 most recent statuses posted from the authenticating user. It's also possible to request another user's timeline via the id parameter below. This is the equivalent of the Web /archive page for your own user, or the profile page for a third party. URL: http://twitter.com/statuses/user_timeline.format Formats: xml, json, rss, atom Method(s): GET Parameters:
showReturns a single status, specified by the id parameter below. The status's author will be returned inline. URL: http://twitter.com/statuses/show/id.format Formats: xml, json Method(s): GET Parameters:
updateUpdates 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. URL: http://twitter.com/statuses/update.format Formats: xml, json. Returns the posted status in requested format when successful. Method(s): POST Parameters:
repliesReturns the 20 most recent @replies (status updates prefixed with @username) for the authenticating user. URL: http://twitter.com/statuses/replies.format Formats: xml, json, rss, atom Method(s): GET Parameters:
destroyDestroys the status specified by the required ID parameter. The authenticating user must be the author of the specified status. URL: http://twitter.com/statuses/destroy/id.format Formats: xml, json Method(s): POST, DELETE Parameters:
User MethodsfriendsReturns up to 100 of the authenticating user's friends who have most recently updated, each with current status inline. It's also possible to request another user's recent friends list via the id parameter below. URL: http://twitter.com/statuses/friends.format Formats: xml, json Method(s): GET Parameters:
followersReturns the authenticating user's followers, each with current status inline. They are ordered by the order in which they joined Twitter (this is going to be changed). URL: http://twitter.com/statuses/followers.format Formats: xml, json Method(s): GET Parameters:
showReturns extended information of a given user, specified by ID or screen name as per the required id parameter below. This information includes design settings, so third party developers can theme their widgets according to a given user's preferences. You must be properly authenticated to request the page of a protected user. URL: http://twitter.com/users/show/id.format Formats: xml, json Method(s): GET Parameters: One of the following is required:
Direct Message Methods
direct_messagesReturns a list of the 20 most recent direct messages sent to the authenticating user. The XML and JSON versions include detailed information about the sending and recipient users. URL: http://twitter.com/direct_messages.format Formats: xml, json, rss, atom Method(s): GET Parameters:
sentReturns a list of the 20 most recent direct messages sent by the authenticating user. The XML and JSON versions include detailed information about the sending and recipient users. URL: http://twitter.com/direct_messages/sent.format Formats: xml, json Method(s): GET Parameters:
newSends a new direct message to the specified user from the authenticating user. Requires both the user and text parameters below. Request must be a POST. Returns the sent message in the requested format when successful. URL: http://twitter.com/direct_messages/new.format Formats: xml, json Method(s): POST Parameters:
destroyDestroys the direct message specified in the required ID parameter. The authenticating user must be the recipient of the specified direct message. URL: http://twitter.com/direct_messages/destroy/id.format Formats: xml, json Method(s): POST, DELETE Parameters:
Friendship MethodscreateBefriends the user specified in the ID parameter as the authenticating user. Returns the befriended user in the requested format when successful. Returns a string describing the failure condition when unsuccessful. URL: http://twitter.com/friendships/create/id.format Formats: xml, json Method(s): POST Parameters:
destroyDiscontinues friendship with the user specified in the ID parameter as the authenticating user. Returns the un-friended user in the requested format when successful. Returns a string describing the failure condition when unsuccessful. URL: http://twitter.com/friendships/destroy/id.format Formats: xml, json Method(s): POST, DELETE Parameters:
existsTests if a friendship exists between two users. URL: http://twitter.com/friendships/exists.format Formats: xml, json Method(s): GET Parameters:
Account Methodsverify_credentialsReturns an HTTP 200 OK response code and a representation of the requesting user if authentication was successful; returns a 401 status code and an error message if not. Use this method to test if supplied user credentials are valid. URL: http://twitter.com/account/verify_credentials.format Formats: xml, json Method(s): GET end_sessionEnds the session of the authenticating user, returning a null cookie. Use this method to sign users out of client-facing applications like widgets. URL: http://twitter.com/account/end_session Formats: xml, json Method(s): POST update_locationThis method has been deprecated in favor of the update_profile method below. Its URL will continue to work, but please consider migrating to the newer and more comprehensive method of updating profile attributes. update_delivery_deviceSets which device Twitter delivers updates to for the authenticating user. Sending none as the device parameter will disable IM or SMS updates. URL: http://twitter.com/account/update_delivery_device.format Formats: xml, json Method(s): POST Parameters:
update_profile_colorsSets one or more hex values that control the color scheme of the authenticating user's profile page on twitter.com. These values are also returned in the /users/show API method. URL: http://twitter.com/account/update_profile_colors.format Formats: xml, json Method(s): POST Parameters: one or more of the following parameters must be present. Each parameter's value must be a valid hexidecimal value, and may be either three or six characters (ex: #fff or #ffffff).
update_profile_imageUpdates the authenticating user's profile image. Expects raw multipart data, not a URL to an image. URL: http://twitter.com/account/update_profile_image.format Formats: xml, json Method(s): POST Parameters:
update_profile_background_imageUpdates the authenticating user's profile background image. Expects raw multipart data, not a URL to an image. URL: http://twitter.com/account/update_profile_background_image.format Formats: xml, json Method(s): POST Parameters:
rate_limit_statusReturns the remaining number of API requests available to the requesting user before the API limit is reached for the current hour. Calls to rate_limit_status do not count against the rate limit. If authentication credentials are provided, the rate limit status for the authenticating user is returned. Otherwise, the rate limit status for the requester's IP address is returned. URL: http://twitter.com/account/rate_limit_status.format Formats: xml, json Method(s): GET Parameters: none
update_profileSets values that users are able to set under the "Account" tab of their settings page. Only the parameters specified will be updated; to only update the "name" attribute, for example, only include that parameter in your request. URL: http://twitter.com/account/update_profile.format Formats: xml, json Method(s): POST Parameters: one or more of the following parameters must be present. Each parameter's value should be a string. See the individual parameter descriptions below for further constraints.
Favorite MethodsfavoritesReturns the 20 most recent favorite statuses for the authenticating user or user specified by the ID parameter in the requested format. URL: http://twitter.com/favorites.format Formats: xml, json, rss, atom Method(s): GET Parameters:
createFavorites the status specified in the ID parameter as the authenticating user. Returns the favorite status when successful. URL: http://twitter.com/favorites/create/id.format Formats: xml, json Method(s): POST Parameters:
destroyUn-favorites the status specified in the ID parameter as the authenticating user. Returns the un-favorited status in the requested format when successful. URL: http://twitter.com/favorites/destroy/id.format Formats: xml, json Method(s): POST, DELETE Parameters:
Notification MethodsfollowEnables notifications for updates from the specified user to the authenticating user. Returns the specified user when successful. URL:http://twitter.com/notifications/follow/id.format Formats: xml, json Method(s): POST Parameters:
leaveDisables notifications for updates from the specified user to the authenticating user. Returns the specified user when successful. URL: http://twitter.com/notifications/leave/id.format Formats: xml, json Method(s): POST Parameters:
NOTE: The Notification Methods require the authenticated user to already be friends with the specified user otherwise the error "there was a problem following the specified user" will be returned. You create and manage friendships with these services.
Block MethodscreateBlocks the user specified in the ID parameter as the authenticating user. Returns the blocked user in the requested format when successful. You can find out more about blocking in the Twitter Support Knowledge Base. URL: http://twitter.com/blocks/create/id.format Formats: xml, json Method(s): POST Parameters:
destroyUn-blocks the user specified in the ID parameter as the authenticating user. Returns the un-blocked user in the requested format when successful. URL: http://twitter.com/blocks/destroy/id.format Formats: xml, json Method(s): POST, DELETE Parameters:
Help MethodstestReturns the string "ok" in the requested format with a 200 OK HTTP status code. URL: http://twitter.com/help/test.format Formats: xml, json Method(s): GET downtime_scheduleReturns the same text displayed on http://twitter.com/home when a maintenance window is scheduled, in the requested format. URL:http://twitter.com/help/downtime_schedule.format Formats: xml, json Method(s): GET
Getting HelpA supplement to this document is the Twitter Development Talk Google Group. Engineers who work on Twitter follow this group closely, and many third party developers are kindly participating and lending their expertise. It’s a great place to ask questions about the Twitter API. AuthorsThis document is maintained by Alex Payne, Twitter's API Lead. You can reach him via email at alex@twitter.com.
|
Comments (0)
You don't have permission to comment on this page.