- Loading...
|
|
REST API DocumentationPage history last edited by Matt Sanford 1 week, 1 day 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. Users and IPs on the whitelist are allowed a maximum of 20,000 requests per hour.
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 QuestionsWe maintain a list of frequently asked questions right here on the API Wiki.
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 Returns: list of status elements
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:
Returns: list of status elements 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:
Returns: list of status elements 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:
Returns: status element 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:
Returns: status element 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:
Returns: list of status elements 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:
Returns: status element User MethodsfriendsReturns the authenticating user's friends, each with current status inline. They are ordered by the order in which they were added as friends. 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:
Returns: list of basic user information elements 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:
Returns: list of basic user information elements 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:
Returns: extended user information element 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:
Return: list of direct message elements 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:
Return: list of direct message elements 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:
Return: direct message element 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:
Return: list of direct message elements 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:
Returns: basic user information element 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:
Returns: basic user information element existsTests if a friendship exists between two users. URL: http://twitter.com/friendships/exists.format Formats: xml, json Method(s): GET Parameters:
Returns: true, false
Social Graph Methodsids (friends)Returns an array of numeric IDs for every user the specified user is following. URL: http://twitter.com/friends/ids.xml Formats: xml, json Method(s): GET Parameters:
Returns: list of IDs
ids (followers)Returns an array of numeric IDs for every user the specified user is followed by. URL: http://twitter.com/followers/ids.format Formats: xml, json Method(s): GET Parameters:
Returns: list of IDs 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.format 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:
Returns: basic user information element 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).
Returns: extended user information element 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:
Returns: extended user information element
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:
Returns: extended user information element
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.
Returns: extended user information element 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:
Returns: list of status elements 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:
Returns: status element 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:
Returns: status element 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:
Returns: basic user information element
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:
Returns: basic user information element
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:
Returns: basic user information element 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:
Returns: basic user information element 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
Return ElementsAlmost all API calls return well-formed elements of data. The element or list of elements are comprised of return values.
Status elementA status element consists of information on a status, with a nested <user> element to describe the author. <status> created_at id text source truncated in_reply_to_status_id in_reply_to_user_id favorited <user> id name screen_name description location profile_image_url url protected followers_count
Basic user information elementBasic user information elements contain primary user information with nested a <status> element to describe the user's most current update. <user> id name screen_name location description profile_image_url url protected followers_count <status> created_at id text source truncated in_reply_to_status_id in_reply_to_user_id favorited in_reply_to_screen_name
Extended user information elementExtended user information elements contain detailed user-specified information about a user's profile. <user> id name screen_name location description profile_image_url url protected followers_count profile_background_color profile_text_color profile_link_color profile_sidebar_fill_color profile_sidebar_border_color friends_count created_at favourites_count utc_offset time_zone profile_background_image_url profile_background_tile following notifications statuses_count
Direct message elementDIrect message elements contain a set of values that describe a message, as well as nested <sender> and <recipient> nodes. <direct_message> id sender_id text recipient_id created_at sender_screen_name recipient_screen_name <sender> id name screen_name location description profile_image_url url protected followers_count <recipient> id name screen_name location description profile_image_url url protected followers_count
Return ValuesAPI methods return elements of data. These elements contain a known set of value fields from the following index. created_atDescription: timestamp of element creation, either status or user Example: Sat Jan 24 22:14:29 +0000 2009
descriptionDescription: 160 characters or less of text that describes a user Examples: empty (Default), I like new shiny things.
favoritedDescription: boolean indicating if a status has been marked as a favorite Examples: true, false
favorites_countDescription: number of statuses a user has marked as favorite Examples: 0, 451
followingDescription: boolean indicating if a user is following a given user Examples: true, false
followers_countDescription: number of users following a user's updates Examples: 0, 4034
friends_countDescription: number of users a user is following Examples: 0, 221
nameDescription: full name of a registered user Examples: Tweety Bird, John Doe
hourly_limitDescription: maximum number of API calls a user is allowed in an hour Examples: 100
idDescription: a permanent unique id referencing an object, such as user or status Examples: 1145445329 (status), 14198354 (user)
in_reply_to_screen_nameDescription: display name for the user that wrote the status a status replies to (see screen_name) Examples: empty, tweetybird
in_reply_to_status_idDescription: unique id for the status a status replies to (see id) Examples: empty, 1047468972
in_reply_to_user_idDescription: unique id for the user that wrote the status a status replies to (see id) Examples: empty, 14597523
locationDescription: user specified string representing where they are from Examples: empty (Default), California OR New York, NY, In The Woods, 27.893621,-82.243706
notificationsDescription: boolean indicating if a user is receiving device updates for a given user Examples: true, false
profile_background_colorDescription: hex RGB value for a user's background color Example: 9ae4e8 (Default)
profile_background_image_urlDescription: location of a user's background image Examples: empty, http://static.twitter.com/images/themes/theme1/bg.gif (Default), http://s3.amazonaws.com/twitter_production/profile_background_images/2752608/super_sweet.jpg profile_background_tileDescription: boolean indicating if a user's background is tiled Examples: true, false
profile_image_urlDescription: location to a user's avatar file Examples: http://static.twitter.com/images/default_profile_normal.png (Default), http://s3.amazonaws.com/twitter_production/profile_images/14198354/sweet_avatar.jpg
profile_link_colorDescription: hex RGB value for a user's link color Example: 0000ff (Default)
profile_sidebar_border_colorDescription: hex RGB value for a user's border color Example: 87bc44 (Default)
profile_sidebar_fill_colorDescription: hex RGB value for a user's sidebar color Example: e0ff92 (Default)
profile_text_colorDescription: hex RGB value for a user's text color Example: 000000 (Default)
protectedDescription: boolean indicating if a user has a protected profile Examples: true, false
recipient_idDescription: unique id of the user that received a direct message (see id) Example: 1401881
recipient_screen_nameDescription: display name of the user that sent a direct message (see screen_name) Examples: tweetybird, johnd
remaining_hitsDescription: number of API calls remaining for a user Examples: 0, 43
reset_timeDescription: time when a user's API call allocation resets Example: Sun Jan 25 01:20:43 +0000 2009
reset_time_in_secondsDescription: Unix time when a user's API call allocation resets Example: 1232846443
screen_nameDescription: display name for a user Examples: tweetybird, johnd
sender_idDescription: unique id of the user that sent a direct message (see id) Example: 6633812 sender_screen_nameDescription: display name of the user that sent a direct message (see screen_name) Examples: tweetybird, johnd
sourceDescription: application that sent a status Examples: web
statuses_countDescription: the total number of status updates performed by a user, excluding direct messages sent Examples: 0, 9423 textDescription: escaped and HTML encoded status body Examples: I am eating oatmeal, The first tag is always <html>
time_zoneDescription: a user's time zone Examples: Central Time (US & Canada) (Default), Sydney truncatedDescription: boolean indicating if a status required shortening Examples: true, false urlDescription: user's homepage Examples: empty, http://downforeveryoneorjustme.com utc_offsetDescription: number of seconds between a user's registered time zone and Coordinated Universal Time Examples: -21600 (Default), 36000 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.
|
Anonymous
Create an account or Log in
Comments (0)
You don't have permission to comment on this page.