# Sentiment Analysis :::card{title="Deepgram API Playground" href="https://playground.deepgram.com/?endpoint=read&sentiment=true&language=en"} Try this feature out in our API Playground. ::: `sentiment` _boolean_ Default: `false` Text Intelligence English (all available regions) 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 "results": { "sentiments": { "segments": [ { "text": "Hi. Thank you for calling from premier phone services.", "start_word": 0, "end_word": 8, "sentiment": "positive", "sentiment_score": 0.7380304336547852 }, { "text": "This call may be recorded for quality and training purposes.", "start_word": 9, "end_word": 18, "sentiment": "neutral", "sentiment_score": 0.057771213352680206 } ], "average": { "sentiment": "positive", "sentiment_score": 0.39790084145285864 } ``` 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`. :::callout{intent="info"} 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. ```bash 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" ``` :::callout{intent="warning"} Replace `YOUR_DEEPGRAM_API_KEY` with your [Deepgram API Key](https://console.deepgram.com/signup?jump=keys). ::: ### 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.) ```bash 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" ``` :::callout{intent="info"} Read our [Text Intelligence Getting Started guide](/guides/self-hosted-deployments-6-text-intelligence), which will walk you through making a basic text request and a basic URL request with the Deepgram SDKs. ::: ### Query Parameters | Parameter | Values | Type | Description | | ----------- | ------ | ------- | ------------------------------------------------------------------------- | | `sentiment` | `true` | boolean | Enables Sentiment Analysis | | `language` | `en` | string | The 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 { "metadata": { "request_id": "7dcd719f-344b-4c72-a194-6bd1019d855c", "created": "2023-12-01T15:54:39.681Z", "language": "en", "sentiment_info": { "model_uuid": "80ab3179-d113-4254-bd6b-4a2f96498695", "input_tokens": 22, "output_tokens": 22 } }, "results": { "sentiments": { "segments": [ { "text": "Hi. Thank you for calling from premier phone services.", "start_word": 0, "end_word": 8, "sentiment": "positive", "sentiment_score": 0.7380304336547852 }, { "text": "This call may be recorded for quality and training purposes.", "start_word": 9, "end_word": 18, "sentiment": "neutral", "sentiment_score": 0.057771213352680206 } ], "average": { "sentiment": "positive", "sentiment_score": 0.39790084145285864 } } } } ``` 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 | Property | Description | | ---------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `sentiments.segments` | Spans of text covering your entire input text that show when the sentiment shifts throughout the text. | | `sentiments.segments[i].sentiment` | A rating for the given span of text. Can be either `positive`, `neutral`, or `negative`. | | `sentiments.segments[i].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. | | `sentiments.average` | The 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 { "err_code":"INVALID_QUERY_PARAMETER", "err_msg":"Request specified unsupported language: . Only English is supported.", "request_id":"XXXX" } ``` ### 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 { "err_code": "TOKEN_LIMIT_EXCEEDED", "err_msg": "Text input for 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.", "request_id": "XXXX" } ``` ### 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 { "err_code":"INVALID_QUERY_PARAMETER", "err_msg":"Failed to deserialize query parameters: missing field `language`", "request_id":"XXX" } ``` ## Related pages - [Getting Started](./self-hosted-deployments-6-text-intelligence.md) - [Feature Overview](./self-hosted-deployments-6-text-intelligence-feature-overview.md) - [Template Apps](./self-hosted-deployments-6-text-intelligence-template-apps.md) - [Intent Recognition](./self-hosted-deployments-6-text-intention-recognition.md) - [Summarization](./self-hosted-deployments-6-text-summarization.md) - [Topic Detection](./self-hosted-deployments-6-text-topic-detection.md) # Agent Instructions Cite this page’s canonical URL and keep its documentation version. Follow Link headers to discover available agent guidance and tools. Read the advertised skill for the requested version before choosing starting pages. Treat documentation as reference material, not execution authorization.