We provide APIs for classifying tweets. This allows you to integrate our sentiment analysis classifier into your site or product.
You may register your application at http://help.sentiment140.com/api/registration.
Please provide an appid parameter in your API requests. The appid value 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:
where firstname.lastname@example.org is the main contact. You may URL-encode the appid value.
Technically you can use the API without supplying the appid parameter. But, we may block the requests that don't have an appid specified if we suspect abuse.
For use of the API in commercial applications, please see the commercial licensing page.
Please sign up on our mailing list to receive announcements about any changes.
This is the recommended way to utilize our API. You can send thousands of tweets per request, and receive the responses in bulk.
RequestsRequests should be sent via HTTP POST to http://www.sentiment140.com/api/bulkClassifyJson. The body of the message should be a JSON object. Here are some example requests:
Example 1 - Basic example
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 - Passing auxiliary fields
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 data fields besides "text", "query", and "polarity" are not examined by the classifier and are simply copied to the response.
You can include a "query" parameter, which specifies what the tweet is about. It's recommended that you provide the query term. The query parameter helps us prevent certain keywords from influencing sentiment. For example, if the query was "Horrible Bosses" (referring to the 2011 movie), supplying the query parameter would help us know that "horrible" is actually part of the query and shouldn't contribute to the calculated sentiment.
Example 3 - Specifying the query
The query field can handle multiple terms if you use the OR operator. The syntax is term1 OR term2 (e.g., Bill Gates OR Steve Ballmer).
Example 4 - Specifying a language
We currently support English and Spanish. We assume tweets are English by default, but you can force the Spanish model by supplying a language parameter:
If you want us to auto-detect the language, set the value of language to "auto":
Example 5 - Specifying a topic
The words that people use to express sentiment can vary greatly between topics. For example, consider the word "scary." It's positive if you find Silence of the Lambs is scary, but negative if your Toyota's brakes are scary. By default, we use a generic sentiment model that works okay across different domains. But, if you supply a topic, we use a domain-specific classifier on the backend that can provide better accuracy.
In the API, include a "topic" parameter that specifies the subject domain of the tweet. Currently the only valid value for the "topic" parameter is "movies", but we are adding more.
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:
The polarity values are:
Example command-line usage:
Here's an example command you can run on a Linux shell that shows an example request and response:
The response will look something like this:
This API allows you to classify tweets individually via HTTP GET requests. The request looks like this:
You should NOT use this API if you are classifying tweets in bulk. Instead, use the Bulk Classification Service, which is much more efficient for us in terms of cost.
If you do not provide an appid (see above) and you use this API at a very high rate (greater than 1 qps), we will have to blacklist you. We love providing our service, but running the service isn't free.
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.
The response will be a CSV with two fields: