Sentiment - Sentiment

The API returns a sentiment prediction, as well as sentiment scores for each sentiment class (Positive, Negative, and Neutral) for the document and each sentence within it. See the Supported languages in Text Analytics API for the list of enabled languages.

POST {Endpoint}/text/analytics/v3.0/sentiment
POST {Endpoint}/text/analytics/v3.0/sentiment?model-version={model-version}&showStats={showStats}

URI Parameters

Name In Required Type Description
Endpoint
path True
  • string

Supported Cognitive Services endpoints (protocol and hostname, for example: https://westus.api.cognitive.microsoft.com).

model-version
query
  • string

(Optional) This value indicates which model will be used for scoring. If a model-version is not specified, the API should default to the latest, non-preview version.

showStats
query
  • boolean

(Optional) if set to true, response will contain input and document level statistics.

Request Header

Media Types: "application/json", "text/json"

Name Required Type Description
Ocp-Apim-Subscription-Key True
  • string

Request Body

Media Types: "application/json", "text/json"

Name Required Type Description
documents True

The set of documents to process as part of this batch.

Responses

Name Type Description
200 OK

A successful call results in a document sentiment prediction, as well as sentiment scores for each sentiment class (Positive, Negative, and Neutral)

Media Types: "application/json", "text/json"

Other Status Codes

Error Response

Media Types: "application/json", "text/json"

Security

Ocp-Apim-Subscription-Key

Type: apiKey
In: header

Examples

Successful Sentiment request

Sample Request

POST {Endpoint}/text/analytics/v3.0/sentiment


{
  "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."
    },
    {
      "language": "en",
      "id": "3",
      "text": "Pike place market is my favorite Seattle attraction."
    }
  ]
}

Sample Response

{
  "documents": [
    {
      "id": "1",
      "sentiment": "positive",
      "confidenceScores": {
        "positive": 0.98,
        "neutral": 0.01,
        "negative": 0.01
      },
      "sentences": [
        {
          "text": "Hello world.",
          "sentiment": "neutral",
          "confidenceScores": {
            "positive": 0.07,
            "neutral": 0.91,
            "negative": 0.02
          },
          "offset": 0,
          "length": 12
        },
        {
          "text": "This is some input text that I love.",
          "sentiment": "positive",
          "confidenceScores": {
            "positive": 0.98,
            "neutral": 0.01,
            "negative": 0.01
          },
          "offset": 13,
          "length": 36
        }
      ],
      "warnings": []
    },
    {
      "id": "2",
      "sentiment": "positive",
      "confidenceScores": {
        "positive": 0.98,
        "neutral": 0.01,
        "negative": 0.01
      },
      "sentences": [
        {
          "text": "It's incredibly sunny outside!",
          "sentiment": "neutral",
          "confidenceScores": {
            "positive": 0.04,
            "neutral": 0.93,
            "negative": 0.03
          },
          "offset": 0,
          "length": 30
        },
        {
          "text": "I'm so happy.",
          "sentiment": "positive",
          "confidenceScores": {
            "positive": 0.98,
            "neutral": 0.01,
            "negative": 0.01
          },
          "offset": 31,
          "length": 13
        }
      ],
      "warnings": []
    },
    {
      "id": "3",
      "sentiment": "positive",
      "confidenceScores": {
        "positive": 0.98,
        "neutral": 0.01,
        "negative": 0.01
      },
      "sentences": [
        {
          "text": "Pike place market is my favorite Seattle attraction.",
          "sentiment": "positive",
          "confidenceScores": {
            "positive": 0.98,
            "neutral": 0.01,
            "negative": 0.01
          },
          "offset": 0,
          "length": 52
        }
      ],
      "warnings": []
    }
  ],
  "errors": [],
  "modelVersion": "2020-04-01"
}

Definitions

DocumentError
DocumentSentiment
DocumentSentimentValue

Predicted sentiment for document (Negative, Neutral, Positive, or Mixed).

DocumentStatistics

if showStats=true was specified in the request this field will contain information about the document payload.

ErrorCodeValue

Error code.

ErrorResponse
InnerError
InnerErrorCodeValue

Error code.

MultiLanguageBatchInput

Contains a set of input documents to be analyzed by the service.

MultiLanguageInput

Contains an input document to be analyzed by the service.

RequestStatistics

if showStats=true was specified in the request this field will contain information about the request payload.

SentenceSentiment
SentenceSentimentValue

The predicted Sentiment for the sentence.

SentimentConfidenceScorePerLabel

Represents the confidence scores between 0 and 1 across all sentiment classes: positive, neutral, negative.

SentimentResponse
TextAnalyticsError
TextAnalyticsWarning
WarningCodeValue

Error code.

DocumentError

Name Type Description
error

Document Error.

id
  • string

Document Id.

DocumentSentiment

Name Type Description
confidenceScores

Document level sentiment confidence scores between 0 and 1 for each sentiment class.

id
  • string

Unique, non-empty document identifier.

sentences

Sentence level sentiment analysis.

sentiment

Predicted sentiment for document (Negative, Neutral, Positive, or Mixed).

statistics

if showStats=true was specified in the request this field will contain information about the document payload.

warnings

Warnings encountered while processing document.

DocumentSentimentValue

Predicted sentiment for document (Negative, Neutral, Positive, or Mixed).

Name Type Description
mixed
  • string
negative
  • string
neutral
  • string
positive
  • string

DocumentStatistics

if showStats=true was specified in the request this field will contain information about the document payload.

Name Type Description
charactersCount
  • integer

Number of text elements recognized in the document.

transactionsCount
  • integer

Number of transactions for the document.

ErrorCodeValue

Error code.

Name Type Description
internalServerError
  • string
invalidArgument
  • string
invalidRequest
  • string
serviceUnavailable
  • string

ErrorResponse

Name Type Description
error

Document Error.

InnerError

Name Type Description
code

Error code.

details
  • object

Error details.

innererror

Inner error contains more specific information.

message
  • string

Error message.

target
  • string

Error target.

InnerErrorCodeValue

Error code.

Name Type Description
emptyRequest
  • string
invalidCountryHint
  • string
invalidDocument
  • string
invalidDocumentBatch
  • string
invalidParameterValue
  • string
invalidRequestBodyFormat
  • string
missingInputRecords
  • string
modelVersionIncorrect
  • string
unsupportedLanguageCode
  • string

MultiLanguageBatchInput

Contains a set of input documents to be analyzed by the service.

Name Type Description
documents

The set of documents to process as part of this batch.

MultiLanguageInput

Contains an input document to be analyzed by the service.

Name Type Description
id
  • string

A unique, non-empty document identifier.

language
  • string

(Optional) This is the 2 letter ISO 639-1 representation of a language. For example, use "en" for English; "es" for Spanish etc. If not set, use "en" for English as default.

text
  • string

The input text to process.

RequestStatistics

if showStats=true was specified in the request this field will contain information about the request payload.

Name Type Description
documentsCount
  • integer

Number of documents submitted in the request.

erroneousDocumentsCount
  • integer

Number of invalid documents. This includes empty, over-size limit or non-supported languages documents.

transactionsCount
  • integer

Number of transactions for the request.

validDocumentsCount
  • integer

Number of valid documents. This excludes empty, over-size limit or non-supported languages documents.

SentenceSentiment

Name Type Description
confidenceScores

The sentiment confidence score between 0 and 1 for the sentence for all classes.

length
  • integer

The length of the sentence by Unicode standard.

offset
  • integer

The sentence offset from the start of the document.

sentiment

The predicted Sentiment for the sentence.

text
  • string

The sentence text.

SentenceSentimentValue

The predicted Sentiment for the sentence.

Name Type Description
negative
  • string
neutral
  • string
positive
  • string

SentimentConfidenceScorePerLabel

Represents the confidence scores between 0 and 1 across all sentiment classes: positive, neutral, negative.

Name Type Description
negative
  • number
neutral
  • number
positive
  • number

SentimentResponse

Name Type Description
documents

Sentiment analysis per document.

errors

Errors by document id.

modelVersion
  • string

This field indicates which model is used for scoring.

statistics

if showStats=true was specified in the request this field will contain information about the request payload.

TextAnalyticsError

Name Type Description
code

Error code.

details

Details about specific errors that led to this reported error.

innererror

Inner error contains more specific information.

message
  • string

Error message.

target
  • string

Error target.

TextAnalyticsWarning

Name Type Description
code

Error code.

message
  • string

Warning message.

targetRef
  • string

A JSON pointer reference indicating the target object.

WarningCodeValue

Error code.

Name Type Description
DocumentTruncated
  • string
LongWordsInDocument
  • string