Sentiment Analysis

Sentiment Analysis recognizes sentiment throughout the inputed text.

sentiment boolean   Default: false

English (all available regions)

Deepgram API Playground Try this feature out in our API Playground!

Sentiment Analysis accepts an input text, divides it into a list of segments comprised of sections of the text, and identifies the sentiment of each segment. It also assigns an average sentiment to the entire text.

JSON
1"results": {
2    "sentiments": {
3      "segments": [
4        {
5          "text": "Hi. Thank you for calling from premier phone services.",
6          "start_word": 0,
7          "end_word": 8,
8          "sentiment": "positive",
9          "sentiment_score": 0.7380304336547852
10        },
11        {
12          "text": "This call may be recorded for quality and training purposes.",
13          "start_word": 9,
14          "end_word": 18,
15          "sentiment": "neutral",
16          "sentiment_score": 0.057771213352680206
17        }
18      ],
19      "average": {
20        "sentiment": "positive",
21        "sentiment_score": 0.39790084145285864
22      }

A sentiment of positive, negative, or neutral along with a sentiment_score is identified for each segment of the source text, and an average of the entire text’s sentiment is also provided along with the average sentiment_score.

The break point for a sentiment_score becoming positive or negative is +-0.333333333....

Enable Feature

To enable Sentiment, use the following parameter in the query string when you call Deepgram’s /read endpoint:

sentiment=true

Basic Text Request

To analyze text from a file on your computer, run the following curl command in a terminal or your favorite API client.

cURL
$curl -vX POST \
> -H "Authorization: Token YOUR_DEEPGRAM_API_KEY" \
> -H "Content-Type: application/json" \
> -d '{"text": "YOUR_TEXT_INPUT"}' \
> "https://api.deepgram.com/v1/read?sentiment=true&language=en"

Replace YOUR_DEEPGRAM_API_KEY with your Deepgram API Key.

Basic URL Request

To analyze text from a hosted file, run the following curl command in a terminal or your favorite API client. (Try testing it out with the hosted file https://static.deepgram.com/examples/aura.txt.)

cURL
$curl -vX POST \
> -H "Authorization: Token YOUR_DEEPGRAM_API_KEY" \
> -H "Content-Type: application/json" \
> -d '{"url": "https://YOUR_FILE_URL.txt"}' \
> "https://api.deepgram.com/v1/read?sentiment=true&language=en"

Read our Text Intelligence Getting Started guide, which will walk you through making a basic text request and a basic URL request with the Deepgram SDKs.

Query Parameters

ParameterValuesTypeDescription
sentimenttruebooleanEnables Sentiment Analysis
languageenstringThe language of your input text (Only English is supported at this time.)

Analyze Response

When the file is finished processing, you’ll receive a JSON response that has the following basic structure:

JSON
1{
2  "metadata": {
3    "request_id": "7dcd719f-344b-4c72-a194-6bd1019d855c",
4    "created": "2023-12-01T15:54:39.681Z",
5    "language": "en",
6    "sentiment_info": {
7      "model_uuid": "80ab3179-d113-4254-bd6b-4a2f96498695",
8      "input_tokens": 22,
9      "output_tokens": 22
10    }
11  },
12  "results": {
13    "sentiments": {
14      "segments": [
15        {
16          "text": "Hi. Thank you for calling from premier phone services.",
17          "start_word": 0,
18          "end_word": 8,
19          "sentiment": "positive",
20          "sentiment_score": 0.7380304336547852
21        },
22        {
23          "text": "This call may be recorded for quality and training purposes.",
24          "start_word": 9,
25          "end_word": 18,
26          "sentiment": "neutral",
27          "sentiment_score": 0.057771213352680206
28        }
29      ],
30      "average": {
31        "sentiment": "positive",
32        "sentiment_score": 0.39790084145285864
33      }
34    }
35  }
36}

Use the API reference or the API Playground to view the detailed response.

The sentiment values added to objects are:

  • sentiment: The sentiment of the associated text (positive | negative | neutral).
  • sentiment_score: A floating point value between -1 and 1 representing the sentiment of the associated span of text, with -1 being the most negative sentiment, and 1 being the most positive sentiment.

Response Properties

PropertyDescription
sentiments.segmentsSpans of text covering your entire input text that show when the sentiment shifts throughout the text.
sentiments.segments[i].sentimentA rating for the given span of text. Can be either positive, neutral, or negative.
sentiments.segments[i].sentiment_scoreA floating point value between -1 and 1 representing the sentiment of the associated span of text, with -1 being the most negative sentiment, and 1 being the most positive sentiment.
sentiments.averageThe average sentiment for the entire text.

API Error Responses

Unsupported Language

Status 400

If you request Sentiment Analysis with an unsupported language by specifying a language code such as sentiment=true&language=es or sentiment=true&detect_language=true where the detected language is unsupported, you will get the error message below.

JSON
1{
2  "err_code":"INVALID_QUERY_PARAMETER",
3  "err_msg":"Request specified unsupported language: <language_name>. Only English is supported.",
4  "request_id":"XXXX"
5}

Token Limit Exceeded

Status 400

If the request’s input length exceeded the 150k token rate limit per request, you will get the error message below.

JSON
1{
2  "err_code": "TOKEN_LIMIT_EXCEEDED",
3  "err_msg": "Text input for <api_name> currently supports up to 150K tokens. Please revise your text input to fit within the defined token limit. For more information, please visit our API documentation.",
4  "request_id": "XXXX"
5}

Missing Query Parameter

Status 400

If the request sent contained only the feature parameter (sentiment) but not the language parameter, you will receive this error.

JSON
1{
2  "err_code":"INVALID_QUERY_PARAMETER",
3  "err_msg":"Failed to deserialize query parameters: missing field `language`",
4  "request_id":"XXX"
5}
Built with