Getting started with the Question and Answer service

The IBM Watson™ Question and Answer service provides an Application Programming Interface (API) that enables you to add the power of the IBM Watson cognitive computing system to your application. Applications that use the Question and Answer service use a corpus of information that provides domain knowledge based on a specific set of input documents and other information. Two default corpora are provided for use with the Question and Answer service:

See the next section for a discussion of the content of these corpora, the sources of information from which they were created, and some classes of sample questions that you can use when testing these corpora. To see a quick demo of the Question and Answer service in action, click here.

To download an article and sample code that shows how to integrate the Question and Answer service with another Watson product, Watson Explorer, see GitHub.

We want to hear from you! Please provide comments or ask questions about Question and Answer in the Watson dev forum.

We are always looking to improve and learn from your experience with our services. You can help Watson learn by providing personalized feedback. The Question and Answer service includes a feedback API that can be used to submit comments, observations, and suggestions that Watson and its developers can use to educate and improve this service. The Question and Answer API, including its feedback API, is documented here. For an example of submitting feedback through this API in a Node.js application, see this section.

Note: This is a beta release of the Question and Answer service. The beta version of this API might not be supported after a new beta is released or after the service exits beta. The service is not recommended for production use. Visit the forum mentioned above to provide feedback on how we can improve the API.

Corpora for the Question and Answer API

Each corpus that is designed for use with the Question and Answer API provides domain knowledge based on a specific set of input documents and other information. The next two sections provide information about each of the corpora that are provided for use with the Question and Answer API, including the sources of the information that they contain and classes of sample questions that you can use to test the Question and Answer API and the corpora themselves.

The corpora used by the Question and Answer service benefit from continued use and training. These corpora continue to learn and provide better responses as they are used and as their users provide feedback on the accuracy of the answers that they provide.

The beta deployment of the Question and Answer service is intended to show examples of how it might be deployed. Extensive training to produce highly accurate or precise answers has not been applied. Over time, the ongoing use and training of the service can improve results by providing higher quality results and reducing bad or errant output.

Watson for Healthcare

The Watson for Healthcare corpus contains content from the following sources:

  • Healthfinder.gov

  • CDC Health Topics

  • National Heart, Lung, and Blood Institute (NHLBI)

  • National Institute of Arthritis and Musculoskeletal and Skin Diseases (NIAMS)

  • National Institute of Diabetes and Digestive and Kidney Diseases (NIDDK)

  • National Institute of Neurological Disorders and Stroke (NINDS)

  • Cancer.gov (physician data query)

Some types of questions that you may want to use to see the power of the Question and Answer service with its Watson for Healthcare corpus are:

  • Condition Questions

    • "What is X?", where X is a general medical condition such as a stroke or a specific condition such as Machado-Joseph Disease.

    • "What causes X?", where X is a general condition such as heart disease or a specific condition such as Wilson Disease. Sample phrasing of such questions includes What causes X, What's the cause of X, and so on.

    • "What is the treatment for X?", where X is a condition such as Aplastic Anemia or Autoimmune Hepatitis. Sample phrasing of such questions includes How is X treated, What's the treatment for X, and so on.

    • "What are the symptoms of X?", where X is a condition such as Cirrhosis or Multiple Sclerosis. Sample phrasing of such questions includes What are the signs of X, What are the symptoms of X, and so on.

    • "Am I at risk of X?", where X is a condition such as listerosis or insomnia. Sample phrasing of such questions includes How can I reduce my risk for X, Who is at risk for X, and so on.

  • Procedure Questions

    • "What should I expect before X?", where X is a procedure such as heart surgery or a blood transfusion. Sample phrasing of such questions includes What should I expect before X, What can I expect going into X, and so on.

    • "What should I expect after X?", where X is a procedure such as a cardiac catheterization or a coronary angioplasty. Sample phrasing of such questions includes What should I expect after X, What is my recovery outlook after X, and so on.

  • General Health Questions

    • Basic questions, such as What are the benefits of taking aspirin daily?, Why do I need to get shots?, and How do I know if I have food poisoning?.

  • Action-Related Questions

    • Questions that request information about the action to take in order to achieve a given result, such as How can I quit smoking?, What should I do if my child is obese?, and What can I do to get more calcium?.

Watson for Travel

The Watson for Travel corpus contains content from the following sources:

  • Wikivoyage

  • CDC Travel

  • TSA.gov

Some types of questions that you may want to use to see the power of the Question and Answer service with its Watson for Travel corpus are:

  • Tourism Questions

    • "Where is the best place to stay in X?" or "What are some recommended hotels in X?"

    • "What should I do in X?" or "What is there to do in X?"

    • "Where should I eat in X?" or "Where can I get food in X?"

    • "Is it safe to travel to X?" or "Is it safe to go to X?"

  • Logistical Questions: questions that request information about how to achieve a result:

    • "How do I get downtown from X?"

    • "What airport should I use to get to X?"

    • "Is there a ferry from X to Y?"

  • Travel Health Questions: questions that focus on travel-related health concerns:

    • "What is X?", "Am I at risk for X?", or "How do I prevent X?"

  • Air Travel Questions: general questions about air travel:

    • "What is the X rule?", "What are the rules for X and airport screening?", or "Can I bring my X through airport security?"

Learn more

Connecting to Bluemix

Bluemix is the IBM Platform as a Service (PaaS) environment that hosts the Watson Developer Cloud; for more information about Bluemix, see the Bluemix documentation. To develop applications on your local machine and push them to Bluemix, you need to install command-line or graphical tools that enable you to interact with Bluemix, as explained in Getting started with Bluemix.

Once you have installed the tools that you want to use, the first step in developing an application in Bluemix that uses the Question and Answer service is to connect to the API and log in to Bluemix. At this time, you can also create an instance of the Question and Answer service that you can bind to your application, as described in Creating an instance of a service. You can connect an instance of any Watson service to an application only after that application exists in Bluemix.

The following sections explain how to create a sample Question and Answer application and run it in Bluemix. The steps describe how to use an instance of the Question and Answer service from a variety of runtimes, such as a servlet in a Java web server, a Node.js application, or a Ruby on Rails or Sinatra application.

A sample Question and Answer application in Bluemix

This section explains how to create and run a complete sample application that uses the Question and Answer service in Bluemix. You can access an instance of the service from a variety of runtimes, such as WebSphere Liberty for Java, Node.js, and Ruby on Rails or Sinatra. The following sections describe how to obtain and use the sample application in the Java (with WebSphere Liberty), Node.js, and Ruby (with Sinatra) languages.

Deploying and running the application in Bluemix describes the language-independent steps needed to use the application in Bluemix. Building and running the application locally provides additional information about running the application from your local machine.

The sample application lets you enter questions against a selected corpus. You choose the corpus you want to query, Healthcare or Travel, enter a question, and click the Ask button. The application returns responses with their confidence levels. The sample application looks and works identically for all supported programming languages.

The sample application in Java

This section explains how to create a sample Java application that uses an instance of the Question and Answer service in Bluemix. The application runs as a Java servlet in the WebSphere Liberty profile.

Note: You need to use the Apache ant compiler to build the Java application. For information about the ant compiler and to download a copy for your operating system, visit ant.apache.org.

Complete the following steps to prepare the Java application for the Bluemix environment:

  1. Download the .zip file that contains the source files for the Java sample: qa-java-sample.zip. Unzip the file on your local machine, and change directories to qa-java-sample/qa-java.git. This is the working directory for the sample application.

    The Java source file for the servlet, DemoServlet.java, resides in a subdirectory of the src directory that is located in the working directory. Examine the code and its comments to better understand the application. The following example shows the DemoServlet.java file:

    
      
  2. Edit the manifest.yml file to change the name attribute for your application to something unique; for example, change qa-java to something like qa-java-username. The name you choose must be unique among all Bluemix applications. Note that the name of the service instance shown in the file is qa-service. You will use the names of both the application and the service instance in later steps.

    The following example shows the manifest.yml file that you need to modify:

    
      
  3. Use the Apache ant compiler to build the application and create its webApp.war file via the following commands. The first command cleans up any remnants of a previous build, and the second performs a new build of the application. Both rely on the build.xml file included in the .zip file.

    ant clean
    ant build

Continue with the steps described in Deploying and running the application in Bluemix to run the sample in Bluemix.

The sample application in Node.js

This section explains how to create a sample Node.js application that uses an instance of the Question and Answer service in Bluemix. The sample uses Express as a web application framework and Jade as a template engine.

Complete the following steps to prepare the Node.js application for the Bluemix environment:

  1. Download the .zip file that contains the source files for the Node.js sample: qa-nodejs-sample.zip. Unzip the file on your local machine, and change directories to qa-nodejs-sample/qa-nodejs.git. This is the working directory for the sample application.

    The Javascript source file for the application, app.js, resides in the working directory of the application. Examine the code and its comments to better understand the application. The following example shows the app.js file:

    
      
  2. Edit the manifest.yml file to change the name attribute for your application to something unique; for example, change qa-nodejs to something like qa-nodejs-username. The name you choose must be unique among all Bluemix applications. Note that the name of the service instance shown in the file is qa-service. You will use the names of both the application and the service instance in later steps.

    The following example shows the manifest.yml file that you need to modify:

    
    
      

For this example, you do not need to use Node Packaged Modules (npm). The sample code is built when you deploy your application by pushing it to Bluemix with the cf push command later in the instructions. The npm command is needed only if you plan to build the application locally.

Continue with the steps described in Deploying and running the application in Bluemix to run the sample in Bluemix.

The sample application in Ruby

This section explains how to create a sample Ruby application that uses an instance of the Question and Answer service in Bluemix. The application runs in the Ruby Sinatra framework.

Complete the following steps to prepare the Ruby application for the Bluemix environment:

  1. Download the .zip file that contains the source files for the Ruby sample: qa-ruby-master.zip. Unzip the file on your local machine, and change directories to qa-ruby-master/qa-ruby-master. This is the working directory for the sample application.

    The Ruby source file for the application, app.rb, resides in the working directory of the application. Examine the code and its comments to better understand the application. The following example shows the app.rb file:

    
      
  2. Edit the manifest.yml file to change the name attribute for your application to something unique; for example, change qa-ruby to something like qa-ruby-username. The name you choose must be unique among all Bluemix applications. Note that the name of the service instance shown in the file is qa-service. You will use the names of both the application and the service instance in later steps.

    The following example shows the manifest.yml file that you need to modify:

    
      

For this example, you do not need to compile the application. The sample code is built when you deploy your application by pushing it to Bluemix with the cf push command later in the instructions. You need to compile only if you plan to build the application locally.

Continue with the steps described in Deploying and running the application in Bluemix to run the sample in Bluemix.

Deploying and running the application in Bluemix

After preparing the sample application in one of the languages as described in the previous sections, follow the instructions in this section to deploy and run the application in Bluemix. The following steps use the Cloud Foundry cf command to work with Bluemix. Visit the Downloads section of Cloud Foundry's public GitHub repository to obtain a platform-specific installer or an archive file that contains platform-specific binaries for the latest version of this tool; refer to the documentation for the cf command for more information about the tool. The following steps are common to all languages.

  1. Use the cf api command to connect to Bluemix and specify the location of the Watson Services APIs:

    cf api https://api.ng.bluemix.net
  2. Use the cf login command to log in to Bluemix. You can use the appropriate options to specify your username, password, organization, and space; the command prompts for any required information that you do not specify on the command line. Note that you can also use the cf target command to specify the organization and space after logging in.

    cf login -u username
  3. Use the cf marketplace command to learn the name of the Question and Answer service you wish to use with your application and the plans under which the service is available. You use these values in the next step. Note that for this example, you should use the service named question_and_answer and the plan named question_and_answer_free_plan in the next step.

    cf marketplace
  4. Use the cf create-service command to create an instance of the service for use with your application. The first and second arguments are the service name and the plan you obtained in the previous step; the third argument is the name of the service instance specified in the manifest.yml file, in this case, qa-service.

    cf create-service service-name plan qa-service
  5. Use the cf push command to push the application to Bluemix. The command also binds the instance of the service you are using to your application. The sole argument to the command is the name of the application specified in the manifest.yml file.

    Note: For Java, you need to append the -p option followed by the name of the .war file for the application, webApp.war, to the command line.

    cf push application-name

    The cf push command obtains the files to be pushed from your local directory. The -p option lets you specify the pathname of the compiled application, for example, the .war file for a Java application or the .zip file for a Node.js or Ruby application.

  6. Enter the URL specified in the output of the cf push command in a browser to access your application.

Building and running the application locally

After you have deployed and run the sample application in Bluemix according to the steps in the previous section, you may elect to work with the application locally. Working locally can expedite the iterative development process, allowing you to write, deploy, and test changes to your code quickly before migrating them back to the Bluemix environment. This section provides information about building and running the application on your local machine.

To run the application locally, you need to modify the source files for the application to use values from the VCAP_SERVICES JSON environment variable available from Bluemix. You need the values of the url, username, and password fields from the environment variable. See Environment variables in Bluemix for more information.

Once you know these three values, edit the source files for the different languages as follows:

  • For Java, edit the DemoServlet.java source file to change the values of the following String variables in the DemoServlet class of the application:

    private String baseURL = "<service url>";
    private String username = "<service username>";
    private String password = "<service password>";
  • For Node.js, edit the app.js source file to change the values of the following variables:

    var service_url = '<service_url>';
    var service_username = '<service_username>';
    var service_password = '<service_password>';
  • For Ruby, edit the app.rb source file to change the values of the following variables:

    service_url = '<service_url>'
    service_username = '<service_username>'
    service_password = '<service_password>'

In each case, replace the placeholder values and angle brackets with the values of the url, username, and password fields from the VCAP_SERVICES environment variable. Be sure to remove the angle brackets as part of the substitution. Note that the code automatically uses the correct values for these fields from the environment variable when you run the sample application in Bluemix.

After making these changes, use the ant compiler for Java or Ruby with the build.xml file included with the samples, or use the npm command for Node.js, to build and run the sample application locally. To deploy and run the Java version of the application locally, you will also need to install and configure the WebSphere Liberty Profile, which is the runtime environment for the application. After building your application, you need to add it as a server to your local WebSphere Liberty runtime and start the server. For information about WebSphere Liberty Profile and to download a copy for your operating system, visit https://developer.ibm.com/wasdev/downloads/.

You can access the application from the URL found in the VCAP_SERVICES environment variable.

Using the Question and Answer service in Java

The Question and Answer service offers an API that uses the HTTP POST method to request answers to a question submitted against a specified corpus. The code leverages external libraries to help with JSON parsing and the HTTP request. To parse the JSON content of the VCAP_SERVICES environment variable, the code imports two classes from an IBM-specific library for JSON, which is included in both the sample code and the WebSphere Liberty profile:

import com.ibm.json.java.JSONArray;
import com.ibm.json.java.JSONObject;

For HTTP communications by the servlet, the application code imports the following classes from the Apache HttpClient and HttpCore libraries, which are included with the sample code:

import org.apache.http.client.fluent.Executor;
import org.apache.http.client.fluent.Request;
import org.apache.http.entity.ContentType;

The doPost method of the DemoServlet class includes the code that prepares for and calls the Question and Answer API. The following snippet of code gets the text of the question and the dataset (corpus) against which the question is to be submitted. It creates a JSON object named questionJson to which it adds the text of the question. It also prepares a second JSON object named evidenceRequest to specify the number of items requested in response to the question, in this case five, and adds that to the questionJson object, as well.

String question = req.getParameter("questionText");
String dataset = req.getParameter("dataset");

JSONObject questionJson = new JSONObject();
questionJson.put("questionText",question);
JSONObject evidenceRequest = new JSONObject();
evidenceRequest.put("items",5);
questionJson.put("evidenceRequest",evidenceRequest);

JSONObject postData = new JSONObject();
postData.put("question",questionJson);

The following snippet shows the subsequent lines of code from the doPost method that execute the HTTP POST method to the Question and Answer API. The code creates a new instance of an Executor object with the necessary authorization paremeter used to authenticate the specified user name and password. It identifies the corpus to be queried, as indicated by the dataset parameter. It then executes the request, the results of which are returned as a string assigned to the answersJson variable.

The code calls the formatAnswers method of the DemoServlet class to parse the response from a JSON string to a key-value List object named answers. The following lines of code set the answers, questionText, and dataset attributes of the req object, which is then passed to the index.jsp page for presentation to the user.

Executor executor = Executor.newInstance().auth(username, password);
URI serviceURI = new URI(baseURL+ "/v1/question/"+dataset).normalize();
String answersJson = executor.execute(Request.Post(serviceURI)
    .addHeader("Accept", "application/json")
    .addHeader("X-SyncTimeout", "30")
    .bodyString(postData.toString(), ContentType.APPLICATION_JSON)
    ).returnContent().asString();

List<Map<String, String>> answers = formatAnswers(answersJson);

req.setAttribute("answers", answers);
req.setAttribute("questionText", question);
req.setAttribute("dataset", dataset);
...
req.getRequestDispatcher("/index.jsp").forward(req, resp);

The complete source code for the Java sample is shown in The sample application in Java. The example available from the demo of the Question and Answer service shows the results of the API.

Submitting feedback in a Node.js application

The Question and Answer API provides a single point of access to multiple industry-specific corpora. The Question and Answer service feedback API enables an application to provide answer relevancy ratings and user comments. Feedback values are:

  • 1: Relevant

  • -1: Not relevant

  • 9: Partially relevant

  • 0: No user feedback (default value)

User feedback should be collected based on whether the answer provided was appropriate. User comments enable a user to provide more in-depth information for an answer. The collected ratings and comments are used by Watson to improve learning.

The following example code shows how to provide user ratings and comments in a Node.js application. You can also download the full example code.

The code is intended to provide a starting point for your own experimentation. In the code, you must replace the strings service_url, service_username, and service_password with the corresponding values from the VCAP_SERVICES JSON environment variable, as described previously in Building and running the application locally.



  

Other Watson Developer Cloud services use an alternate feedback mechanism whose use is documented in the API reference material for each service.

API reference

See the API reference material to learn more about the Question and Answer API, including its functions and the HTTP verbs with which they are associated.