node package manager



Twitter REST & Streaming API client for Node.js

Still very much a work-in-progress.

Getting Started

Install twitter-starling:

npm install twitter-starling

Include the twitter library:

var Twitter = require('twitter-starling');

[ optional ] Create an authentication credential :

var credential = new Twitter.LoginCredential(   'CONSUMER_KEY',
                                                'ACCESS_TOKEN_SECRET'   );

Create the Twitter client:

var authorisedTwitter = new Twitter(credential);


Query the Twitter REST API:

// get the public timeline 
authorisedTwitter.timeline.public( {}, function(result, parent) {
    if(result.isSuccess) {
        var tweets = result.message();
        for(var i=0; i<tweets.length; i++) {
            console.log(util.summariseTwitter(tweets[i], '(public_timeline) '));
    } else {
        console.log("Error: " + result.message); 

Query the Twitter Streaming API:

// sample the public timeline{}, function(result) {
    if(result.isSuccess) {
    try {
        var tweet = JSON.parse(;
            if(typeof tweets[j].user === 'undefined') {
                console.log('[' + user.screen_name + '' + postfix);
            } else if(typeof tweets[j].status === 'undefined') {
                console.log('[' + tweet.user.screen_name + '' + tweet.text + postfix);
        } catch (e) {
            // best to just ignore it, eh? 
    } else {
        console.log("Error: " + result.message);

More examples

From root source folder you can try out some examples in the test directory:

node test

this will execute some basic REST and Streaming functionality and is a good starting point if the above examples aren't detailed enough.

Going Forward

Twitter-Starling is still in active development.

Most of the functionality is there, but some testing is lacking (there are no unit tests, oh dear!) so you can continue to use it but it would not be advisable to do so on production systems. not yet at least.

Where do I get the source code?

Check the GitHub repo here:

I want to contribute

Contact me (Sean Nicholls) on GitHub

The biggest need right now is full documentation of the library. So if you're documentally inclined, get in touch!


MIT License - fork, modify and use however you want.