View
 

API Docs

Page history last edited by tomonaka@... 14 years, 6 months ago

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 

Former 2 methods require the knowledge of the user's username and password and last one does not need.

Basic Authorization

Basic Authorization is strongly deprecated now. 

On June 30, 2010, basic authentication on the Twitter API is to be shutted off. http://www.countdowntooauth.com/ 

Use OAuth instead. 

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.

Under OAuth protocol, you need to register your application as consumer to twitter as service provider. You can register at http://twitter.com/oauth_clients .

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

Libraries of OAuth

Important point for application developper is that  it is now basically required to use OAuth to show your application name/link at each tweet as "from <application name>". 

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_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 PathData formatExample
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 (1)

oyun said

at 3:55 am on May 31, 2010

http://www.kucukpatisserie.com/
http://www.gunalsen.com
http://www.kelebekcafe.net
http://www.mirclider.com
http://www.mirclider.net
http://www.mirclider.org
http://www.doruknet.org
http://www.dorukchat.net
http://www.dorukchat.org
http://www.netzurna.com
http://www.onursan.org
http://www.gevezechat.org
http://www.izmirchat.org
http://www.cinselchat.org
http://www.hanimeligelinlik.com
http://www.hanimeligelinlik.net
http://www.hanimeligelinlik.org
http://www.oyunlider.com
http://sikisyeri.blogspot.com/
http://fikra34.blogspot.com/
http://gunluk-filim.blogspot.com/
http://cinsel-muhabbet.blogspot.com
http://escinselsohbet.blogspot.com
http://cinselsohbetiniz.blogspot.com
http://gaysohbetiniz.blogspot.com
http://lezsohbetiniz.blogspot.com
http://ist-lgbtt.blogspot.com/
http://travesti34.blogspot.com/
http://gay34.blogspot.com/
http://gay-lez.blogspot.com/
http://gay-europa.blogspot.com/
http://drkcht.blogspot.com/
http://sarki-s0zleri.blogspot.com/
http://www.facebook.com/OnurSan.Fan
http://www.facebook.com/GunalSen
http://www.facebook.com/Partneriniz
http://www.facebook.com/AdultChat
http://twitter.com/OnurSanFan
http://twitter.com/DiningServices
http://twitter.com/WSUCougarscom
http://twitter.com/WSUCVMrecruit
http://cinselsohbet.blog.com/
http://gaychat.blog.com/
http://gaysohbet.blog.com/
http://sicaksohbet.blog.com/
http://sicakchat.blog.com/
http://sexchat.blog.com/
http://sexsohbet.blog.com/
http://diziizley1n.blog.com/
http://diziizleyin1.blog.com/
http://fikrabul.blog.com/
http://sikisturk.blog.com/
http://amcik.blog.com/
http://travesti.blog.com/
http://mircindir.blog.com/
http://mircyukle.blog.com/
http://kelebekindir.blog.com/
http://kelebekchat.blog.com/
http://kelebeksohbett.blog.com/
http://kelebektr.blog.com/
http://kelebekturk.blog.com/
http://trsohbet.blog.com/
http://chatnet.blog.com/
http://dalnet.blog.com
http://twitterfan.blog.com

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