API

Notice: Twitter Sentiment has changed to Sentiment140. The documentation on this page is deprecated.

We provide APIs for classifying tweets. This allows you to integrate our sentiment analysis classifier into your site or product. If you plan on integrating this API into a product, please sign up for the following mailing list to receive announcements about any changes. Moreover, if you plan on using this for commercial purposes, please contact us.

Please include an appid parameter in the HTTP endpoint of your API calls. The value of appid should be an email address we can contact. For example, if you are using the JSON Bulk Classification API, the HTTP endpoint that you use to send requests may look like this: http://twittersentiment.appspot.com/api/bulkClassifyJson?appid=bob@apple.com, where bob@apple.com is the main contact.


Bulk Classification Service (JSON) - Recommended

This is the recommended way to utilize our API. You can send thousands of tweets per request, and receive the responses in bulk.

Requests
Requests should be sent via HTTP POST to 
http://twittersentiment.appspot.com/api/bulkClassifyJson. The body of the message should be a JSON object. Here are some example requests:

Example 1 (simple):
{"data": [{"text": "I love Titanic."},
          {"text": "I hate Titanic."}]}

In this example, you send a JSON array inside a JSON object's "data" field. Each item should have a field called "text".

Example 2 (with auxiliary fields):
{"data": [{"text": "I love Titanic.", "id": 1234},
          {"text": "I hate Titanic.", "id": 4567}]}

You can also include auxiliary fields ("id" in this case), which will be copied to the response. This is useful if you need to match the request items to the response items. Any fields besides "text", "query", and "polarity" are not examined by the classifier and are simply copied to the response.

Example 3 (with query parameter):
{"data": [{"text": "I love Titanic.", "query": "Titanic", "id": 1234},
          {"text": "I hate Titanic.", "query": "Titanic", "id": 4567}]}

You can provide a "query" term, which specifies what the tweet is about. It's recommended that you provide the query term.

Response Body:
The response will be the same as the request, except a new field "polarity" added to each object. For example, the response for Example 2 above will look like the following:

{"data": [{"text": "I love Titanic.", "id":1234, "polarity": 4},
          {"text": "I hate Titanic.", "id":4567, "polarity": 0}]}

The polarity values are:
  • 0: negative
  • 2: neutral
  • 4: positive

Example command-line usage:
Here's an example command you can run on a Linux shell that shows an example request and response:
$ curl -d "{'data': [{'text': 'I love Titanic.'}]}" http://twittersentiment.appspot.com/api/bulkClassifyJson
{"data":[{"text":"I love Titanic.","polarity":4}]}

Simple Classification Service (JSON)

This API allows you to classify tweets individually via HTTP GET requests. The request looks like this:
http://twittersentiment.appspot.com/api/classify?text=new+moon+is+awesome&query=new+moon&callback=myJsFunction

Please see the Bulk Classification Service if you want to classify many tweets per request.

Request Parameters:
  • text: The text you want to classify. This should be URL encoded.
  • query: The subject. This should be URL encoded. (optional)
  • callback: The callback function (optional). Leave this out if you want a pure JSON object returned.
Response Data:
  • text: original text submitted
  • query: original query submitted
  • polarity. The polarity values are:
    • 0: negative
    • 2: neutral
    • 4: positive


Bulk Classification Service (CSV)

This makes it easy to use Linux's curl program to send tweets to be classified in bulk. You can send a very simple text file of tweets.

Example Request
  1. Create a file called obama.txt with the following content:
    obama is awesome
    obama sucks
    obama is eating a potato
  2. Run the following command (one line):
    curl --data-binary @obama.txt "http://twittersentiment.appspot.com/api/bulkClassify?query=obama

    In case you're not familiar with curl, the --data-binary flag tells curl to preserve the new line character in the sent data set, and the @obama.txt tells curls which filename to read the data from.

Output:

The response will be a CSV with two fields:
  • polarity. The polarity values are:
    • 0: negative
    • 2: neutral
    • 4: positive
  • the text
Notes:
  • The query parameter tells us what we should be classifying the sentiment towards. It's optional.
  • This API should work for up to 10,000 tweets per call. You can perform multiple calls.
Comments