• If you are citizen of an European Union member nation, you may not use this service unless you are at least 16 years old.

  • You already know Dokkio is an AI-powered assistant to organize & manage your digital files & messages. Very soon, Dokkio will support Outlook as well as One Drive. Check it out today!

View
 

API Docs

This version was saved 14 years, 1 month ago View current version     Page history
Saved by tomonaka@...
on February 28, 2010 at 6:37:20 am
 

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

  

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 :)

 


 

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 three options for authorization:

 

  1. Basic Authorization
  2. Login Authorization and session cookie management
  3. Use OAuth protocol 

 

 

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

 

 

OAuth 

 Now twitter recommends authenticate using OAuth protocol rather than other options.

Using OAuth protocol, application has no need to know user's password itself.

Official informations of OAuth protocol is here.

 

You can use libraries to implement OAuth protocol in your application.

Libraries of OAuth

 

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 Path Data format Example
created_at HTTPCustom Format date Tue Mar 13 00:12:41 +0000 2007
text Up to 160 characters of utf8 Creating this table
id Integer 123
user.name Up to 40 characters of utf8 Rick Measham
user.description Up to 160 characters of utf8 Perl and Javascript Developer
user.location Up to 30 characters of utf8 Melbourne, Australia
user.screen_name Up to 15 characters from: A-Z a-z 0-9 and _ RickMeasham
user.url Up to 100 characters of utf8 http://rick.measham.id.au/
user.id Integer 1050881

 

(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 Path Data format Example
id Integer 1050881
name Up to 40 characters of utf8 Rick Measham
location Up to 30 characters of utf8 Melbourne, Australia
description Up to 160 characters of utf8 Perl and Javascript Developer
profile_image_url Valid 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
url Up to 100 characters of utf8 http://rick.measham.id.au/
status.created_at HTTPCustom Format date Tue Mar 13 00:12:41 +0000 2007
status.id Integer 123
status.text Up to 160 characters of utf8 Creating 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

Comments (0)

You don't have permission to comment on this page.