Asynchronous Twitter REST/stream/search client API for node.js
Clone or download
#145 Compare This branch is 105 commits ahead, 21 commits behind jdub:master.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.
lib using 1.1 Sep 14, 2012
test fix twitter trends endpoint Sep 1, 2012
LICENSE The big shift from twitter-node to node-twitter. Oct 17, 2010 Update Oct 14, 2014
index.js move more firmly away from node-twitter as npm/lib name Dec 22, 2010
package.json [dist] Version bump, v0.5.0 Sep 14, 2012


This repository has been unmaintained for two years, is deprecated on npm, and should not be considered an authoritative source of anything. Sorry for the inconvenience.

Asynchronous Twitter client API for node.js

ntwitter is an improved version of jdub's node-twitter, which in turn was inspired by, and uses some code from, technoweenie's twitter-node.


You can install ntwitter and its dependencies with npm: npm install ntwitter.

Getting started

This library is, for the most part, the same API as node-twitter. Much of the documentation below is straight from node-twitter - credit goes to jdub for putting all this together in the first place.

The most significant API change involves error handling in callbacks. Callbacks now receive the error as a separate parameter, rather than as part of the data. This is consistent with node's standard library. Callbacks should now look something like this:

function (err, result) {
  if (err) return callback(err);

  // Do something with 'result' here

Where callback is the parent function's callback. (Or any other function you want to call on error.)

Setup API

The keys listed below can be obtained from after setting up a new App.

var twitter = require('ntwitter');

var twit = new twitter({
  consumer_key: 'Twitter',
  consumer_secret: 'API',
  access_token_key: 'keys',
  access_token_secret: 'go here'


Interaction with other parts of Twitter is accomplished through their RESTful API. The best documentation for this exists at Convenience methods exist for many of the available methods, but some may be more up-to-date than others. If your Twitter interaction is very important, double-check the parameters in the code with Twitter's current documentation.

Note that all functions may be chained:

  .verifyCredentials(function (err, data) {
  .updateStatus('Test tweet from ntwitter/' + twitter.VERSION,
    function (err, data) {

Search API'nodejs OR #node', {}, function(err, data) {

Streaming API

The stream() callback receives a Stream-like EventEmitter.

Here is an example of how to call the statuses/sample method:'statuses/sample', function(stream) {
  stream.on('data', function (data) {

Here is an example of how to call the 'statuses/filter' method with a bounding box over San Fransisco and New York City ( see streaming api for more details on locations ):'statuses/filter', {'locations':'-122.75,36.8,-121.75,37.8,-74,40,-73,41'}, function(stream) {
  stream.on('data', function (data) {

ntwitter also supports user and site streams:'user', {track:'nodejs'}, function(stream) {
  stream.on('data', function (data) {
  stream.on('end', function (response) {
    // Handle a disconnection
  stream.on('destroy', function (response) {
    // Handle a 'silent' disconnection from Twitter, no end/error event fired
  // Disconnect stream after five seconds
  setTimeout(stream.destroy, 5000);


Lots of people contribute to this project. You should too!