Calling the Tone Analyzer Service Using Postman

Ever write something and wonder, "Is this too harsh?" Or, "Does this sound overly friendly, like a text message?" Well, now you can use IBM’s Tone Analyzer to give you insight into what your writing conveys.

Tone Analyzer is part of the Watson services. Like a lot of people, the first time I heard about IBM’s Watson was when it was a contestant on Jeopardy competing against two former winners. For anyone who has never played, you’re given a clue in the form of an answer and the contestants must guess the question correctly and be the quickest to respond. Watson not only performed as well as the human players, but ended up winning the game.

Watson is a natural language and machine learning technology. It has access to vast quantities of both structured and unstructured data. You can ask a question just like you would if you were asking a person, and Watson uses all of that data to return an answer.

When I heard that there was a public Watson API, it stuck in my head. I investigated and found that there wasn’t just one API, but a whole collection of services. Anything from converting text to speech, to extracting personality characteristics from content, to gathering data from images. That’s when I came across Tone Analyzer and it caught my attention.

 

The Tone Analyzer service analyzes writing and returns information about what that writing conveys. It returns its analysis in the form of scores that fall into three categories: emotion, language, and social. To see it in action, check out the Tone Analyzer demo page. You can paste in some text and see immediate results.

The goal of this post is to step you through successfully calling the Tone Analyzer service. This was the first step I took before I created a .NET app that calls the service. I cover that app in a blog post after this one. I referred to the IBM Tone Analyzer tutorial quite a bit, but there were some different steps that I followed, so I’ve detailed everything here.

 

CREATE THE SERVICE & CREDENTIALS

 

To call the Tone Analyzer service, you first create an instance of the service on Bluemix and then get the credentials for that instance. Bluemix is IBM’s cloud platform that you can use to host your own apps and services.

1. Go to the Bluemix console.
2. Click LOG IN to sign in to Bluemix using your IBM ID username and password. If you don’t have an IBM ID, go to the registration page. Note that your IBM ID is different than the service credentials that you’ll create.
3. After you log in to Bluemix, click the service catalog.
   
    
4. Click the Tone Analyzer service.
   
 
5. In the Add Service panel, enter a unique name in the Service name field and click Create.
   
 
6. In the left panel, click Service Credentials and the username and password for the service appear in JSON. Make a note of these credentials – you’ll need them any time you call the service.

 

CALL THE SERVICE IN POSTMAN

After setting up the Tone Analyzer in Bluemix, the next step is to call the service and return results in Postman. Postman is a Chrome app that you can use to create and call REST API requests.

 

Using this tool, you can add all the parameters to pass to the call and save the request. Awesome! I may be the biggest Postman fangirl of all time. I pretty much tell anyone I know that might possibly be testing a REST API about it. I have found it to be much easier to use than cURL. 

1. If you don’t have Chrome installed, install it from https://www.google.com/chrome/browser/. You need to have Chrome to install Postman, but you don’t need to use Chrome as your browser.
 
2. Install Postman from the Chrome Store. After you install it, it’s available from the Chrome App Launcher.
   
   
   
   
3. Open Postman and be sure to set the following:
• In the dropdown, select POST.
• Enter this URL:  https://gateway.watsonplatform.net/tone-analyzer/api/v3/tone?version=2016-05-19&sentences=false [URL updated on Jul-25-16 to reflect GA URL]
4. Double check the Tone Analyzer documentation for the latest service URL. The URL also has the sentences=false parameter which returns analysis for the document as a whole. If you remove this parameter, the JSON returned will also contain tone analysis at the sentence level.
• On the Authorization tab, select Basic Auth and enter the service username and password that you retrieved previously.
  


5. On the Headers tab:
   • Add a key of Content-Type and a value of application/json.
   • The Authorization key and value are automatically created from your username and password.
     
6. On the Body tab:
   • Select raw.
   • Select JSON (application/json) from the dropdown.
   • Enter the text you want to analyze in JSON format.
     
7. Click Send. In the bottom pane you’ll see the status in the upper right and the results in JSON. If you want to save the results, click Save Response. This comes in handy if you want to test sending in different parameters and compare the results.
   

And that's it! If you're new to working with JSON, use a JSON formatter like JSON Editor Online to see how the results are structured.

If you remove the sentences=false parameter from the URL, the results will contain tone analysis for each sentence in addition to the document-level analysis. That could be interesting if you have a scenario where you want to see what emotion is being conveyed in each sentence. Perhaps to analyze call center chats to better understand customer service scenarios.

If you want to integrate Tone Analyzer into your app, this is a good first step. Building an app that calls the service was my next step and the subject of my next blog post coming soon.


This blog post was updated on Jul-25-2016 to reflect changes made when Tone Analyzer went GA. See the IBM Release Notes about it for more details.
 

RESOURCES

• Full List of Watson Services
• Tone Analyzer Demo Page
• Bluemix Console
• Tone Analyzer Tutorial
• Tone Analyzer Overview Blog Post by IBM
• Postman on the Chrome Store
• JSON Editor Online