Getting started with Natural Language Understanding

Before you begin

• Create an instance of the service:
  1. Go to the Natural Language Understanding page in the IBM Cloud catalog.
  2. Sign up for a free IBM Cloud account or log in.
  3. Click Create.
• Copy the credentials to authenticate to your service instance:
  1. On the Manage page, click Show Credentials.
  2. Copy the API Key and URL values.
• Make sure that you have the curl command.

  • Test whether curl is installed. Run the following command on the command line. If the output lists the curl version with SSL support, you are set for the tutorial.

    curl -V
    

  • If necessary, install a version with SSL enabled from curl.haxx.se. Add the location of the file to your PATH environment variables if you want to run curl from any command-line location.

This tutorial shows you how to use the Natural Language Understanding API from a command-line interface. To download client libraries for various programming languages, check out the Watson SDKs.

Step 1: Analyze a webpage

Run the following command to analyze a webpage to get sentiment, concepts, categories, entities, and keywords. Replace {apikey} and {url} with your service credentials.

curl -X POST -u "apikey:{apikey}" \
--header "Content-Type: application/json" \
--data '{
  "url": "http://newsroom.ibm.com/Guerbet-and-IBM-Watson-Health-Announce-Strategic-Partnership-for-Artificial-Intelligence-in-Medical-Imaging-Liver",
  "features": {
    "sentiment": {},
    "categories": {},
    "concepts": {},
    "entities": {},
    "keywords": {}
  }
}' \
"{url}/v1/analyze?version=2019-07-12"

Windows users: This command might not run on Windows. Run the following command instead:

curl -X POST -u "apikey:{apikey}" --header "Content-Type: application/json" --data "{\"url\":\"http://newsroom.ibm.com/Guerbet-and-IBM-Watson-Health-Announce-Strategic-Partnership-for-Artificial-Intelligence-in-Medical-Imaging-Liver\",\"features\":{\"sentiment\":{},\"categories\":{},\"concepts\":{},\"entities\":{},\"keywords\":{}}}" "{url}/v1/analyze?version=2019-07-12"

The next step demonstrates how to specify options that customize the analysis for each feature.

Step 2: Analyze target phrases and keywords

Natural Language Understanding can analyze target phrases in context of the surrounding text for focused sentiment and emotion results. The targets option for sentiment in the following example tells the service to search for the targets "apples", "oranges", and "broccoli". Since "apples" and "oranges" are located in the text, sentiment scores are returned for those targets.

You can also get sentiment and emotion results for entities and keywords that are detected in your text. In the example, the emotion option for keywords tells the service to analyze each detected keyword for emotion results.

curl -X POST -u "apikey:{apikey}" \
--header "Content-Type: application/json" \
--data '{
  "text": "I love apples! I do not like oranges.",
  "features": {
    "sentiment": {
      "targets": [
        "apples",
        "oranges",
        "broccoli"
      ]
    },
    "keywords": {
      "emotion": true
    }
  }
}' \
"{url}/v1/analyze?version=2019-07-12"

Runnable command for Windows users:

curl -X POST -u "apikey:{apikey}" --header "Content-Type: application/json" --data "{\"text\":\"I love apples! I do not like oranges.\",\"features\":{\"sentiment\":{\"targets\":[\"apples\",\"oranges\",\"broccoli\"]},\"keywords\":{\"emotion\":true}}}" "{url}/v1/analyze?version=2019-07-12"

Next steps

• View the API reference.
• Learn how to identify custom entities and relations.