Admin Message: Thank you for your patience during our technical difficulties. We're working to restore full service. Please see our blog for details.

The official API docs live here. Also check out the Twitter developer talk Google Group.

Unofficial API Docs

As the official docs are not yet written, I've decided to take the bull by the horns and start this page. Feel free to update and edit at will .. this is a wiki :)

  1. Unofficial API Docs
    1. Publicly Available Commands
      1. public_timeline
    2. Authorization
      1. Basic Authorization
      2. Login Authorization
    3. Authorized Commands
      1. user_timeline
      2. friends_timeline
      3. friends
      4. followers
      5. update
      6. account_settings
    4. Response Types
      1. Status Responses
      2. User Responses
    5. Request Headers
    6. Conventions

Publicly Available Commands

public_timeline

The public timeline can be retrieved as JSON, XML, RSS and ATOM from the following URLs:

This feed will always (currently) return the latest 20 posts. However the suggestion of a 'count' parameter has been mooted. Eg: http://twitter.com/statuses/public_timeline.xml?count=5

Response type: status

Authorization

There are currently two options for authorization:

  1. Basic Authorization
  2. Login Authorization and session cookie management

Both require the knowledge of the user's username and password.

Basic Authorization

Basic Authorization is done via whatever method your library requires. This could be the simple use of a URL such as: http://username:password@twitter.com/statuses/user_timeline.xml

Any other implementation of basic authorization should be referred to your programming language's WWW libraries.

Response type: N/A - This auth type is used with any command. A 401 status indicates a failed auth.

Login Authorization

NOTE: This is not an official API command. You will receive a text/html response. You will need to parse that to determine success/failure. There is no guarantee Twitter will not change the content of the returned page.

If you prefer, you can use cookie management to login via the website auth. Send a POST request to http://twitter.com/login with the 'username_or_email' and 'password' parameters set as appropriate. The headers of the response will include a '_twitter_session' cookie. Present this on all future requests.

Response type: html

Authorized Commands

These commands are only available to users who have logged in as above

user_timeline

This command returns the authorized user's timeline. The following URLs require no extra parameters:

Response type: status

friends_timeline

This command returns the authorized user's friends timeline (friends include the authorized user). The following URLs require no extra parameters:

Response type: status

friends

This command returns the authorized user and their friends' current status. *Not* a timeline, just the latest entry:

Response type: user

NOTE: 2007-03-21: This appears not to be working for RSS or ATOM

followers

This command returns the authorized user's followers' current status. Once again, *not* a timeline, just the latest entry:

Response type: user

NOTE: 2007-03-21: This appears not to be working for RSS or ATOM

update

This command allow you to set the authorized user's status. Send a POST request to the following URLs with the 'status' parameter set to the new status. Don't forget to URL-encode the status if you library doesn't do it for you.

Response type: null

account_settings

NOTE: This is not an official API command. You will receive a text/html response. You will need to parse that to determine success/failure. There is no guarantee Twitter will not change the content of the returned page.

This command allows you to set various account settings for the authorized user. Send a POST to the following URL:

The following parameter names should be self explanatory. Don't forget to URL Encode both the parameter name and value if your library doesn't handle that for you automatically.

  • user[name] -- Only letters, numbers and underscores (_) are allowed
  • user[email]
  • user[time_zone] -- See the website source for a list of accepted values
  • user[url]
  • user[description] -- Up to 160 characters only.
  • user[location]
  • user[protected] -- 1 or 0
Response type: html

Response Types

Status Responses

These responses are in reply to timeline type requests.

Fields returned:


Field PathData formatExample
created_atHTTPCustom Format dateTue Mar 13 00:12:41 +0000 2007
textUp to 160 characters of utf8Creating this table
idInteger123
user.nameUp to 40 characters of utf8Rick Measham
user.descriptionUp to 160 characters of utf8Perl and Javascript Developer
user.locationUp to 30 characters of utf8Melbourne, Australia
user.screen_nameUp to 15 characters from: A-Z a-z 0-9 and _RickMeasham
user.urlUp to 100 characters of utf8http://rick.measham.id.au/
user.idInteger1050881

(Note that the XML looks like: <statuses><status><created_at> ... </created_at> ... </status><statuses>)

User Responses

These responses are in reply to requests that return user information such as friends and followers.

Fields returned:


Field PathData formatExample
idInteger1050881
nameUp to 40 characters of utf8Rick Measham
locationUp to 30 characters of utf8Melbourne, Australia
descriptionUp to 160 characters of utf8Perl and Javascript Developer
profile_image_urlValid URL at twitter.com (the query string appears to be a random number to force a reload each time)http://static.twitter.com//system/user/profile_image/1050881/normal/rickm.png?1173740203
urlUp to 100 characters of utf8http://rick.measham.id.au/
status.created_atHTTPCustom Format dateTue Mar 13 00:12:41 +0000 2007
status.idInteger123
status.textUp to 160 characters of utf8Creating this table

(Note that the XML looks like: <users><user><created_at> ... </created_at> ... </user><users>)

Request Headers

These headers are currently considered a de facto standard. So they may change. Don't blame me if you have to change your code later on, but on 2007-03-21, Alex Payne (from Twitter) said:
Please do start sending headers to us. It'll be most helpful for planning our capacity.

Rick Measham (that's me!) then suggested the following headers, to which Alex replied:
Those X headers are exactly along the lines of what I was thinking. Thanks for setting a sane de-facto standard!

The following request header should be used when making the above calls:

  • X-Twitter-Client: [The 'brand name' of your client]
The following request headers can be used when making the above calls:
  • X-Twitter-Client-Version: [The version number]
  • X-Twitter-Client-URL: [URL of your client's meta information for publication in some future directory. See below]
The URL must point to an XML document something like the following:
<client>
	<name>GoogleGadget</name>
	<version>2.01</version>
	<author>
		<name>Rick Measham</name>
		<email>google@twitter.isite.net.au</email>
		<twitter>RickMeasham</twitter>
	</author>
	<url>http://twitter.isite.net.au</url>
	<twitter>GoogleGadget</twitter>
	<description><![CDATA[
		The Twitter Google Gadget brings all the fun of twitter to your Google personalised homepage.
		<a href="http://fusion.google.com/add?feedurl=http%3A//twitter.isite.net.au/twitter.xml"><img src="http://buttons.googlesyndication.com/fusion/add.gif" width="104" height="17" border="0" alt="Add to Google"></a>
	]]>
	</description>
</client>

NOTE: I expect this XML may change .. this was a quick hack. Join the developers list and chime in if you want to comment.

Conventions

The following terms are used in this document to signify the requirements of the API. Those in bold only apply when shown in bold. (They are based on section 1.2 of RFC2060)

  1. must, or the adjective REQUIRED, means that the definition is an absolute requirement of the specification.
  2. must not that the definition is an absolute prohibition of the specification.
  3. should means that there may exist valid reasons in particular circumstances to ignore a particular item, but the full implications must be understood and carefully weighed before choosing a different course.
  4. **should not* means that there may exist valid reasons in particular circumstances when the particular behavior is acceptable or even useful, but the full implications should be understood and the case carefully weighed before implementing any behavior described with this label.
  5. may, or the adjective optional, means that an item is truly optional. One vendor may choose to include the item because a particular marketplace requires it or because the vendor feels that it enhances the product while another vendor may omit the same item. An implementation which does not include a particular option must be prepared to interoperate with another implementation which does include the option.
  • "Can" is used instead of "may" when referring to a possible circumstance or situation, as opposed to an optional facility.
  • "User" is used to refer to a human user, whereas "client" refers to the software being run by the user.
  • "Twitter" means the owner(s) of the service located at twitter.com for which this document describes the API
  • "twitter.com" means the server(s) against which the API works


Page Information

  • 1 week ago [history]
  • View page source
  • You're not logged in
  • No tags yet learn more

Wiki Information

Recent PBwiki Blog Posts