Skip to content

Streams

Jump to bottom
linvi edited this page Nov 1, 2016 · 19 revisions

Overview

Streams are very powerful tools that most Twitter developers should use. They give access to live information as it occurs on Twitter. Streams are at the core of Tweetinvi. In fact Tweetinvi was initially created for streaming purposes only.

First of all I will give you a quick demonstration on how to use streams.

Twitter exposes 3 types of streams in the Public API.

  • Sample Stream: Returns random public tweets
  • User Stream: Live information of any event that happens for a specific user
  • Filtered Stream: Returns all public tweets matching a specific set of criteria

*IMPORTANT NOTE : Each of these streams are limited to return up to 1% of the total tweets posted on Twitter. This is specifically relevant for Filtered Streams. With Filtered Streams, this rule means that if your filters criteria are too wide and would return more than 1% of the total tweets posted on Twitter, the Stream API will not return all the tweets.

How to use the streams?

Whilst you'll probably want to register for different events based on the stream you are using, streams share some methods, events, and logic.

First of all each of the different types of streams are created from the static class Stream within the Tweetinvi namespace. This is done using the Stream.Create...Stream() where '...' represents the type of the stream.

Start, Pause, Resume

Each type of stream can be paused, resumed, and stopped. When they do, an event is raised to inform you that the running state of the stream has changed.

// Start
stream.StartStream();
// And its associated event
stream.StreamStarted += (sender, args) => { };

// ...
stream.PauseStream();
stream.ResumeStream();

When invoking any of these methods, the stream.StreamState property will be updated. You can use this property to detect the current state of a stream.

Stop and Error handling

The StreamStopped event is different from the three others as it also gives information of the reason why the stream was stopped. The reason can be a problem with your connection or Twitter Stream API, which for some reason decides that your stream needs to be closed. This information can be retrieved from the event args of the event.

stream.StreamStopped += (sender, args) =>
{
    var exceptionThatCausedTheStreamToStop = args.Exception;
    var twitterDisconnectMessage = args.DisconnectMessage;
};

Stream Parameters

Streams share a small set of optional parameters that you can set up.

// Filter Tweets by Languages
stream.AddTweetLanguageFilter(LanguageFilter.English);
stream.AddTweetLanguageFilter("fr");

// You can define how restrictive your tweets are
stream.FilterLevel = StreamFilterLevel.Low;

// This option allows the application to get notified 
// if the stream is about to be disconnected
stream.StallWarnings = true;

Please note that the StallWarnings must be set to true in order to receive events from stream.WarningFallingBehindDetected.

Stream Events

Tweetinvi streams use events to notify users that it received a message from the Twitter stream.

Global Events

  • JsonObjectReceived: notifies that a json message has been received
  • UnmanagedEventReceived : notifies that a message that is not handled by Tweetinvi has been received
  • LimitReached : notifies that your stream attempts to access more than 1% of the total tweets published
  • DisconnectMessageReceived : notifies that Twitter has decided to shut down this stream connection

Tweet Events

  • TweetDeleted: notifies that a tweet has been deleted
  • TweetLocationInfoRemoved : notifies that the geo information of a tweet have been deleted

Withheld Events

  • TweetWitheld: notifies that a tweet has withheld within your country
  • UserWitheld: notifies that a user has been withheld within your country

Stream and Credentials

Before version 0.9.9.x, streams were using the credentials of the Thread invoking the StartStream method. To simplify the development of complex multi-threaded application a new mechanism is used by Streams to retrieve the credentials.

Version 0.9.10.x

  • All types of Streams now use the credentials of the thread where they are created. It means that if you create a stream in Thread1 and start a stream in Thread2, the stream will use the Thread1 credentials unless you modify them manually as explained few lines below.
// Thread1 credentials
Auth.SetUserCredentials(thread1Credentials);

// Create the stream and store the Thread1 credentials in stream.Credentials
stream = Stream.CreateFilteredStream();

// Thread2
var t = new Thread(() =>
{
    // Thread2 credentials
    Auth.SetUserCredentials(thread2Credentials);

    // Uses Thread1 credentials by default
    stream.StartStreamMatchingAllConditions();
});
  • All types of Streams can now be created by specifying an ITwitterCredentials. When this value is set, it will be used by the stream to authenticate.
var creds = new TwitterCredentials(...);
var stream = Stream.CreateSampleStream(creds);
  • Streams credentials can now be changed manually when the stream is NOT RUNNING.
var stream = Stream.CreateSampleStream();
// The stream currently uses the thread credentials
var newCreds= new TwitterCredentials(...);
stream.Credentials = newCreds; // The stream will now be using the newCreds

Sample Stream

The sample stream is the easiest type of stream to interact with. It simply returns 1% of all the public tweets published on Twitter at any time. Twitter randomly selects one tweet for every 100 tweets and publishes this Tweet in the stream.

This stream is quite interesting for researchers. Even though only 1% of the tweets are received you can often receive between 3 to 5 millions tweets in a day. With such a sample it is quite easy to perform some statistics.

Getting all these tweets with the library has been simplified to a simple event which is raised each time a tweet is received.

var stream = Stream.CreateSampleStream();
stream.TweetReceived += (sender, args) =>
{
    // Do what you want with the Tweet.
    Console.WriteLine(args.Tweet);
};
stream.StartStream();

User Streams

This type of stream is very useful. It allows you to get a wide variety of events related with a User. For example you can get informed when the user publishes a message, a friend or simply when anyone you follow does. You can get informed for incoming messages, new followers, new lists, and I could continue... (but I won't!)

Below you can find a quick example demonstrating how to get notified when a new user is following the AuthenticatedUser.

var stream = Stream.CreateUserStream();
stream.FollowedByUser += (sender, args) =>
{
    Console.WriteLine("You have been followed by " + args.User);
};
stream.StartStream();

More information on User Streams

Filtered Streams

Like the sample stream, the filtered streams is a stream returning tweets only. The difference between both of these streams is that you can filter the type of tweets returned by a filtered stream based on three criteria.

  1. Filter by keywords and type of tweets using the AddTrack method
  2. Filter by location using the AddLocation method
  3. Filter by user using the AddFollow method

When at least one filter has been set up, you can start the stream. You can set up each of the criteria at the same time and each of them can contain multiple values.

var stream = Stream.CreateFilteredStream();
stream.AddTrack("tweetinvi");
stream.MatchingTweetReceived += (sender, args) =>
{
    Console.WriteLine("A tweet containing 'tweetinvi' has been found; the tweet is '" + args.Tweet + "'");
};
stream.StartStreamMatchingAllConditions();

More information on Filtered Streams

Tweetinvi 5.0

Twitter API

Clone this wiki locally