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 |
|
Supported Cognitive Services endpoints (protocol and hostname, for example: https://westus.api.cognitive.microsoft.com). |
|
model-version
|
query |
|
(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. |
|
|
show
|
query |
|
(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 |
|
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
|
Document |
|
|
Document |
|
|
Document |
Predicted sentiment for document (Negative, Neutral, Positive, or Mixed). |
|
Document |
if showStats=true was specified in the request this field will contain information about the document payload. |
|
Error |
Error code. |
|
Error |
|
|
Inner |
|
|
Inner |
Error code. |
|
Multi |
Contains a set of input documents to be analyzed by the service. |
|
Multi |
Contains an input document to be analyzed by the service. |
|
Request |
if showStats=true was specified in the request this field will contain information about the request payload. |
|
Sentence |
|
|
Sentence |
The predicted Sentiment for the sentence. |
|
Sentiment |
Represents the confidence scores between 0 and 1 across all sentiment classes: positive, neutral, negative. |
|
Sentiment |
|
|
Text |
|
|
Text |
|
|
Warning |
Error code. |
DocumentError
| Name | Type | Description |
|---|---|---|
| error |
Document Error. |
|
| id |
|
Document Id. |
DocumentSentiment
| Name | Type | Description |
|---|---|---|
| confidenceScores |
Document level sentiment confidence scores between 0 and 1 for each sentiment class. |
|
| id |
|
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 |
|
|
| negative |
|
|
| neutral |
|
|
| positive |
|
DocumentStatistics
if showStats=true was specified in the request this field will contain information about the document payload.
| Name | Type | Description |
|---|---|---|
| charactersCount |
|
Number of text elements recognized in the document. |
| transactionsCount |
|
Number of transactions for the document. |
ErrorCodeValue
Error code.
| Name | Type | Description |
|---|---|---|
| internalServerError |
|
|
| invalidArgument |
|
|
| invalidRequest |
|
|
| serviceUnavailable |
|
ErrorResponse
| Name | Type | Description |
|---|---|---|
| error |
Document Error. |
InnerError
| Name | Type | Description |
|---|---|---|
| code |
Error code. |
|
| details |
|
Error details. |
| innererror |
Inner error contains more specific information. |
|
| message |
|
Error message. |
| target |
|
Error target. |
InnerErrorCodeValue
Error code.
| Name | Type | Description |
|---|---|---|
| emptyRequest |
|
|
| invalidCountryHint |
|
|
| invalidDocument |
|
|
| invalidDocumentBatch |
|
|
| invalidParameterValue |
|
|
| invalidRequestBodyFormat |
|
|
| missingInputRecords |
|
|
| modelVersionIncorrect |
|
|
| unsupportedLanguageCode |
|
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 |
|
A unique, non-empty document identifier. |
| language |
|
(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 |
|
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 |
|
Number of documents submitted in the request. |
| erroneousDocumentsCount |
|
Number of invalid documents. This includes empty, over-size limit or non-supported languages documents. |
| transactionsCount |
|
Number of transactions for the request. |
| validDocumentsCount |
|
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 |
|
The length of the sentence by Unicode standard. |
| offset |
|
The sentence offset from the start of the document. |
| sentiment |
The predicted Sentiment for the sentence. |
|
| text |
|
The sentence text. |
SentenceSentimentValue
The predicted Sentiment for the sentence.
| Name | Type | Description |
|---|---|---|
| negative |
|
|
| neutral |
|
|
| positive |
|
SentimentConfidenceScorePerLabel
Represents the confidence scores between 0 and 1 across all sentiment classes: positive, neutral, negative.
| Name | Type | Description |
|---|---|---|
| negative |
|
|
| neutral |
|
|
| positive |
|
SentimentResponse
| Name | Type | Description |
|---|---|---|
| documents |
Sentiment analysis per document. |
|
| errors |
Errors by document id. |
|
| modelVersion |
|
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 |
|
Error message. |
| target |
|
Error target. |
TextAnalyticsWarning
| Name | Type | Description |
|---|---|---|
| code |
Error code. |
|
| message |
|
Warning message. |
| targetRef |
|
A JSON pointer reference indicating the target object. |
WarningCodeValue
Error code.
| Name | Type | Description |
|---|---|---|
| DocumentTruncated |
|
|
| LongWordsInDocument |
|