Filtered Streams

Overview

Like the sample stream, the filtered streams is a stream only returning tweets. 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: tracks, locations, and users.

*IMPORTANT SECTION: Please take few minutes to read the first section of this page: Start Stream.

When you are done with this section please read the following:

1. Filtered Stream Events
2. Filter by keywords and type of tweets using the AddTrack method.
3. Filter by location using the AddLocation method.
4. 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();

Start Stream

I need to insist and say that this section is important. As mentioned in the overview, the filtered streams can be filtered by three types of filters.

What I consider important to understand is that Twitter does not consider these 3 types of filter as being 'AND' filters. Instead type of filter is an 'OR' filter. Let's take an example to explain how twitter works.

Twitter Stream Behavior

Let's consider a stream with three filters. A first filter on the keyword 'tweetinvi' (track filter). A second filter to get tweets from 'New York' (location filter). And finally a third filter specifying that the stream needs to return the tweets from the user 'ladygaga' (follow filter).

When running this stream, Twitter will sends all the tweets if they EITHER contain the keyword 'tweetinvi' OR if the tweet was published from 'New York' OR if the tweet has been created by 'ladygaga'.

Tweetinvi Behavior - All vs. Any

• When using the StartStreamMatchingAnyConditions method to start the stream, Tweetinvi will return the tweets matching EITHER of the filter types.

• When using the StartStreamMatchingAllConditions method to start the stream, Tweetinvi will return the tweets matching ALL of the filter types.

Events

• MatchingTweetReceived will return all the tweets matching the criteria with the set of keywords (tracks) that matched the tweet.
• MatchingTweetAndLocationReceived will return the same information as MatchingTweetReceived but in addition will provide the matching location information.

Please note that you can easily get the information concerning followed users. When the event is received, just check if Tweet.CreatedBy.Id exist in the collection of user ids that the stream follows.

Filter by Track and Keywords

The first and most used filter is keywords. Twitter parameter is named Track. Tweetinvi respected their naming choice and called them tracks too.

As a first note, please be aware that a track cannot contain more than 60 characters.

OR OPERATOR: You can add multiple tracks to the same filtered stream. When you do, twitter consider them as OR conditions. Adding 'tweetinvi' as a first track and 'linvi' in a second track will result in a stream that returns all tweets mentioning 'tweetinvi' OR 'linvi'.

AND OPERATOR: Separating multiple keywords within the same track, with a single space, enables you to use the AND operator. For example using the track 'tweetinvi linvi' will make the stream only return tweets that contains both 'tweetinvi' AND 'linvi'.

Track URL: Please be aware that if you want to track an URL the 'wwww.' must be omitted. Failure to do so will result in the stream to not return any result for this specific track.

Example:

// Let's get tweets containing 'linvi' 
stream.AddTrack("linvi");

// OR tweets containing both 'tweetinvi' AND 'rocks'.
stream.AddTrack("tweetinvi rocks");

Filter by locations

Twitter also allows you to filter tweets based on their geographic coordinates. The 2 coordinates represent a square box.

// Either provide the two coordinates
stream.AddLocation(new Coordinates(-74,40), new Coordinates(-73,41));

// Or a location object
var centerOfNewYork = new Location(new Coordinates(-74,40), new Coordinates(-73,41));
stream.AddLocation(centerOfNewYork);

I like to use .AddLocation(top_left, bottom_right).

Filter by users

Finally, the filtered streams can be filtered by users. The stream will return tweets created by the specified user. Like the two previous filters, you can simply add a user with the stream.AddFollow method.

// Using a user id
fs.AddFollow(387394843894);

// Using a user
fs.AddFollow(user);