Twitter API ME: Quick Tutorial

Hi all,

Such as I advanced in Twitter API ME's announcement post, here it goes some code snippets to demonstrate how to use this API. In fact, I will consider this post as a first tutorial on Twitter API ME that will help you to get started. First of all, I will show you how to create a simple query, submit it to Twitter Search API and then present the result. So you will not see much detail in this quick tutorial. Actually, I am thinking of dedicating more posts to explain each class in detail. But for now, let's just see how it works.

Twitter API ME, such as Twitter API, is splitted into two main components: Search and REST APIs. Twitter API ME 1.0 just supports Search API services. So, for now, you will work with the package com.twitterapime.search only. This package contains all the classes that are responsible for submitting a query to Twitter and then getting the result. These are the main classes:

• Query
• QueryComposer
• SearchDevice
• Tweet

Query class wraps a string that represents a query, which is submitted to Twitter Search API. This query is in URL format. To compose a query, the developer can use the QueryComposer class. This class provides methods for most types of filters/parameters supported by Twitter Search API. For instance, QueryComposer.from(String) is used to create a query to search for all tweets submitted by a certain user; QueryComposer.contain(String), search for tweets that contain a given word, and so on.

It is also possible to create a query with more than one parameter. In this case, you can concatenate two queries, by calling the method QueryComposer.append(Query, Query). It will return a new query object with both queries concatenated.

SearchDevice class is the entry point to Twitter Search API. This class provides the methods to submit a query to Twitter and retrieve the search's result. Its use is very straighforward: create a query and pass to SearchDevice.searchTweets(Query) method. The return of this method is an array of Tweet objects. Tweet class represents a tweet: a Twitter's message.

To retrieve the tweet's info (e.g. message, author, publish date, etc.), just use one of its "get" methods (e.g. Tweet.getString(String)), passing one of the attributes defined by MetadataSet interface. The Tweet's attributes are represented by the contants that start with TWEET prefix, e.g., MetadataSet.TWEET_CONTENT.

Now let's show some code. This example demonstrates how to search for all the tweets sent by a given user (e.g. me) and that contains the word "F1" (we will get a lot of results :-)):

...
SearchDevice sd = SearchDevice.getInstance();
Query q1 = QueryComposer.from("ernandesmjr");
Query q2 = QueryComposer.contain("F1");
Query q3 = QueryComposer.append(q1, q2);
Tweet[] result = sd.searchTweets(q3);
for (int i = 0; i < 0; i++) {
 list.append(result[i].getString(MetadataSet.TWEET_CONTENT), null);
}
...

Let's search for tweets that references or mentions a certain person. In additional, we will request to Twitter Search API to return up to 5 tweets:

...
SearchDevice sd = SearchDevice.getInstance();
Query q1 = QueryComposer.reference("ernandesmjr");
Query q2 = QueryComposer.resultCount(5);
Query q3 = QueryComposer.append(q1, q2);
Tweet[] result = sd.searchTweets(q3);
for (int i = 0; i < 0; i++) {
 System.out.println(result[i].getString(MetadataSet.TWEET_CONTENT));
 System.out.println(result[i].getString(MetadataSet.TWEET_PUBLISH_DATE));
}
...

It is easy, isn't it? The rest, for while, is just a matter of discovering the others methods available in thoses classes. But the main use is what is described in these code snippets. More details you can check on javadoc.

See you in the nest post...