How to: Detect sentiment using the Text Analytics API

The Text Analytics API's Sentiment Analysis feature evaluates text and returns sentiment scores and labels for each sentence. This is useful for detecting positive and negative sentiment in social media, customer reviews, discussion forums and more. The AI models used by the API are provided by the service, you just have to send content for analysis.

Tip

Text Analytics also provides a Linux-based Docker container image for language detection, so you can install and run the Text Analytics container close to your data.

Sentiment Analysis supports a wide range of languages, with more in preview. For more information, see Supported languages.

Concepts

The Text Analytics API uses a machine learning classification algorithm to generate a sentiment score between 0 and 1. Scores closer to 1 indicate positive sentiment, while scores closer to 0 indicate negative sentiment. Sentiment analysis is performed on the entire document, instead of individual entities in the text. This means sentiment scores are returned at a document or sentence level.

The model used is pre-trained with an extensive corpus of text and sentiment associations. It utilizes a combination of techniques for analysis, including text processing, part-of-speech analysis, word placement, and word associations. For more information about the algorithm, see Introducing Text Analytics. Currently, it isn't possible to provide your own training data.

There's a tendency for scoring accuracy to improve when documents contain fewer sentences rather than a large block of text. During an objectivity assessment phase, the model determines whether a document as a whole is objective or contains sentiment. A document that's mostly objective doesn't progress to the sentiment detection phase, which results in a 0.50 score, with no further processing. For documents that continue in the pipeline, the next phase generates a score above or below 0.50. The score depends on the degree of sentiment detected in the document.

Sentiment Analysis versions and features

The Text Analytics API offers two versions of Sentiment Analysis - v2 and v3. Sentiment Analysis v3 (Public preview) provides significant improvements in the accuracy and detail of the API's text categorization and scoring.

Note

  • The Sentiment Analysis v3 request format and data limits are the same as the previous version.
  • Sentiment Analysis v3 is available in the following regions: Australia East, Central Canada, Central US, East Asia, East US, East US 2, North Europe, Southeast Asia, South Central US, UK South, West Europe, and West US 2.
Feature Sentiment Analysis v2 Sentiment Analysis v3
Methods for single, and batch requests X X
Sentiment scores for the entire document X X
Sentiment scores for individual sentences X
Sentiment labeling X
Model versioning X

Sentiment scoring

Sentiment Analysis v3 classifies text with sentiment labels (described below). The returned scores represent the model's confidence that the text is either positive, negative, or neutral. Higher values signify higher confidence.

Sentiment labeling

Sentiment Analysis v3 can return scores and labels at a sentence and document level. The scores and labels are positive, negative, and neutral. At the document level, the mixed sentiment label also can be returned without a score. 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

Model versioning

Note

Model versioning for sentiment analysis is available starting in version v3.0-preview.1.

Version 3 of the Text Analytics API lets you choose the model version that is most current for your data. Use the optional model-version parameter to select the version of the model that is desired for your requests. If this parameter isn't specified the API will default to latest, the latest stable version. Even though you can use the newest model-version in any request, only some features are updated in each version. The table below describes which features have been updated in each model version:

Model version Features updated Latest version for:
2020-02-01 Entity recognition Entity recognition
2019-10-01 Entity recognition, Sentiment analysis Language detection, Key phrase extraction, Sentiment analysis

Each response from the v3 endpoints includes a model-version field specifying the model version that was used.

{
    "documents": […]
    "errors": []
    "model-version": "2019-10-01"
}

See What's new for details on the updates for these model versions.

Example C# code

You can find an example C# application that calls this version of Sentiment Analysis on GitHub.

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.

Document size must be under 5,120 characters per document. You can have up to 1,000 items (IDs) per collection. 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.

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.

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

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 Sentiment Analysis request

The following is an example of content you might submit for sentiment analysis. The request format is the same for both versions of the API.

{
    "documents": [
    {
        "language": "en",
        "id": "1",
        "text": "Hello world. This is some input text that I love."
    },
    {
        "language": "en",
        "id": "2",
        "text": "It's incredibly sunny outside! I'm so happy."
    }
    ],
}

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

The sentiment analyzer classifies text as predominantly positive or negative. It assigns a score in the range of 0 to 1. Values close to 0.5 are neutral or indeterminate. A score of 0.5 indicates neutrality. When a string can't be analyzed for sentiment or has no sentiment, the score is always 0.5 exactly. For example, if you pass in a Spanish string with an English language code, the score is 0.5.

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.

Sentiment Analysis v3 example response

Responses from Sentiment Analysis v3 contain sentiment labels and scores for each analyzed sentence and document. documentScores is not returned if the document sentiment label is mixed.

{
    "documents": [
        {
            "id": "1",
            "sentiment": "positive",
            "documentScores": {
                "positive": 0.98570585250854492,
                "neutral": 0.0001625834556762,
                "negative": 0.0141316400840878
            },
            "sentences": [
                {
                    "sentiment": "neutral",
                    "sentenceScores": {
                        "positive": 0.0785155147314072,
                        "neutral": 0.89702343940734863,
                        "negative": 0.0244610067456961
                    },
                    "offset": 0,
                    "length": 12
                },
                {
                    "sentiment": "positive",
                    "sentenceScores": {
                        "positive": 0.98570585250854492,
                        "neutral": 0.0001625834556762,
                        "negative": 0.0141316400840878
                    },
                    "offset": 13,
                    "length": 36
                }
            ]
        },
        {
            "id": "2",
            "sentiment": "positive",
            "documentScores": {
                "positive": 0.89198976755142212,
                "neutral": 0.103382371366024,
                "negative": 0.0046278294175863
            },
            "sentences": [
                {
                    "sentiment": "positive",
                    "sentenceScores": {
                        "positive": 0.78401315212249756,
                        "neutral": 0.2067587077617645,
                        "negative": 0.0092281140387058
                    },
                    "offset": 0,
                    "length": 30
                },
                {
                    "sentiment": "positive",
                    "sentenceScores": {
                        "positive": 0.99996638298034668,
                        "neutral": 0.0000060341349126,
                        "negative": 0.0000275444017461
                    },
                    "offset": 31,
                    "length": 13
                }
            ]
        }
    ],
    "errors": []
}

Summary

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

  • Sentiment Analysis is available for selected languages in two versions.
  • 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.
  • 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