RxNav

RxTerms API

updated: 1/11/2012

Lister Hill Center


The RxTerms API is a web service for accessing the current RxTerms data set from your program via SOAP/WSDL.

Quick Links:

Building a Java Application to use the RxTerms API

The RxTerms API provides developers with functions for retrieving RxTerms data from the most current RxTerms data set. Building applications to use the RxTerms API require initial setup of the development environment and developing code. Each of these is described in detail in this chapter.

Java Development Environment Setup

Setup of a Java developer's environment involves the following steps. All steps must be completed before application code can be compiled and built to execute requests with the RxTerms API.
  1. Obtain a Simple Object Access Protocol (SOAP) 1.2 compatible engine for web service message routing.
  2. Download the WSDL for the RxTerms API web service.
  3. Generate the client side stubs using Axis's WSDL2Java utility for the WSDL (for applications written in Java).

1. Obtaining a SOAP 1.2 Engine

Developers will require a Simple Object Access Protocol (SOAP) 1.2 compatible engine to route the web service messages to/from the RxTerms API. The client programs shown in this guide have been tested with Apache Axis Version 1.4 Follow the link to their website and download and install the version onto your development machine. The location of this download will be referred to as <AXIS_DIR> in this guide.

2. Downloading the RxTerms WSDL

The RxTerms WSDL may be downloaded from the RxNav web site. Right-click on the RxTerms API WSDL and save the WSDL file to your development machine. The path to this file will be hereafter referred to as <RXTERMS_WSDL_LOCATION>.

3. Generating Client Stubs for Java

Apache Axis is delivered with a utility to generate Java classes from a WSDL. Using WSDL2Java generates client stubs that enable communication with a defined web service. 
  prompt> java -classpath  <CLASSPATH> org.apache.axis.wsdl.WSDL2Java \
      <RXTERMS_WSDL_LOCATION>
The call to the utility places generated Java class files in the directory where the utility is run. The <CLASSPATH> must include the following jar files generally found in the lib directory of the Axis installation: 
axis.jar
wsdl4j-1.5.1.jar
commons-logging-1.0.4.jar
commons-discovery-0.2.jar
jaxrpc.jar
saaj.jar
activation.jar
mail.jar
Other SOAP engines use different utilities to generate the client stubs. Refer to your specific SOAP engine documentation for instructions on building the client stubs using the downloaded WSDL.

Coding Java Applications to use the RxTerms API

The basic paradigm for obtaining RxTerms data from the RxTerms API web service is as follows:
  1. Establish a connection to the RxTerms API web service.
  2. Obtain the data from the RxTerms API web service.

Java Code: Establishing a Connection to the RxTerms API Web Service

The RxTerms API web service is an Axis web service running at the NLM on the RxNav production machine. The web service endpoint URI is http://mor.nlm.nih.gov/axis/services/RxTermsAPI The classes generated during WSDL2Java execution must be imported into your application. For Java applications, include these import statements: 
import java.net.URL;
import BeanService.*;
import gov.nih.nlm.mor.axis.services.RxTermsAPI.*;
The following code snippet shows how to establish a connection to the RxTerms API web service. 
String rxhost = "http://mor.nlm.nih.gov";
String rxURI = rxhost + "/axis/services/RxTermsAPI";

// Locate the RxTerms API web service
URL rxURL = new URL(rxURI);
RxTermsServiceServiceLocator rxtermsService = new RxTermsServiceServiceLocator();
RxTermsService dbmanager = rxtermsService.getRxTermsAPI(rxURL);

Java Code: Obtaining RxTerms Data

The RxTerms API web service provides access to current RxTerms data through its calls defined in the WSDL. The code snippet below gets the RxTerms display name for a given RxNorm concept identifier (RxCUI). Each operation made available in the RxTerms API web service is described in detail in the RxTerms API reference section. 
// Get the concept unique identifier for a string
String displayName = dbmanager.getRxTermDisplayName("198440");
// print results
System.out.println("RxTerms Name = " + displayName);

Compiling the Java Application

When compiling the application using the RxTerms API, the CLASSPATH must include the directory into which the compiled stubs were put and the following jar files which are generally found in the lib directory of the Axis installation: 
axis.jar
wsdl4j-1.5.1.jar
commons-logging-1.0.4.jar
commons-discovery-0.2.jar
jaxrpc.jar
saaj.jar
activation.jar
mail.jar


RxTerms API Reference

This section contains the design details of the RxTerms API. Each function contains a description, the inputs to the function, the outputs from the function and examples. Available functions:

Function Description
getAllRxTermInfo Retrieve RxTerms information for a specified RxNorm concept
getRxTermDisplayName Retrieve the RxTerms display name for a specified RxNorm concept
getRxTermsVersion Retrieve the RxTerms version
getAllConcepts new Retrieve all RxTerms concepts

getAllRxTermInfo( rxcui )

Get the RxTerms information for a specified RxNorm concept.

Input:

rxcui - the RxNorm concept identifier

Output:

an RxTerms concept structure containing the following fields:

Example

getAllRxTermInfo( "209459")    

returns:

{ Brand name = "TYLENOL",  Display name = "TYLENOL (Oral-pill)", 
Display name synonym = "", Full name = "Acetaminophen 500 MG Oral Tablet [Tylenol]",
Full generic name = "Acetaminophen 500 MG Oral Tablet",  Generic RxCUI = "198440",
Dose form = "Tabs", Route = "Oral-pill", RxCUI = "209459", RxNorm dose form = "Oral Tablet",
Strength = "500 mg", Suppress = "", Term Type = "SBD"}

getRxTermDisplayName( rxcui )

Get the RxTerms display name for a specified RxNorm concept.

Input:

rxcui - the RxNorm concept identifier

Output:

The RxTerms display name.

Example

getRxTermDisplayName( "209459" )  

returns "TYLENOL (Oral-pill)"

getRxTermsVersion( )

Get the version of the RxTerms data set.

Input:

None

Output:

The version of the RxTerms data set.

Example

getRxTermsVersion()   

returns  "RxTerms201011"

getAllConcepts( )

Get the RxTerms information for all RxNorm concepts in the RxTerms data set.

Input:

None

Output:

An array of RxTerms minimal concept structures, each structure containing:

Example

getAllConcepts( )    

returns:
{
  { 
    Full name = "Acetaminophen 500 MG Oral Tablet [Tylenol]",
    RxCUI = "209459", 
    Term Type = "SBD" 
  }

   (many more ...)
}

RxTerms Web API Client

An interactive web client which calls the RxTerms API functions is publicly available. To access the client, bring up a web browser and enter the following URL: http://mor.nlm.nih.gov/perl/rxterms_api_demo.pl

This will bring up the application shown below:

RxTerms API Client


The web application can call any of the API functions available from the Method: drop down list. Parameters for the functions are entered in the Arg1 position on the screen. In the example below, the function getAllRxTermInfo is selected and 209459 is entered for Arg1 (the RxCUI). The answer is shown in the colored box below the form.

RxTerms API Client - getAllRxTermInfo

Comments? Feedback? Questions?
Contact: Contact us

U.S. National Library of Medicine, 8600 Rockville Pike, Bethesda, MD 20894
National Institutes of Health, Department of Health & Human Services
Copyright, Privacy, Accessibility