RxNorm API

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

The WSDL file for the RxNorm API can be found here.

Building Applications to use the RxNorm API

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

Development Environment Setup

Setup of a developer's environment involves the following steps. Each step must be completed before application code can be compiled and built to execute requests with the RxNorm API.

Obtain a Simple Object Access Protocol (SOAP) 1.2 compatible engine for web service message routing.
Download the WSDL for the RxNorm API web service.
Generate the client side stubs using Axis's WSDL2Java utility for the WSDL (for applications written in Java).

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 RxNorm 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.

Downloading the RxNorm WSDL

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

Generating Client Stubs

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 \
			<RXNORM_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.

Building Application Code using the RxNorm API

The examples in this section are written in Java. As examples become available, example code for other programming languages will be posted to the RxNav web site. The basic paradigm for obtaining RxNorm data from the RxNorm API web service is as follows:

Establish a connection to the RxNorm API web service.
Obtain the data from the RxNorm API web service.

Establishing a Connection to the RxNorm API Web Service

The RxNorm 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/RxNormDBService 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.RxNormDBService.*;

The following code snippet shows how to establish a connection to the RxNorm API web service.

String rxhost = "http://mor.nlm.nih.gov";
String rxURI = rxhost + "/axis/services/RxNormDBService";

// Locate the RxNorm API web service
URL rxURL = new URL(rxURI);
DBManagerService rxnormService = new DBManagerServiceLocator();
DBManager dbmanager = rxnormService.getRxNormDBService(rxURL);

Obtaining RxNorm Data

The RxNorm API web service provides access to current RxNorm data through its calls defined in the WSDL. The code snippet below searches for a concept unique identifier (RXCUI) using exact matching of an input string. Each operation made available in the RxNorm API web service is described in detail in the RxNorm API design document.

// Get the concept unique identifier for a string
String [] rxcuis = dbmanager.findRxcuiByString("aspirin");
// print results
for (int j = 0; j < rxcuis.length; j++)
    System.out.println("RXCUI = " + rxcuis[j]);
if (rxcuis.length == 0) 
    System.out.println("No concept found");

Compiling the Application

When compiling the application using the RxNorm 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

RxNorm API Reference

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

findRxcuiByString
findRxcuiById
getSpellingSuggestions
getRxConceptProperties
getRelatedByRelationship
getRelatedByType
getAllRelatedInfo
getDrugs
getNDCs
getRxNormVersion
getIdTypes
getRelaTypes
getTermTypes

findRxcuiByString( searchString )

Search for a name in the RxNorm data set and return the RXCUIs of any concepts which have that name as an RxNorm term or as a synonym of an RxNorm term.

Input:

searchString - the search string

Output:

an array of RxNorm identifiers

Example

findRxcuiByString( "zocor")     

returns: 
  { 19653 }

findRxcuiById( idType, id )

Search for an identifier from another vocabulary and return the RXCUIs of any concepts which have an RxNorm term as a synonym or have that identifier as an attribute.

Input:

idType - the identifier type. Valid types are:

AMPID - Alchemy Marketed Product Identifier
GCN - Generic Code Number
GFC - Generic Formula Code
GPPC - Generic Product Packing Code
GS - Gold Standard Alchemy identifier
LISTING_SEQ_NO - FDA Identification Number
MMSL_CODE - Multum identifier
NDC - National Drug Code
SNOMEDCT - SNOMEDCT Identifier
SPL - Standard Product Label
UMLSCUI - UMLS Concept Unique Identifier
VUID - Veterans Health Administration Unique Identifier

id - the identifier

Output:

an array of RxNorm identifiers

Example

findRxcuiById ( "UMLSCUI", "C0162723")    

returns:
  { 58930 }

getSpellingSuggestions( searchString )

Get spelling suggestions for a given term. The suggestions are RxNorm terms contained in the current version.

Input:

searchString - the name of the term

Output:

an array of names that are spelling suggestions of the input term, ranked by decreasing relevance.

Example

getSpellingSuggestions( "zyrteck" )

returns:
  {"Zyrtec", "Zyrtec-D", "zyrphen"}

getRxConceptProperties( rxcui )

Get the RxNorm Concept properties

Input:

rxcui - the RxNorm identifier

Output:

an RxNorm concept structure containing the following fields:

Name - RxNorm concept name
Rxcui - RxNorm identifier
Type - RxNorm term type. Valid term types are:
- IN - ingredient
- BN - brand name
- SBD - branded drug name
- SBDC - branded drug component
- SBDF - branded drug form
- SCD - clinical drug name
- SCDC - clinical drug component
- SCDF - clinical drug form
- DF - dose form
- BPCK - branded pack
- GPCK - generic pack
Lat - the language of the term
Suppress - the suppress flag
Umlscui - the UMLS concept unique identifier, if assigned
SY - the synonym (only applicable for type=SBD or type=BPCK)

Example

getRxConceptProperties( "58930")    

returns:

{ Name = "Zyrtec",  Rxcui = "58930", Type = "BN", Lat = "ENG", 
Suppress = "N", Umlscui = "C0162723", SY = "" }

getRelatedByRelationship( rxcui, relationship-list )

Get the related RxNorm identifiers of an RxNorm concept specified by a relational attribute.

Input:

rxcui - the RxNorm identifier
relationship-list - an array of the relationship attribute names such as "tradename_of", "has_form", "isa", etc

Output:

an array of RxNorm concept group structures. An RxNorm concept group structure has the following fields:

Type - the RxNorm term type
Array of RxNorm concept structures. See above for the description of the RxNorm concept structure.

Example

getRelatedByRelationship( "58930", {"tradename_of", "has_precise_ingredient"} )  

returns:

{
Type = "IN", {
{ Name = "Cetirizine", Rxcui = "20610", Type = "IN", Lat = "ENG", 
Suppress = "N", Umlscui = "C055147", SY = ""},
{ Name = "Cetirizine Dihydrochloride", Rxcui = "203150", Type = "IN", Lat = "ENG", 
Suppress = "N", Umlscui = "C0700480", SY = ""} }
}

getRelatedByType( rxcui, type-list )

Get the related RxNorm identifiers of an RxNorm concept specified one or more term types.

Input:

rxcui - the RxNorm identifier
type-list - an array of one or more RxNorm term types

Output:

an array of RxNorm concept group structures. An RxNorm concept group structure has the following fields:

Type - the RxNorm term type
Array of RxNorm concept structures. See above for the description of the RxNorm concept structure.

Example

getRelatedByType( "131725", {"IN", "SBD"} )  

returns:

{
Type = "IN", { 
{ Name = "zolpidem", Rxcui = "39993", Type = "IN", Lat = "ENG", 
Suppress = "N", Umlscui = "C0078839", SY = ""},
{ Name = "Zolpidem tartrate", Rxcui = "221183", Type = "IN", Lat = "ENG", 
Suppress = "N", Umlscui = "C0724725", SY = ""} }
Type = "SBD", {
{ Name = "zolpidem 10 MG Oral Tablet [Ambien]", Rxcui = "210762", Type = "SBD", Lat = "ENG", 
Suppress = "N", Umlscui = "C0712713", SY= "Ambien 10 MG Oral Tablet"},
{ Name = "zolpidem 12.5 MG Extended Release Tablet [Ambien]", Rxcui = "602455", Type = "SBD", Lat = "ENG", 
Suppress = "N", Umlscui = "C1628353", SY= "Ambien 12.5 MG Extended Release Tablet"}, 
{ Name = "zolpidem 5 MG Oral Tablet [Ambien]", Rxcui = "210749", Type = "SBD", Lat = "ENG", 
Suppress = "N", Umlscui = "C0712699", SY= "Ambien 5 MG Oral Tablet"}, 
{ Name = "zolpidem 6.25 MG Extended Release Tablet [Ambien]", Rxcui = "602459", Type = "SBD", Lat = "ENG", 
Suppress = "N", Umlscui = "C1630664", SY= "Ambien 6.25 MG Extended Release Tablet"} }
}

getAllRelatedInfo( rxcui )

Get all the related RxNorm concepts for a given RxNorm identifier. This includes concepts of term types "IN", "BN", "SBD", "SBDC", "SBDF", "SCD", "SCDC", "SCDF", "DF", "BPCK" and "GPCK".

Input:

rxcui - the RxNorm identifier

Output:

an array of RxNorm concept group structures. An RxNorm concept group structure has the following fields: Type - the RxNorm term type Array of RxNorm concept structures. See above for the description of the RxNorm concept structure.

Example

getAllRelatedInfo( "151524" ) 

returns:

{
Type = "IN", { 
{ Name = "Sulindac", Rxcui = "10237", Type = "IN", Lat = "ENG", Suppress = "N", 
Umlscui = "C0038792", SY = ""} }
Type = "BN", {
{ Name = "Clinoril", Rxcui = "151524", Type = "BN", Lat = "ENG", Suppress = "N", 
Umlscui = "C0591267", SY = ""} }
Type = "SCDC", {
{ Name = "Sulindac 150 MG", Rxcui = "316755", Type = "SCDC", Lat = "ENG", 
Suppress = "N", Umlscui = "C0990458", SY= ""},
{ Name = "Sulindac 200 MG", Rxcui = "316756", Type = "SCDC", Lat = "ENG", 
Suppress = "N", Umlscui = "C0990459", SY= ""} }
Type = "SBDC", {
{ Name = "Sulindac 150 MG [Clinoril]", Rxcui = "569138", Type = "SBDC", Lat = "ENG", 
Suppress = "N", Umlscui = "C1618559", SY= ""},
{ Name = "Sulindac 200 MG [Clinoril]", Rxcui = "564274", Type = "SBDC", Lat = "ENG", 
Suppress = "N", Umlscui = "C1617517", SY= ""} }
Type = "SCD", {
{ Name = "Sulindac 150 MG Oral Tablet", Rxcui = "198238", Type = "SCD", Lat = "ENG", 
Suppress = "N", Umlscui = "C0690432", SY= ""},
{ Name = "Sulindac 200 MG Oral Tablet", Rxcui = "198239", Type = "SCD", Lat = "ENG", 
Suppress = "N", Umlscui = "C0690433", SY= ""} }
Type = "SBD", {
{ Name = "Sulindac 150 MG Oral Tablet [Clinoril]", Rxcui = "198238", Type = "SBD", Lat = "ENG", 
Suppress = "N", Umlscui = "C0710020", SY= "Clinoril 150 MG Oral Tablet"}, 
{ Name = "Sulindac 200 MG Oral Tablet [Clinoril]", Rxcui = "105944", Type = "SBD", Lat = "ENG", 
Suppress = "N", Umlscui = "C0357508", SY= "Clinoril 200 MG Oral Tablet"} }
Type = "SCDF", {
{ Name = "Sulindac Oral Tablet", Rxcui = "374003", Type = "SCDF", Type = "SCDF", Lat = "ENG", 
Suppress = "N", Umlscui = "C1248075", SY= ""} }
Type = "SBDF", {
{ Name = "Sulindac Oral Tablet [Clinoril]", Rxcui = "367629", Type = "SBDF", Lat = "ENG", 
Suppress = "N", Umlscui = "C1621233", SY= ""} }
Type = "DF", {
{ Name = "Oral Tablet", Rxcui = "317541", Type = "DF", Lat = "ENG", 
Suppress = "N", Umlscui = "C0993159", SY= ""} }
Type = "BPCK", {}
Type = "GPCK", {}
}

getDrugs( name )

Get the drug products associated with a specified name. The name can be an ingredient, brand name, clinical drug form, branded drug form, clinical drug component, or branded drug component.

Input:

name - the name of the drug

Output:

An array of concept group structures whose types are "SBD" and "BPCK" for brand names, branded drug forms or branded drug components, or "SCD" and "GPCK" for ingredients, clinical drug forms or clinical drug components.

Example 1:

getDrugs( "varenicline" )  

returns:

{
Type = "SCD", {
{ Name = "varenicline 0.5 MG Oral Tablet", Rxcui = "636671", Type = "SCD", 
Lat = "ENG", Suppress = "N", Umlscui = "C1711886", SY= ""},
{ Name = "varenicline 1 MG Oral Tablet", Rxcui = "636676", Type = "SCD", 
Lat = "ENG", Suppress = "N", Umlscui = "C1711889", SY= ""} }
Type = "GPCK", {
{ Name = "{ 56 (varencline 1 MG Oral Tablet) } Pack", RxCui = "749788", Type = "GPCK", 
Lat = "ENG", Suppress = "N", Umlscui = "", SY= ""} }
}

Example 2:

getDrugs("cymbalta")   

returns:

{
Type = "SBD", {
{ Name = "duloxetine 20 MG Enteric Coated Capsule [Cymbalta]", Rxcui = "596928", 
Type = "SBD", Lat = "ENG", Suppress = "N", Umlscui = "C1656295", 
SY= "Cymbalta 20 MG Enteric Coated Capsule"},
{ Name = "duloxetine 30 MG Enteric Coated Capsule [Cymbalta]", Rxcui = "596932", 
Type = "SBD", Lat = "ENG", Suppress = "N", Umlscui = "C1614249", 
SY= "Cymbalta 30 MG Enteric Coated Capsule"},
{ Name = "duloxetine 60 MG Enteric Coated Capsule [Cymbalta]", Rxcui = "615186", 
Type = "SBD", Lat = "ENG", Suppress = "N", Umlscui = "C1624617", 
SY= "Cymbalta 60 MG Enteric Coated Capsule"} }
Type = "BPCK", {}
}

getNDCs( rxcui )

Get the National Drug Codes (NDCs) for the RxNorm concept.

Input:

rxcui - the RxNorm identifier

Output:

An array of NDCs

Example

getNDCs( "105259")    

returns:
             
  { "00069305050", "00069305086", "51129930501", "60491072206" }

getRxNormVersion( )

Get the version of the RxNorm data set.

Input:

None

Output:

The version of the RxNorm data set

Example

getRxNormVersion()   

returns  "07AC_071228F"

getIdTypes()

Get the valid identifier types of the RxNorm data set. See findRxCuiById for use of these types.

Input:

None

Output:

An array of valid identifier types.

Example

getIdTypes()   

returns:
 
{"AMPID",  "GCN", "GFC", "GPPC", "LISTING_SEQ_NO", "MMSL_CODE",  "NDC", "SNOMEDCT", 
"SPL", "UMLSCUI", "VUID" }

getRelaTypes()

Get the relationship names in the RxNorm data set.

Input:

None

Output:

An array of relationship names. See getRelatedByRelationship for use of these names.

Example

getRelaTypes()    

returns:

{ "consists_of", "constitutes", "contained_in", "contains", "dose_form_of", 
"form_of", "has_dose_form", "has_form", "has_ingredient", "has_precise_ingredient", 
"has_tradename", "ingredient_of", "inverse_isa", "isa", "precise_ingredient_of", 
"reformulated_to", "reformulation_of", "tradename_of" }

getTermTypes()

Get the valid term types in the RxNorm data set.

Input:

None

Output:

An array of the valid term types. See getRelatedByType for use of these term types.

Example

getTermTypes()     

returns:

{ "BN", "BPCK", "DF", "GPCK", "IN", "SBD", "SBDC", "SBDF", "SCD", "SCDC", "SCDF"}