Sentiment Analysis

Analyzes text for positive or negative sentiment.

The Sentiment Analysis API analyzes text to return the sentiment as positive, negative, neutral, or mixed. It contains a dictionary of positive and negative words of different types, and defines patterns that describe how to combine these words to form positive and negative phrases.

You can use sentiment analysis to gain valuable insights into what users, customers, friends, and colleagues are saying.

Automatically classifying text by sentiment allows you to easily find out the general opinions of people in your area of interest. For example, you might want to analyze reviews of a product to help you improve the customer experience, or to find the most or least popular product.

Quick Start

The Sentiment Analysis API takes text input, which you can provide in the text parameter. You can also use a URL or a Haven OnDemand object store reference, or you can upload a file in a POST request. You can provide multiple inputs by specifying multiple input parameters.

By default, the API runs in English. For example:

/1/api/[async|sync]/analyzesentiment/v2?text=I like cats

You can run the same query in a different language by adding the language parameter. The following example sets it to French:

/1/api/[async|sync]/analyzesentiment/v2?text=J'aime les chats&language=fre

The API splits the text that you input into entities, which describe a part of the text with a particular sentiment. The API returns details of the extracted entities, including the length, and the detected sentiment.

For example, for the English query.

{
   sentiment_analysis: [
      {
         positive: [
            {
               sentiment: "like",
               topic: "cats",
               score: 0.6085845466635199,
               original_text: "i like cats",
               original_length: 11,
               normalized_text: "i like cats",
               normalized_length: 11,
               offset: 0
            }
         ],
         negative: [ ],
         aggregate: {
            sentiment: "positive",
            score: 0.6085845466635199
         }
      }
   ]
}

The API can extract positive and negative phrases from the text input. Each of the sentiments extracted contains some valuable information.

  • sentiment is the qualifier for the sentiment, in this case the verb like.
  • topic indicates what the positive or negative sentiment was about, in this case cats.
  • score is a value between 0 and 1 (0 and -1 in the negative case), which indicates the strength and confidence of the sentiment.

With the use of stronger words, the scores are larger.

/1/api/[async|sync]/analyzesentiment/v2?text=I really like cats

positive: [
   {
      sentiment: "really like",
      topic: "cats",
      score: 0.7614534295773973,

Sometimes the text input contains more than one sentiment. For example:

/1/api/[async|sync]/analyzesentiment/v2?text=I like dogs but I hate cats

{
   sentiment_analysis: [
      {
         positive: [
            {
               sentiment: "like",
               topic: "dogs",
               score: 0.6085845466635199,
               original_text: "I like dogs",
               original_length: 11,
               normalized_text: "I like dogs",
               normalized_length: 11,
               offset: 0
            }
         ],
         negative: [
            {
               sentiment: "hate",
               topic: "cats",
               score: -0.9340398985983612,
               original_text: "but I hate cats",
               original_length: 15,
               normalized_text: "but I hate cats",
               normalized_length: 15,
               offset: 12
            }
         ],
         aggregate: {
            sentiment: "negative",
            score: -0.16272767596742066
         }
      }
   ]
}

Here, Haven OnDemand has extracted a positive sentiment about dogs but a negative sentiment about cats. In this case, it uses the strength of the word. hate is stronger than like and so it is weighted at 93%, while like has a weight of 61%.

The aggregate portion of the results takes into account all of the sentiments extracted to provide an overview. In this case an overall negative sentiment, because of the opposition of positive and negative, and an overall negative score of -0.16, because of the strength of the words used.

A sentence without any sentiment score results in a neutral aggregate response. For example:

/1/api/[async|sync]/analyzesentiment/v2?text=your blue hat is on the chair and dinner is on the table

{
   sentiment_analysis: [
      {
         positive: [ ],
         negative: [ ],
         aggregate: {
            sentiment: "neutral",
            score: 0
         }
      }
   ]
}

If the text contains both positive and negative statements, and the aggregate score is near zero (between -0.025 and 0.025), the API returns the aggregate sentiment as mixed. The aggregate sentiment can also be slightly positive or slightly negative when the score is small but not that close to zero (between 0.025 and 0.1, or -0.025 and -0.1).

Automatically classifying text by sentiment allows you to easily find out the general opinions of people in your area of interest. For example, you might want to analyze reviews of a product to help you improve the customer experience, or identify highly relevant issues or strong points in the product or the competition.

/1/api/[async|sync]/analyzesentiment/v2?text=this product is amazing! I really like the battery life

When you are using English sentiment analysis, you can use the mode parameter to specify whether to prioritize the quality or number of result matches.

By default, mode is set to precision, which tries to find the highest confidence sentiment matches. This option might give better results for longer documents. You can set mode to recall if you want to return more matches, which might be lower quality matches. This option might be appropriate for short documents, such as feedback surveys or tweets, because it picks up additional sentiment matches from short fragments.

Haven OnDemand recommends testing the different mode options with your data to see which method gives you the best results.

Note: If you use the mode parameter for non-English input text, it has no effect.

You can also use files as input. In this case, the API first sends the file to the Text Extraction API before analyzing the sentiment. For example:

curl -X POST http://api.havenondemand.com/1/api/[async|sync]/analyzesentiment/v2 --form "file=@myreviews.txt"

If you specify multiple files or text inputs in the request, the API returns each result as a separate item in the response array, with its own aggregate score.

Note: API input is subject to a maximum size quota. If you upload text or a file that is too large, the API returns an error. For more information, see Rate Limiting, Quotas, Data Expiry, and Maximums.

Synchronous
https://api.havenondemand.com/1/api/sync/analyzesentiment/v2
Asynchronous
https://api.havenondemand.com/1/api/async/analyzesentiment/v2
Authentication

This API requires an authentication token to be supplied in the following parameter:

Parameter Description
apikey The API key to use to authenticate the API request.
Parameters

This API accepts the following parameters:

Required
Name Type Description
file
array<binary> A file containing the document to process. Multipart POST only.
reference
array<string> A Haven OnDemand reference obtained from either the Expand Container or Store Object API. The corresponding document is passed to the API.
text
array<string> The text content to process.
url
array<string> A publicly accessible HTTP URL from which the document can be retrieved.
Optional
Name Type Description
language
enum The language of your source text. Default value: eng.
mode
enum The type of relevance measure to prioritize when determining matches. Default value: precision.
Enumeration Types

This API's parameters use the enumerations described below:

language
The language of your source text.
eng English
fre French
spa Spanish
ger German
ita Italian
chi Chinese
por Portuguese
dut Dutch
rus Russian
cze Czech
tur Turkish
mode
The type of relevance measure to prioritize when determining matches.
precision precision
Prioritize precision.
recall recall
Prioritize recall.

This API returns a JSON response that is described by the model below. This single model is presented both as an easy to read abstract definition and as the formal JSON schema.

Asynchronous Use

Additional requests are required to get the result if this API is invoked asynchronously.

You can use /1/job/status/<job-id> to get the status of the job, including results if the job is finished.

You can also use /1/job/result/<job-id>, which waits until the job has finished and then returns the result.

Model
This is an abstract definition of the response that describes each of the properties that might be returned.
Sentiment Analysis Response {
sentiment_analysis ( array[object] ) The details for the sentiment in the text input.
}
Model Schema
This is a JSON schema that describes the syntax of the response. See json-schema.org for a complete reference.
{
    "entity": {
        "items": {
            "properties": {
                "normalized_length": {
                    "type": "number"
                },
                "normalized_text": {
                    "type": "string"
                },
                "original_length": {
                    "type": "number"
                },
                "original_text": {
                    "type": "string"
                },
                "score": {
                    "type": "number"
                },
                "sentiment": {
                    "type": [
                        "string",
                        "null"
                    ]
                },
                "topic": {
                    "type": [
                        "string",
                        "null"
                    ]
                },
                "offset": {
                    "type": "integer"
                }
            },
            "required": [
                "sentiment",
                "topic",
                "score",
                "original_text",
                "normalized_text",
                "normalized_length",
                "original_length",
                "offset"
            ],
            "type": "object"
        },
        "type": "array"
    },
    "text_sentiment": {
        "items": {
            "aggregate": {
                "properties": {
                    "score": {
                        "type": "number"
                    },
                    "sentiment": {
                        "enum": [
                            "negative",
                            "slightly negative",
                            "mixed",
                            "slightly positive",
                            "positive",
                            "neutral"
                        ]
                    }
                },
                "required": [
                    "sentiment",
                    "score"
                ],
                "type": "object"
            },
            "negative": {
                "$ref": "#/entity"
            },
            "positive": {
                "$ref": "#/entity"
            },
            "required": [
                "positive",
                "negative",
                "aggregate"
            ],
            "type": "object"
        },
        "type": "array"
    },
    "properties": {
        "sentiment_analysis": {
            "$ref": "#/text_sentiment"
        }
    },
    "required": [
        "sentiment_analysis"
    ],
    "type": "object"
}
https://api.havenondemand.com/1/api/sync/analyzesentiment/v2
/api/api-example/1/api/sync/analyzesentiment/v2
Examples
See this API for yourself - select one of our examples below.
Negative Sentiment
I am really annoyed with your poor performance recently
Positive Sentiment
Hey, good job with that thing you did recently
Parameters
Required
Add another value
Select files Change Remove
Add another value
Add another value
Optional
Name Type Value
language
enum
mode
enum


ASync – Response An error occurred making the API request
Response Code:
Response Body

	
Making API Request…
Checking result of job

To try this API with your own data and use it in your own applications, you need an API Key. You can create an API Key from your account page - API Keys.

Output Refresh An error occurred making the API request View Input
Rendered RawHtml Response
Result Display
Response Code:
Response Body:

			
Make this call with curl

Version 2 (2016-09-26)

This page outlines the changes to the Sentiment Analysis API from the previous version.

  • The mode parameter has been added to allow you to prioritize precision (high-confidence matches) or recall (returning more possible matches).
  • The response format has been improved. In particular, when you send multiple text inputs or files in the request, the analysis for each item is now returned separately in an array, with its own aggregate score, rather than being merged into a single aggregate. Additionally, the documentindex response field is no longer returned. The results are now returned in the same order as the parameters in the request, so this response field is not required.
  • The aggregate score now returns mixed rather than neutral if an entity had both positive and negative matches, but the score was within 0.025 of zero.
  • The aggregate score now returns slightly positive and slightly negative results for scores between 0.025 and 0.1, and -0.025 and -0.1 respectively.
  • Entities now return the character offset of the match in the original text.


If you would like to provide us with more information then please use the box below:

We will use your submission to help improve our product.