TweetFeel TWITTER Sentiment API

Overview

The TweetFeel Twitter Sentiment API allows you programmatically discover real-time sentiment about a particular keyword or phrase using data from Twitter. You can track how your brand is perceived over time, discover customer pain points, or find real-life positive quotes that can help promote your product. More information and a web interface can be found at http://www.tweetfeel.com

The open version of the TweetFeel API only performs analysis on the 50 most recent positive/negative tweets on any given topic (not counting neutral tweets and most retweets). To access the full power of TweetFeel, please upgrade to a TweetFeel Biz account at http://tweetfeel.com/biz.

API KEYS

URL Syntax

The TweetFeel API is accessed using HTTP GET requests to the following URL:

http://svc.webservius.com/v1/tweetFeel/tfapi?
              wsvKey=[your API key]
              &keyword=[keyword]
              &type=[request type: pos, neg, all, or score (default)]
              &maxresults=[maximum results to return]

The parameters and the format of the results are explained in detail below.

Examples:

http://svc.webservius.com/v1/tweetFeel/tfapi?wsvKey=demo&keyword=coke
Returns the sentiment score for the keyword ‘coke’

http://svc.webservius.com/v1/tweetFeel/tfapi?wsvKey=demo&keyword=pepsi&type=neg
Returns recent negative Tweets for the keyword ‘pepsi’ (useful for discovering customer pain points)

http://svc.webservius.com/v1/tweetFeel/tfapi?wsvKey=demo&keyword=pepsi&type=pos
Returns recent positive Tweets for the keyword ‘pepsi’ (useful for proudly displaying real-time positive customer quotes on your site)

URL Parameters

wsvKey (required):

This is your API key, which is issued to you when you subscribe to the TweetFeel API. Note that the “K” in “wsvKey” is capitalized.

keyword (required):

This is the keyword that you would like to get the sentiment for. You can specify an entire phrase by URL-encoding it, e.g.:

http://svc.webservius.com/v1/tweetFeel/tfapi?wsvKey=demo&keyword=coca%20cola
Returns the sentiment score for the phrase ‘coca cola’

type(optional):

Allows you to choose the type of information that will be returned:

pos – Return positive Tweets
neg – Return negative Tweets
all – Return positive and negative Tweets
score – Only return the sentiment score, without any Tweets

If the type is not specified, “score” is used.

maxresults (optional)

Allows you to control the maximum number of Tweets that will be returned. By default, 50 Tweets will be provided. The Tweets will always be the most recent ones, regardless of the ‘maxresults’ setting.

http://svc.webservius.com/v1/tweetFeel/tfapi?wsvKey=demo&maxresults=10&type=pos&keyword=pepsi
Returns the 10 most recent positive tweets about the keyword ‘pepsi’

Although you can specify a number higher than 50 in ‘maxresults’, TweetFeel does not guarantee that more than 50 Tweets will be returned.

API Results

TweetFeel analyses all relevant Tweets (taking into account the maxresults and type paramteres), looking back as much as 1 week (the exact time limit is controlled by Twitter). It performs linguistic analysis on the Tweets (for a more tunable analysis, upgrade to a TweetFeel Biz account). Most re-tweets are removed.

Finally, a score is returned, which is simply the percentage of positive Tweets out of the total Tweets that show either positive or negative sentiment. Note that neutral Tweets (those that are neither positive nor negative) do not impact the score and are never returned by the TweetFeel API.

If the ‘type’ URL parameter is ‘all’, ‘pos’, or ‘neg’, specific Tweets are also returned. This allows you to discover the data behind the sentiment score – for example, you can find out about the actual pain points your customers are facing (by looking at the negative Tweets), or find real-life positive customer quotes (by looking at the positive Tweets).

Normally, the ‘maxresults’ parameter controls how many Tweets you will get. However, if there hasn’t been much Twitter traffic for a given keyword, less Tweets may be returned.

API Results Format

The results are returned in the JSON format (see http://www.json.org).

The format is as follows:

{
                “score”: [Percentage positive tweets (number)]
                “count”: [Number of tweets available (number)]
                “tweets”:
                [
                                {
                                                “tweet”: [Text of the tweet (string)]
                                                “type”:[String: Sentiment type of tweet – pos or neg (string)]
                                                “username”:[Twitter username of user posting the tweet (string)]
                                                “date”:[UTC Date/time of the Tweet, YYYY-MM-DD HH:MM:SS (string)]
                                }
                                …
                ]
}

The “tweets” member will be empty if the “type” parameter is missing in the request, or if type=score.

Example 1:

http://svc.webservius.com/v1/tweetFeel/tfapi?wsvKey=demo&keyword=pepsi
Returns the sentiment score for the keyword ‘pepsi’. Result:

{“score”:95,”count”:50,”tweets”:[]}

Example 2:

http://svc.webservius.com/v1/tweetFeel/tfapi?wsvKey=demo&keyword=pepsi&maxresults=2&type=all
Returns the 2 most recent tweets for the keyword ‘pepsi’. Result:

{“score”:50,”count”:2,”tweets”:[
{“tweet”:”I love Pepsi!”,”type”:”pos”,”username”:”pepsiLover”,”date”:”2009-12-31 21:05:46”},
{“tweet”:”I hate Pepsi!”,”type”:”neg”,”username”:”pepsiHater”,”date”:”2009-12-31 21:05:43”}
]}

If there is an error in the request, an HTTP response code in the 400 range will be returned (or in the 500 range if the error is on the TweetFeel side).

Questions?

Contact support@webservius.com