How to: Sentiment analysis and Opinion Mining

The Text Analytics API's Sentiment Analysis feature provides two ways for detecting positive and negative sentiment. If you send a Sentiment Analysis request, the API will return sentiment labels (such as "negative", "neutral" and "positive") and confidence scores at the sentence and document-level. You can also send Opinion Mining requests using the Sentiment Analysis endpoint, which provides granular information about the opinions related to words (such as the attributes of products or services) in the text.

The AI models used by the API are provided by the service, you just have to send content for analysis.

Sentiment Analysis versions and features

Feature Sentiment Analysis v3.0 Sentiment Analysis v3.1
Methods for single, and batch requests X X
Sentiment Analysis scores and labeling X X
Linux-based Docker container X
Opinion Mining X

Sentiment Analysis

Sentiment Analysis in version 3.x applies sentiment labels to text, which are returned at a sentence and document level, with a confidence score for each.

The labels are positive, negative, and neutral. At the document level, the mixed sentiment label also can be returned. The sentiment of the document is determined below:

Sentence sentiment Returned document label
At least one positive sentence is in the document. The rest of the sentences are neutral. positive
At least one negative sentence is in the document. The rest of the sentences are neutral. negative
At least one negative sentence and at least one positive sentence are in the document. mixed
All sentences in the document are neutral. neutral

Confidence scores range from 1 to 0. Scores closer to 1 indicate a higher confidence in the label's classification, while lower scores indicate lower confidence. For each document or each sentence, the predicted scores associated with the labels (positive, negative and neutral) add up to 1. For more information, see the Text Analytics transparency note.

Opinion Mining

Opinion Mining is a feature of Sentiment Analysis, starting in version 3.1. Also known as Aspect-based Sentiment Analysis in Natural Language Processing (NLP), this feature provides more granular information about the opinions related to attributes of products or services in text. The API surfaces opinions as a target (noun or verb) and an assessment (adjective).

For example, if a customer leaves feedback about a hotel such as "The room was great, but the staff was unfriendly.", Opinion Mining will locate targets (aspects) in the text, and their associated assessments (opinions) and sentiments. Sentiment Analysis might only report a negative sentiment.

A diagram of the Opinion Mining example

To get Opinion Mining in your results, you must include the opinionMining=true flag in a request for sentiment analysis. The Opinion Mining results will be included in the sentiment analysis response. Opinion mining is an extension of Sentiment Analysis and is included in your current pricing tier.

Sending a REST API request

Preparation

Sentiment analysis produces a higher-quality result when you give it smaller amounts of text to work on. This is opposite from key phrase extraction, which performs better on larger blocks of text. To get the best results from both operations, consider restructuring the inputs accordingly.

You must have JSON documents in this format: ID, text, and language. Sentiment Analysis supports a wide range of languages. For more information, see Supported languages.

Document size must be under 5,120 characters per document. For the maximum number of documents permitted in a collection, see the data limits article under Concepts. The collection is submitted in the body of the request.

Structure the request

Create a POST request. You can use Postman or the API testing console in the following reference links to quickly structure and send one.

Request endpoints

Set the HTTPS endpoint for sentiment analysis by using either a Text Analytics resource on Azure or an instantiated Text Analytics container. You must include the correct URL for the version you want to use. For example:

Note

You can find your key and endpoint for your Text Analytics resource on the Azure portal. They will be located on the resource's Quick start page, under resource management.

Sentiment Analysis

https://<your-custom-subdomain>.cognitiveservices.azure.com/text/analytics/v3.1/sentiment

Opinion Mining

To get Opinion Mining results, you must include the opinionMining=true parameter. For example:

https://<your-custom-subdomain>.cognitiveservices.azure.com/text/analytics/v3.1/sentiment?opinionMining=true

This parameter is set to false by default.

Set a request header to include your Text Analytics API key. In the request body, provide the JSON documents collection you prepared for this analysis.

Example request for Sentiment Analysis and Opinion Mining

The following is an example of content you might submit for sentiment analysis. The request format is the same for both v3.0 and v3.1.

{
  "documents": [
    {
      "language": "en",
      "id": "1",
      "text": "The restaurant had great food and our waiter was friendly."
    }
  ]
}

Post the request

Analysis is performed upon receipt of the request. For information on the size and number of requests you can send per minute and second, see the data limits section in the overview.

The Text Analytics API is stateless. No data is stored in your account, and results are returned immediately in the response.

View the results

Output is returned immediately. You can stream the results to an application that accepts JSON or save the output to a file on the local system. Then, import the output into an application that you can use to sort, search, and manipulate the data. Due to multilingual and emoji support, the response may contain text offsets. See how to process offsets for more information.

Sentiment Analysis and Opinion Mining example response

Important

The following is a JSON example for using Opinion Mining with Sentiment Analysis, offered in v3.1 of the API. If you don't request Opinion mining, the API response will be the same as the Version 3.0 tab.

Sentiment Analysis v3.1 can return response objects for both Sentiment Analysis and Opinion Mining.

Sentiment analysis returns a sentiment label and confidence score for the entire document, and each sentence within it. Scores closer to 1 indicate a higher confidence in the label's classification, while lower scores indicate lower confidence. A document can have multiple sentences, and the confidence scores within each document or sentence add up to 1.

Opinion Mining will locate targets (nouns or verbs) in the text, and their associated assessment (adjective). In the below response, the sentence The restaurant had great food and our waiter was friendly has two targets: food and waiter. Each target's relations property contains a ref value with the URI-reference to the associated documents, sentences, and assessments objects.

The API returns opinions as a target (noun or verb) and an assessment (adjective).

{
  "documents": [
    {
      "id": "1",
      "sentiment": "positive",
      "confidenceScores": {
        "positive": 1,
        "neutral": 0,
        "negative": 0
      },
      "sentences": [
        {
          "sentiment": "positive",
          "confidenceScores": {
            "positive": 1,
            "neutral": 0,
            "negative": 0
          },
          "offset": 0,
          "length": 58,
          "text": "The restaurant had great food and our waiter was friendly.",
          "targets": [
            {
              "sentiment": "positive",
              "confidenceScores": {
                "positive": 1,
                "negative": 0
              },
              "offset": 25,
              "length": 4,
              "text": "food",
              "relations": [
                {
                  "relationType": "assessment",
                  "ref": "#/documents/0/sentences/0/assessments/0"
                }
              ]
            },
            {
              "sentiment": "positive",
              "confidenceScores": {
                "positive": 1,
                "negative": 0
              },
              "offset": 38,
              "length": 6,
              "text": "waiter",
              "relations": [
                {
                  "relationType": "assessment",
                  "ref": "#/documents/0/sentences/0/assessments/1"
                }
              ]
            }
          ],
          "assessments": [
            {
              "sentiment": "positive",
              "confidenceScores": {
                "positive": 1,
                "negative": 0
              },
              "offset": 19,
              "length": 5,
              "text": "great",
              "isNegated": false
            },
            {
              "sentiment": "positive",
              "confidenceScores": {
                "positive": 1,
                "negative": 0
              },
              "offset": 49,
              "length": 8,
              "text": "friendly",
              "isNegated": false
            }
          ]
        }
      ],
      "warnings": []
    }
  ],
  "errors": [],
  "modelVersion": "2020-04-01"
}

Summary

In this article, you learned concepts and workflow for sentiment analysis using the Text Analytics API. In summary:

  • Sentiment Analysis and Opinion Mining is available for select languages.
  • JSON documents in the request body include an ID, text, and language code.
  • The POST request is to a /sentiment endpoint by using a personalized access key and an endpoint that's valid for your subscription.
  • Use opinionMining=true in Sentiment Analysis requests to get Opinion Mining results.
  • Response output, which consists of a sentiment score for each document ID, can be streamed to any app that accepts JSON. For example, Excel and Power BI.

See also