Curl Node Java Python

Tone Analyzer

API Reference

Introduction

The Tone Analyzer service uses linguistic analysis to detect emotional tones, social propensities, and writing styles in written communication.

API Endpoint

https://gateway.watsonplatform.net/tone-analyzer/api/v3

Node

npm install watson-developer-cloud

Maven

<dependency>
  <groupId>com.ibm.watson.developer_cloud</groupId>
  <artifactId>java-sdk</artifactId>
  <version>3.0.1</version>
</dependency>

Gradle


    compile 'com.ibm.watson.developer_cloud:java-sdk:3.0.1'
    

Python

pip install --upgrade watson-developer-cloud

API explorer

To interact with this API, use the Tone Analyzer Service API explorer. Use the explorer to test your calls to the API, and to view live responses from the server.

Authentication

You authenticate to the Tone Analyzer API by providing the username and password that are provided in the service credentials for the service instance that you want to use. The API uses Basic Authentication.

After creating an instance of the Tone Analyzer service, select Service Credentials from the left navigation for its dashboard to see the username and password that are associated with that instance.

Replace {username} and {password} with your credentials


curl -u "{username}":"{password}"

var watson = require('watson-developer-cloud');

var tone_analyzer = watson.tone_analyzer({
  username: '{username}',
  password: '{password}',
  version: 'v3',
  version_date: '2016-05-19'
});

ToneAnalyzer service = new ToneAnalyzer(ToneAnalyzer.VERSION_DATE_2016_05_19);
service.setUsernameAndPassword("{username}", "{password}");

import json
from watson_developer_cloud import ToneAnalyzerV3


tone_analyzer = ToneAnalyzerV3(
   username='YOUR SERVICE USERNAME',
   password='YOUR SERVICE PASSWORD',
   version='2016-05-19')

Methods

Analyze tone

Analyzes the tone of a piece of text. The message is analyzed for several tones - social, emotional, and language. For each tone, various traits are derived. For example, conscientiousness, agreeableness, and openness.

Use GET /v3/tone for smaller request data sizes and for URL query parameters, and use POST /v3/tone for larger request data sizes and for JSON requests.


GET /v3/tone
POST /v3/tone 

Request

Parameter Type Description
text query (Required for GET) Text that contains the content to be analyzed. The Tone Analyzer Service supports up to 128KB of text, or about 1000 sentences. Sentences with less than three words cannot be analyzed.
body body (Required for POST) JSON or plain text that contains the content to be analyzed.
Content-Type header (Required for POST) The type of file being analyzed. Valid values are text/plain, text/html, or application/json.
version query (Required) When we make breaking changes to the API, we release a new, dated version. The value for the version parameter is the date for the version of the API that you want to call. The current version is 2016-05-19, and the documentation reflects the current version. Check out the Release notes for the changelog of available versions.
tones query Filter the results by a specific tone. Valid values for tones are emotion, language, and social.
sentences query Filter your response to remove the sentence level analysis. Valid values for sentences are true and false. This parameter defaults to true when it's not set, which means that a sentence level analysis is automatically provided. Change sentences=false to filter out the sentence level analysis.

Example request GET

curl -u "{username}":"{password}" "https://gateway.watsonplatform.net/tone-analyzer/api/v3/tone?version=2016-05-19&text=A%20word%20is%20dead%20when%20it%20is%20said,%20some%20say.%20Emily%20Dickinson"

Example request POST

curl -u "{username}":"{password}" -H "Content-Type: application/json" -d "{\"text\": \"A word is dead when it is said, some say. Emily Dickinson\"}" "https://gateway.watsonplatform.net/tone-analyzer/api/v3/tone?version=2016-05-19"

Example request


var watson = require('watson-developer-cloud');

var tone_analyzer = watson.tone_analyzer({
  username: '{username}',
  password: '{password}',
  version: 'v3',
  version_date: '2016-05-19 '
});

tone_analyzer.tone({ text: 'A word is dead when it is said, some say. Emily Dickinson' },
  function(err, tone) {
    if (err)
      console.log(err);
    else
      console.log(JSON.stringify(tone, null, 2));
});

Example request


ToneAnalyzer service = new ToneAnalyzer(ToneAnalyzer.VERSION_DATE_2016_05_19);
service.setUsernameAndPassword("", "");

String text =
  "I know the times are difficult! Our sales have been "
      + "disappointing for the past three quarters for our data analytics "
      + "product suite. We have a competitive data analytics product "
      + "suite in the industry. But we need to do our job selling it! "
      + "We need to acknowledge and fix our sales challenges. "
      + "We can’t blame the economy for our lack of execution! "
      + "We are missing critical sales opportunities. "
      + "Our product is in no way inferior to the competitor products. "
      + "Our clients are hungry for analytical tools to improve their "
      + "business outcomes. Economy has nothing to do with it.";

// Call the service and get the tone
ToneAnalysis tone = service.getTone(text, null).execute();
System.out.println(tone);

Example request


import json
from watson_developer_cloud import ToneAnalyzerV3


tone_analyzer = ToneAnalyzerV3(
   username='YOUR SERVICE USERNAME',
   password='YOUR SERVICE PASSWORD',
   version='2016-05-19 ')

print(json.dumps(tone_analyzer.tone(text='A word is dead when it is said, some say. Emily Dickinson'), indent=2))

Response

Name Description
document_tone The tone analysis of the full document.
tone_categories The tone analysis categories. Possible tone categories are emotion, language, and social.
tones Analysis organized by tones. The emotion tones are anger, disgust, fear, joy, and sadness. The language tones are analytical, confident, and tentative. The social tones are openness, conscientiousness, extraversion, agreeableness, and emotional_range.
score The score of the tone.
tone_id Unique ID of the tone.
category_id The unique ID of the category.
category_name The tone analysis categories. Possible tone categories are emotion, language, and social.
sentences_tone The sentence level tone analysis.
sentence_id Unique ID for each sentence.
text Text of the sentence being analyzed.
input_from The character number of the first character in the sentence.
input_to The character number of the last character in the sentence.

Example response


{
  "document_tone": {
    "tone_categories": [
      {
        "tones": [
          {
            "score": 0.25482,
            "tone_id": "anger",
            "tone_name": "Anger"
          },
          {
            "score": 0.345816,
            "tone_id": "disgust",
            "tone_name": "Disgust"
          },
          {
            "score": 0.121116,
            "tone_id": "fear",
            "tone_name": "Fear"
          },
          {
            "score": 0.078903,
            "tone_id": "joy",
            "tone_name": "Joy"
          },
          {
            "score": 0.199345,
            "tone_id": "sadness",
            "tone_name": "Sadness"
          }
        ],
        "category_id": "emotion_tone",
        "category_name": "Emotion Tone"
      },
      {
        "tones": [
          {
            "score": 0.999,
            "tone_id": "analytical",
            "tone_name": "Analytical"
          },
          {
            "score": 0.999,
            "tone_id": "confident",
            "tone_name": "Confident"
          },
          {
            "score": 0.694,
            "tone_id": "tentative",
            "tone_name": "Tentative"
          }
        ],
        "category_id": "language_tone",
        "category_name": "Language Tone"
      },
      {
        "tones": [
          {
            "score": 0.271,
            "tone_id": "openness_big5",
            "tone_name": "Openness"
          },
          {
            "score": 0.11,
            "tone_id": "conscientiousness_big5",
            "tone_name": "Conscientiousness"
          },
          {
            "score": 0.844,
            "tone_id": "extraversion_big5",
            "tone_name": "Extraversion"
          },
          {
            "score": 0.257,
            "tone_id": "agreeableness_big5",
            "tone_name": "Agreeableness"
          },
          {
            "score": 0.497,
            "tone_id": "emotional_range_big5",
            "tone_name": "Emotional Range"
          }
        ],
        "category_id": "social_tone",
        "category_name": "Social Tone"
      }
    ]
  }
}

Data collection

By default, Bluemix collects data from all requests and uses the data to improve the services. If you do not want to share your data, set a header parameter X-Watson-Learning-Opt-Out with the value 1 for all requests. If you do not specify this header in all payload data, data is collected and used to improve the service.

Response handling

The Tone Analyzer service uses standard HTTP response codes to display whether a method completed successfully. A 200 response always indicates success. A 400 type response is some sort of failure, and a 500 type response usually indicates an internal system error.

Error information

200 - OK Success.
201 - OK Created.
400 - Bad Request Missing a required parameter or invalid parameter value.
401 - Unauthorized No API key provided or the API key provided was not valid.
404 - Not Found The requested item or parameter doesn't exist.
429 - Throttle limit Your organization ID made more than 1200 requests per minute, so your calls have been throttled.
500 - Server Errors Internal server error.

Error format

Name Description
error Error description.
code HTTP Status code.
help (Optional) Help message.

Catching an error

Example error


{
  "code" : 400,
  "error" : "The request does not contain a Content-Type"
}