Vptweetstream NPM

VoxPelli Tweet Streamer

A library for Twitters realtime streaming API that among other things has support for updating a stream on the fly without losing any tweets along the way and special support for tracking tweets from users in a way similar to Twitter lists by filtering away non-related tweets.

It's a work in progress - feel free to fork away but don't expect anything :)

Usage

Simple:

require('vptweetstream')
  .stream('username', 'password', { track : ['keyword1'] });
  .events.on('tweet', function (tweet) {
    // The full tweet object from Twitter
  });

Advanced:

var vptweetstream = require('vptweetstream'), stream;

stream = vptweetstream.stream('username', 'password', {
  follow : ['voxpelli', 'github'],    // tweets related to @voxpelli or @github
  track : ['keyword1', 'keyword2'],   // keyword1 OR keyword2
  locations : [
    ['-122.75,36.8', '-121.75,37.8'], // San Fransisco
    ['-74,40', '-73,41']              // OR New York
  ],
  realfollow : true // Only show tweets from someone in the follow array
});

stream.events.on('tweet', function (tweet) {
  // The full tweet object from Twitter
});

stream.events.on('skip count', function (count) {
  // Twitter skipped some tweets due to high volume, this is the amount skipped
});

// Change what is tracked on the fly
// The stream will change to track just "apple" as soon as possible
stream.changeStream({ track : ['apple'] });

Advanced options

follow - an array of Twitter usernames to follow. Any tweet related to one of these users will be included in the stream, see Twitter's documentation for which kind of tweets that are included.
track - an array of keywords to track. If a tweet includes the keyword in any variation it will be included in the stream, see Twitter's documentation for all variations.
locations - either just a simple array containing the longitude and latitutude positions as two strings or an array containing several such arrays. Any tweet from within any of the specified bounding boxes will be included in the stream.
realfollow - used with follow to simulate something like a Twitter list where only the tweets that's actually from the followed persons are included. Set to true to activate.

Events

tweet - triggered whenever a new tweet is received in the stream. A full tweet object is sent as the first argument, see Twitter's documentation for what such an object looks like.
skip count - triggered when Twitter has skipped some tweets in its stream due to high volume. The amount of tweets skipped is sent as the first argument.

Currently supported message types

Twitter's streaming API contains many message types, these are the ones that are currently supported:

limit
tweets
warning (barely supported, will emit custom warning to the console)
delete (barely supported, will emit custom warning to the console)

Non-supported message types will result in warnings being written to the console.

Possible future features

OAuth support - Twitter promotes the use of this instead of passwords and it's better so it should be supported
More message types
More events