RxNorm API

updated: 2/21/2012

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

Useful links:

RxNorm API Reference (updated 2/09/2012)
RxNorm Web API Client
Recent changes to the RxNorm API
RxNorm RESTful Web API User's Guide
RxNorm API WSDL

Building Applications to Use the RxNorm API

This page describes how to build applications to use the RxNorm API.
We provide documentation for coding Java and .Net applications. Documentation for building applications in other programming languages (e.g. Perl) may be added at a later time.

Building a Java Application to use the RxNorm API
Building a .Net Application to use the RxNorm API

Building a Java Application 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.

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

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

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

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

Coding Java Applications to use the RxNorm API

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.

Java Code: 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.rxnav.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);

Java Code: 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 Java 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

Building a .Net Application to use the RxNorm API

.Net Development Environment and Project Setup

Setup of a .Net developer's environment involves the following steps:

Install a current version of Microsoft Visual Studio .Net, selecting at least these options: VB, C#, and Web development. This tutorial mainly assumes VS 2010, but 2008 is known to work with minor differences.
Start up Visual Studio. If it asks for default settings, choose C# or VB, depending on your preference. In this tutorial, we use C#.
From the Visual Studio menu, choose File -> New Project
In the Left pane, choose Visual C# -> Windows
In the Right Pane, choose either Console Application (for a command-line-driven application) or Windows Forms Application (for a GUI-driven application)
In the "Name:" box, enter a name for your project: RxNormClient or RxNorm_GUI_Client (or any project name you want)
A new C# file skeleton named Program.cs that contains an empty Main() method in the Program class will be generated.
Do not close Visual Studio and do not close the project or the current program file. You will need to return here later to complete the project setup.

Downloading the RxNorm WSDL and Generating a Client Stub for .Net

In the steps below,

[your_home_dir] refers to where the RxNormClient "Program.cs" file was just generated. Example on Windows XP with VS 2010:
```
C:\Documents and Settings\[your_username]\\My Documents\Visual Studio 2010\Projects\RxNormClient\RxNormClient
```

[your_wsdl_dir] is where the latest version of wsdl.exe is on your machine. Typical examples:

C:\Program Files\Microsoft SDKs\Windows\v6.0A\bin
C:\Program Files\Microsoft SDKs\Windows\v7.1\Bin
C:\Program Files\Microsoft SDKs\Windows\v7.1\Bin\NETFX 4.0 Tools

[your_csc_dir] is where the latest version of csc.exe is on your machine. Examples:

C:\WINDOWS\Microsoft.NET\Framework\v4.0.30318
C:\WINDOWS\Microsoft.NET\Framework\v3.5

Open a command prompt window and enter:

cd [your_source_dir]
"[your_wsdl_dir]\wsdl.exe" /l:CS /protocol:SOAP http://rxnav.nlm.nih.gov/RxNormDBService.xml

The following message should be displayed:

Writing file '[your_source_dir]\DBManagerService.cs'

Your client stub is in the .cs file that was just created (DBManagerService.cs in this example)

Putting the pieces together into a .Net project

You can now either...
1. Add your client stub source file to your project in Visual Studio
  - In the Solution Explorer pane, right-click the project name and choose Add -> Existing Item
    (The beauty of this option is that it allows you to step into the stub source code in Debug mode.)
2. Compile the stub into a DLL, by first executing the command line:
```
      "[your_csc_dir]\csc.exe" /t:library /r:System.Web.Services.dll /r:System.Xml.dll DBManagerService.cs
        
```
  then adding the DLL as a Reference to your project:
  - Right-click the project name in the Solution Explorer pane
  - Choose Add Reference... then select the Browse tab.
Finally, your project needs a reference to the .Net Web Services namespace before it will compile:
- Right-click the project name in the Solution Explorer pane.
- Choose Add Reference... then select the .Net tab.
- Select System.Web.Services and click OK.
You are now ready to code your class's Main() method in any way you wish.

RxNorm API Reference

This section 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:

Function	Description
approxMatch	Search by name to find the closest RxNorm concepts
findRemapped	Return the re-mapped concept identifiers from an obsolete concept
findRxcuiById	Search by identifier to find RxNorm concepts
findRxcuiByString	Search by name to find RxNorm concepts
getAllConceptsByTTY	Return the RxNorm concepts for the specified term types
getAllProperties	Return all properties for a concept
getAllRelatedInfo	Return all related concept information
getDisplayTerms	Return the auto suggestion names
getDrugs	Return the related drugs
getIdTypes	Return the available identifier types
getMultiIngredBrand	Return the brands containing the specified ingredients
getNDCs	Return all National Drug Codes (NDC) for a concept
getPropCategories	Return the property categories.
getPropNames	Return the property names.
getProprietaryInformation	Return the proprietary information for a concept
getQuantity	Return the quantity attribute for a concept
getRelatedByRelationship	Return the related concepts of specified relationship types
getRelatedByType	Return the related concepts of specified term types
getRelaTypes	Return the available relationship types
getRxConceptProperties	Return the concepts properties
getRxcuiStatus	Return the status of the concept
getRxNormVersion	Return the RxNorm data set version
getSourceTypes	Return the available vocabulary abbreviated source types
getSpellingSuggestions	Return spelling suggestions for a name
getSplSetId	Return the structured product label set identifiers for a concept
getStrength	Return the strength attribute for a concept
getTermTypes	Return the available term types
getUNII	Return the UNII Code for a concept

A sample API client written in perl is also available.

approxMatch( searchString )

Do an approximate match search to determine the strings in the data set that most closely match the search string. The approximate match algorithm is discussed in detail here.

Input:

searchString - the search string

Output:

An array of matching structures. Each matching structure contains the following fields:

Rxcui - RxNorm concept identifier
Rxaui - RxNorm string identifier
score - a score ranging from 0 to 100 indicating the closeness of the match.
rank - the rank of this string to all possible candidates

To get more information about the string, including the name and the vocabulary source, use getProprietaryInformation with the Rxaui returned in the matching structure.

Example

approxMatch( "ACETAMINOPHEN 500 MG CAPLET" )

returns:

{
  {Rxcui = "315266", Rxaui = "1476962", score = "75", rank = "1"},
  {Rxcui = "198440", Rxaui = "2542263", score = "67", rank = "2"},
  {Rxcui = "570042", Rxaui = "2285667", score = "60", rank = "3"},
  {Rxcui = "570063", Rxaui = "2285688", score = "60", rank = "3"},
  {Rxcui = "198439", Rxaui = "1908931", score = "60", rank = "3"},
  {Rxcui = "250651", Rxaui = "1277958", score = "60", rank = "3"},
  {Rxcui = "570064", Rxaui = "2285689", score = "60", rank = "3"},
  {Rxcui = "1095479", Rxaui = "3629097", score = "60", rank = "3"},
  {Rxcui = "198440", Rxaui = "1117683", score = "60", rank = "3"},
  {Rxcui = "570055", Rxaui = "2285680", score = "60", rank = "3"},
  {Rxcui = "198440", Rxaui = "1117685", score = "60", rank = "3"},
  {Rxcui = "570056", Rxaui = "2285681", score = "60", rank = "3"},
  {Rxcui = "570053", Rxaui = "2285678", score = "60", rank = "3"},
  {Rxcui = "570054", Rxaui = "2285679", score = "60", rank = "3"},
  {Rxcui = "570052", Rxaui = "2285677", score = "60", rank = "3"},
  {Rxcui = "198440", Rxaui = "3095258", score = "60", rank = "3"},
  {Rxcui = "198440", Rxaui = "2835101", score = "60", rank = "3"},
  {Rxcui = "570046", Rxaui = "2285671", score = "60", rank = "3"},
  {Rxcui = "570072", Rxaui = "2285697", score = "60", rank = "3"},
  {Rxcui = "198439", Rxaui = "2835100", score = "60", rank = "3"},
  {Rxcui = "570070", Rxaui = "2285695", score = "60", rank = "3"},
  {Rxcui = "198439", Rxaui = "3095254", score = "60", rank = "3"},
  {Rxcui = "570050", Rxaui = "2285675", score = "60", rank = "3"},
  {Rxcui = "198439", Rxaui = "3095255", score = "60", rank = "3"},
  {Rxcui = "198439", Rxaui = "1908927", score = "60", rank = "3"},
  {Rxcui = "198440", Rxaui = "3095257", score = "60", rank = "3"},
  {Rxcui = "198439", Rxaui = "1908929", score = "60", rank = "3"},
  {Rxcui = "198440", Rxaui = "2063136", score = "60", rank = "3"},
  {Rxcui = "570461", Rxaui = "2286136", score = "60", rank = "3"}
}

findRemapped( rxcui )

This function will be deprecated - please use getRxcuiStatus instead. Find the concepts that have been remapped from an obsolete concept. These remapped concepts are defined in the RXNCUI file.

Input:

rxcui - the RxNorm identifier of the obsolete concept

Output:

An array of concept identifier from which the obsolete concept has been mapped to. Note that usually there is a one to one mapping, but some obsolete concepts are mapped to more than one new concept.

Example

getRemapped( 213578 )

returns:

{ "1012626", "1012843" }

findRxcuiById( idType, id, allSourcesFlag )

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. See the getIdTypes example for the valid types. The table below describes the types:

idType	Example	Details
AMPID	2050	the Gold Standard Drug Identifier from Gold Standard Drug Database (SAB:GS)
ANDA	ANDA007581	the FDA Abbreviated New Drug Application identifier
GCN_SEQNO	009172	the Generic Code Sequence Number from First Databank Inc (SAB:NDDF)
GFC	108077	the Generic Formula Code (GFC) from Micromedex RED BOOK (SAB:MMX)
GPPC	14559	the first five characters of the Generic Product Packaging Code from Master Drug Data Base (SAB:MDDB). Medi-Span, a division of Wolters Kluwer Health
HIC_SEQN	004489	the ingredient identifier from First Databank Inc (SAB:NDDF)
LISTING_SEQ_NO	203855	the FDA generated unique identification number for each product from FDA National Drug Code Directory (SAB:MTHFDA)
MESH	D000212	a Subject Medical Headings (MeSH) identifier from the National Library of Medicine (SAB:MSH).
MMSL_CODE	CD1001	a derived identifier that combines the Term type (TTY) and the Multum Mediasource Lexicon (SAB:MMSL) numeric code. First two letters represent the term type: BD, BN, CD, GN or IN.
NDA	NDA021400	the FDA New Drug Application identifier
NDC	00378802505	the National Drug Code (NDC) from the National Drug Code Directory
NUI	N0000148200	the National Drug File Reference Terminology unique identifier (SAB:NDFRT)
SNOMEDCT	1039008	the SNOMED CT concept identifier from SNOMED Clinical Terms drug information (SAB:SNOMEDCT). SNOMED International
SPL_SET_ID	1C5BC1DD-E9EC-44C1-9281-67AD482315D9	the FDA Structured Product Label Set Identifier
UMLSCUI	C0000266	the Unified Medical Language System (UMLS) Concept Unique Identifier
UNII_CODE	LVX8N1UT73	the FDA Unique Ingredient Identifier Code.
VUID	4021359	the Veterans Health Administration Unique Identifier from the Veterans Health Administration National Drug File (SAB:VANDF)

id - the identifier

allSourcesFlag - a flag indicating whether all RxCUIs are to be returned. If set to 1, all non-suppressed RxCUIs will be returned, including those which contain no terms from the RxNorm vocabulary. Otherwise, only RxCUIs which contain a non-suppressed RxNorm vocabulary term will be returned.

Output:

an array of RxNorm identifiers

Example

findRxcuiById ( "UMLSCUI", "C0162723", 0)    

returns:
  { 58930 }

findRxcuiByString( searchString, source-list, allSourcesFlag, searchType )

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

source-list - an array containing the source vocabulary names to use. If null, all sources are allowed. Only used when allSourcesFlag is set to 1. Valid source types are listed in the getSourceTypes example.

allSourcesFlag - a flag indicating whether all RxCUIs are to be returned. If set to 1, all non-suppressed RxCUIs will be returned which match any of the sources specified. Otherwise, only RxCUIs which contain a non-suppressed RxNorm term will be returned.

searchType - a number indicating the type of search to be performed. If set to 0, exact match search will be performed. If set to 1, a normalized string search will be done. When searchType = 2, then an exact match search will be done, and if no results are found, a normalized search will be done. For more information on the normalized string search, click here.

Output:

an array of RxNorm identifiers

Examples

findRxcuiByString( "ETHINYL ESTRADIOL 0.03MG/NORGESTREL 0.3MG TAB", , 0, 0)

returns:
  { 749786 }


findRxcuiByString( "ETHINYL ESTRADIOL 0.03MG/NORGESTREL 0.3MG TAB", , 0, 1)

returns:
  { 311359, 749786 }


findRxcuiByString( "ETHINYL ESTRADIOL 0.03MG/NORGESTREL 0.3MG TAB", , 0, 2)

returns:
  { 749786 }

getAllConceptsByTTY( termtypes )

Return all the concepts for the specified term types.

Input:

termtypes - an array of term types. See the getTermTypes example for the names of valid term types.

Output:

An array of concept minimal structures. Each concept minimal structure contains the following fields:

Rxcui - RxNorm concept identifier
name - RxNorm string identifier
tty - term type

Example

getAllConceptsByTTY( {"BN","BPCK"} )

returns:

{
  {Rxcui = "1000002", name = "Tribenzor 40/5/25", tty = "BN"},
  {Rxcui = "1000016", name = "Uritact", tty = "BN"},
  {Rxcui = "1000086", name = "Lastacaft", tty = "BN"},

  (many more listed ...)
}

getAllProperties( rxcui, categories )

Get all properties for a specified concept.

Input:

rxcui - the RxNorm concept identifier.

categories - an array of category types. See getPropCategories for the names of valid categories. To get all properties for all categories, specify "ALL" (see example below).

Output:

An array of property structures. Each property structure contains

Name - the property name
Value - the property value
Category - the category of the property

Example

getAllProperties( "476299", {"ALL"} )

returns:
{
  { name="TTY",          value="SCD", category="ATTRIBUTES"},
  { name="HUMAN_DRUG",   value="US",  category="ATTRIBUTES"},
  { name="PRESCRIBABLE", value="Y",   category="ATTRIBUTES"},
  { name="AVAILABLE_STRENGTH", value="600 MG", category="ATTRIBUTES"},
  { name="RxCUI",        value="476299",   category="CODES"},
  { name="UMLSCUI",      value="C1509258", category="CODES"},
  { name="RxNorm Name",  value="Amoxicillin trihydrate 600 MG Disintegrating Tablet", category="NAMES"},
  { name="Source",       value="Multum MediSource Lexicon", category="SOURCES"}
}

getAllRelatedInfo( rxcui )

Get all the related RxNorm concepts for a given RxNorm identifier. This includes concepts of term types "IN", "MIN", "PIN", "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 = "SCDG", {
{ Name = "Sulindac Oral Products", Rxcui = "1163018", Type = "SCDG", Lat = "ENG",
Suppress = "N", Umlscui = "", SY= ""},
{ Name = "Sulindac Pills", Rxcui = "1163019", Type = "SCDG", Lat = "ENG",
Suppress = "N", Umlscui = "", SY= ""} }
Type = "SBDG", {
{ Name = "CLinoril Oral Products", Rxcui = "1173005", Type = "SBDG", Lat = "ENG",
Suppress = "N", Umlscui = "", SY= ""},
{ Name = "Clinoril Pills", Rxcui = "1173006", Type = "SBDG", Lat = "ENG",
Suppress = "N", Umlscui = "", SY= ""} }
Type = "DFG", {
{ Name = "Oral Products", Rxcui = "1151131", Type = "DFG", Lat = "ENG",
Suppress = "N", Umlscui = "", SY= ""},
{ Name = "Pills", Rxcui = "1151133", Type = "DFG", Lat = "ENG",
Suppress = "N", Umlscui = "", SY= ""} }
Type = "DF", {
{ Name = "Oral Tablet", Rxcui = "317541", Type = "DF", Lat = "ENG",
Suppress = "N", Umlscui = "C0993159", SY= ""} }
Type = "PIN", {}
Type = "BPCK", {}
Type = "GPCK", {}
Type = "MIN", {}
}

getDisplayTerms( )

Gets the names used by RxNav for auto completion. This is a large list which includes names of ingredients, brands, and branded packs.

Input:

None

Output:

An array of ingredient, brand and branded pack RxNorm names.

Example

getDisplayTerms()

returns:
(a list of names used by the auto completion function of RxNav)

getDrugs( name )

Get the drug products associated with a specified name. The name can be an ingredient, brand name, clinical dose form, branded dose 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 dose forms or branded drug components, or "SCD" and "GPCK" for clinical dose forms or clinical drug components. For ingredients "SBD", "BPCK", "SCD" and "GPCK" are returned.

Example 1:

getDrugs( "varenicline" )

returns:

{
Type = "BPCK", {
{ Name = "{56 (varenicline 1 MG Oral Tablet [Chantix]) } Pack [Chantix Continuing Months Of Therapy]",
Rxcui = "795735", Type = "BPCK",
Lat = "ENG", Suppress = "N", Umlscui = "C1877454", SY= "Chantix Continuing Months Of Therapy Pack"},
{ Name = "{11 (varenicline 0.5 MG Oral Tablet [Chantix]) / 42 (varenicline 1 MG Oral Tablet [Chantix]) } Pack [Chantix First Month of Therapy]",
Rxcui = "795737", Type = "BPCK",
Lat = "ENG", Suppress = "N", Umlscui = "C1877455", SY= "Chantix First Month Of Therapy Pack"} }
Type = "GPCK", {
{ Name = "{11 (varenicline 0.5 MG Oral Tablet) / 42 (varenicline 1 MG Oral Tablet) }", RxCui = "749289", Type = "GPCK",
Lat = "ENG", Suppress = "N", Umlscui = "C1968342", SY= ""},
{ Name = "{ 56 (varencline 1 MG Oral Tablet) } Pack", RxCui = "749788", Type = "GPCK",
Lat = "ENG", Suppress = "N", Umlscui = "C1968394", SY= ""} }
Type = "SBD", {
{ Name = "varenicline 0.5 MG Oral Tablet[Chantix]", Rxcui = "637188", Type = "SBD",
Lat = "ENG", Suppress = "N", Umlscui = "C1712045", SY= "Chantix 0.5 MG Oral Tablet"},
{ Name = "varenicline 1 MG Oral Tablet[Chantix]", Rxcui = "637190", Type = "SBD",
Lat = "ENG", Suppress = "N", Umlscui = "C1712047", SY= "Chantix 1 MG Oral Tablet"} }
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= ""} }
}

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", {}
}

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",  "ANDA", "GCN_SEQNO", "GFC", "GPPC", "HIC_SEQN", "LISTING_SEQ_NO", "MESH", "MMSL_CODE",  "NDA", "NDC", "NUI", "SNOMEDCT",
"SPL_SET_ID", "UMLSCUI", "UNII_CODE", "VUID" }

getMultiIngredBrand( rxcui-list )

Get the brands that contain all the specified ingredients. Note that the brands returned may contain other ingredients in addition to those specified.

Input:

rxcui-list - list of the RxCuis of the ingredients

Output:

an RxNorm concept structure containing the following fields:

Name - RxNorm concept name
Rxcui - RxNorm identifier
Type - RxNorm term type
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

getMultiIngredBrand( {1191, 33408} )

returns:

{Name = "Momentum tradename", Rxcui = "218423", Type = "BN", Lat = "ENG", Suppress = "N", Umlscui = "C0721776", SY = ""}

getNDCs( rxcui )

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

Input:

rxcui - the RxNorm identifier

Output:

An array of NDCs

Example

getNDCs( "351772")

returns:

  {"00069315014", "0069315083", 54868452700"}

getPropCategories( )

Get the property categories.

Example

getPropCategories()

returns:

{ "ATTRIBUTES", "CODES", "NAMES", "SOURCES" }

getPropNames( )

Get the property names.

Example

getPropNames()

returns:

{
  "ACTIVATED", "ANDA", "AVAILABLE_STRENGTH", "BN_CARDINALITY", "HUMAN_DRUG",
  "IN_EXPRESSED_FLAG", "NDA", "ORIG_CODE", "ORIG_SOURCE", "PRESCRIBABLE",
  "QUANTITY", "RxCUI", "RxNorm Name", "RxNorm Synonym", "SPL SET ID",
  "STRENGTH", "Source", "TTY", "UMLSCUI", "UNII_CODE", "VET_DRUG"
}

getProprietaryInformation( rxcui, source-list, proxyTicket, rxaui )

Get the concept information associated with the concept for the specified sources. The user must have a valid UMLS license and be able to access the UTS authority service to obtain proxy tickets to use this function.

Input:

rxcui - the RxNorm identifier

source-list - an array containing the source vocabulary names to use. Valid source values are returned in getSourceTypes.

proxyTicket - a proxy ticket obtained from the UTS authority service. Here is how to obtain the proxy ticket:

Make sure you already have a UMLS license.
Note that your program's users will also need to have their own license.
Download the UTS Authentication Web Service WSDL and generate a client stub AuthorizationService.cs out of it. This is done in a way that is similar to downloading the RxNorm WSDL and generating a client stub for it (described earlier in this document), except that the WSDL location is https://uts-ws.nlm.nih.gov/authorization/services/AuthorizationPort?WSDL.
Establish a SSL connection to the Authentication Web Service.
- Java programmers: Visit the UTS API documentation to learn how this is done in Java.
- .Net programmers: All you need to do is simply install the UTS certificate on your Windows computer. (You also must instruct your program's users to do the same.) The Microsoft .Net framework takes care of actually establishing a secure connection for your program using the certificate.
  To do this, use Internet Explorer to visit the UTS web site (at https://uts.nlm.nih.gov). When you see a message from your browser asking you to accept the certificate, click on "View certificate" then "Install Certificate" and complete the process as prompted. You will need to instruct all users of your program to do the same or else the getProprietaryInformation() function won't work from within your program.
Add to your project the client stub file AuthorizationService.cs which you generated from the Authentication Web Service WSDL.
Implement within your application the code to programatically obtain a Proxy Granting Ticket (PGT). Visit the UTS API documentation to learn how this is done in Java.
Implement within your application the code to use the PGT to programatically obtain a single-use Proxy Ticket from the UTS Authentication Web Service. Visit the UTS API documentation to learn how this is done in Java.

rxaui - this is an optional parameter which specifies the atomic unique identifier to search on.

Output:

an array containing concept information. Each structure contains the following fields:

RxCui - the RxNorm identifier
Name - the name
Type - the source term type
Id - the source specific identifier
Source - the source vocabulary

Example

getProprietaryInformation( "61609", {"SNOMEDCT", "MMSL"}, ticket)

returns:

{{RxCui= "61609", Name= "Arbutamine", Type= "PT", Id= "109207004", Source= "SNOMEDCT"},
 {RxCui= "61609", Name= "Arbutamine (substance)", Type= "FN", Id= "109207004", Source= "SNOMEDCT"},
 {RxCui= "61609", Name= "arbutamine", Type= "GN", Id= "d04216", Source= "MMSL"}}

getQuantity( rxcui )

Gets the quantity attribute for a specified RxNorm concept.

Input:

rxcui - the RxNorm identifier

Output:

The quantity attribute of the concept. This is the RXN_QUANTITY attribute from the RXNSAT file. This applies to some RxNorm concepts of term type = "SBD" or "SCD".

Example

# get the quantity of concept RxCUI=727339 "0.5 ML Sumatriptan 12 MG/ML Prefilled Syringe"

getQuantity( 727339 )

returns:

0.5 ML

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. The list of valid relationship attributes is contained in the getRelaTypes example.

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 = ""}}
Type = "PIN", {
{ Name = "cetirizine hydrochloride", Rxcui = "203150", Type = "PIN", 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. Valid RxNorm term types are list in the getTermTypes example.

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", "PIN", "SBD"} )

returns:

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

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", "doseformgroup_of",
"form_of", "has_dose_form", "has_form", "has_ingredient", "has_ingredients",
"has_part", "has_precise_ingredient", "has_quantified_form", "has_tradename", "has_doseformgroup",
"ingredient_of", "ingredients_of", "inverse_isa", "isa", "part_of", "precise_ingredient_of",
"quantified_form_of", "reformulated_to", "reformulation_of", "tradename_of" }

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 listed in the getTermTypes example.
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, type=SCD or type=BPCK)

Example

getRxConceptProperties( "58930")

returns:

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

getRxcuiStatus( rxcui )

Return the status and concept information for a given concept identifier. If the concept has been remapped, the returned information will represent the remapped concept(s).

Input:

rxcui - the RxNorm concept identifier

Output:

A concept status structure which contains:

Status of the concept. Possible values are:
- Active. The concept is in the current data set and has a non-obsolete term from the RxNorm vocabulary.
- Alien. The concept exists in the current data set, but contains only terms from vocabularies other than RxNorm.
- Remapped. The concept has been remapped to one or more concepts in the current data set.
- Retired. The concept no longer exists in the current data set, or contains only obsolete terms.
- Unknown. The concept identifier is invalid.
Last active release date. This is only available when the status of the concept is Remapped. The form of the release date is yymmddF, where yy=year, mm=numeric month, dd=day of month.
An array of minimal concept information. Data is only returned for Active and Remapped status.

Examples

getRxcuiStatus( 44 )

returns:

{ status="Active", date="", { {rxcui="44", name="Mesna", tty="IN"} } }

getRxcuiStatus( 105048 )

returns:

{ status="Remapped", date="090504F",
  { {rxcui="849839", name="Amantadine Hydrochloride 100 MG Oral Capsule", tty="SCD"},
    {rxcui="849394", name="Amantadine Hydrochloride 100 MG Oral Capsule[Symmetrel]", tty="SBD"} }
}

In the above example, the concept with RxCUI = 105048 was remapped to two concepts.

getRxcuiStatus( 884271 )

returns:

{ status="Retired", date="", {} }

getRxNormVersion( )

Get the version of the RxNorm data set.

Input:

None

Output:

The version of the RxNorm data set. The date of the monthly release will be returned along (if applicable) the date of the last weekly update.

Example

getRxNormVersion()

returns  "07-Jan-2013;23-Jan-2013"

getSourceTypes()

Get the vocabulary abbreviated source names in the RxNorm data set.

Input:

None

Output:

An array of vocabulary source abbreviated names. See getProprietaryInfomation for use of these names.

Example

getSourceTypes()

returns

{"GS", "MDDB", "MMSL", "MMX", "MSH", "MTHFDA", "MTHSPL", "NDDF", "NDFRT", "RXNORM", "SNOMEDCT", "VANDF"}

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", "Zirtek", "Zaptec"}

getSplSetId( rxcui )

Gets the Structured Product Label set identifiers for a specified RxNorm concept.

Input:

rxcui - the RxNorm identifier

Output:

The structured product label set identifiers for the concept. This is the SPL_SET_ID attribute from the RXNSAT file.

Example

getSplSetId( 757702 )

returns:

{ "34B56F73-BEA4-4265-8B2A-C57520CF8E70" }

getStrength( rxcui )

Gets the strength attribute for a specified RxNorm concept.

Input:

rxcui - the RxNorm identifier

Output:

The strength of the concept. This is the RXN_STRENGTH attribute from the RXNSAT file. This applies to RxNorm concepts with term type = "SBDC" or "SCDC".

Example

# get the strength of concept rxcui=315935 "Fluconazole 100 MG"

getStrength( 315935 )

returns:

100 MG

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", "DFG", "GPCK", "IN", "MIN", "PIN", "SBD", "SBDC", "SBDF", "SBDG", "SCD", "SCDC", "SCDF", "SCDG"}

getUNII( rxcui )

Gets the FDA Unique Ingredient Identifier (UNII) code for a specified RxNorm concept.

Input:

rxcui - the RxNorm identifier

Output:

The FDA Unique Ingredient Identifier Code for the concept. This is the UNII_CODE attribute from the RXNSAT file.

Example

getUNII( 235784 )

returns:

7D8YVA497F

RxNorm Web API Client

An interactive web client which calls the RxNorm 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/rxnav_api_demo.pl

This will bring up the application shown below:

RxNorm 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, Arg2, Arg3 and Arg4 positions on the screen. In the example below, the function getConceptProperties is selected and 161 is entered for Arg1 (the RxCUI). The answer is shown in the blue box below the form.

RxNorm API Client - getConceptProperties

RxNorm API Client - getConceptProperties

Recent API changes

Release Date: February 21, 2012
Modules affected: getRxcuiStatus
Description of changes:
Function getRxcuiStatus has been added to the API.

Release Date: December 14, 2011
Modules affected: getAllConceptsByTTY, getAllProperties, getPropNames, getPropCategories, findRxcuiById, getIdTypes
Description of changes:
Functions getAllConceptsByTTY, getAllProperties, getPropNames and getPropCategories have been added to the API. New ID types NDA (New Drug Application) and ANDA (Abbreviated New Drug Application) were added to the list of searchable IDs for findRxcuiById.

Release Date: October 13, 2011
Modules affected: getRelatedByType, getAllRelatedInfo
Description of changes:
The API has been changed to return data for the new TTYs introduced in the October release - SBDG, SCDG, and DFG.

Release Date: August 29, 2011
Modules affected: approxMatch, getProprietaryInformation
Description of changes:
Initial release of approxMatch, a function to find concepts which approximately match a given string. The getProprietaryInformation function has been modified to be able to search on an RxAUI.

Release Date: May 2, 2011
Modules affected: getRelatedByType, getAllRelatedInfo
Description of changes:
For getRelatedByType and getAllRelatedInfo, the determination of the related concepts has changed when starting or ending with an ingredient (PIN) concept. See the default path table for more details. This plus a query change was made to speed up the response time.

Release Date: January 31, 2011
Modules affected: getProprietaryInformation, getSourceTypes, getRelatedByType, getAllRelatedInfo
Description of changes:
The proxyTicket parameter should be generated from the UMLS Terminology Services (UTS) authorization server for use in getProprietaryInformation.
A new function called getSourceTypes was added to return the valid source abbreviations which can be used in getProprietaryInformation.

For getRelatedByType and getAllRelatedInfo, the determination of the related concepts has changed when starting or ending with a precise ingredient (PIN) concept. See the default path table for more details.

Release Date: December 1, 2010
Modules affected: findRemapped
Description of change:
A new function findRemapped was added.

Release Date: September 7, 2010
Modules affected: getRelatedByType, getAllRelatedInfo, getRelatedByRelationship, getTermTypes, getRelaTypes
Description of change:
The September 2010 release of RxNorm data introduced the MIN (multiple ingredient) term type, and includes new relationships - "part_of" and "has_part" between MIN and PIN/IN term types, and "ingredients_of" and "has_ingredients" between MIN and SCD term types.

Release Date: August 10, 2010
Modules affected: getSplSetId
Description of change:
New function to get the Structured Product Label set identifiers for a given concept.

Release Date: August 6, 2010
Modules affected: findRxcuiById
Description of change:
Allowing search on HIC_SEQN.

Release Date: July 22, 2010
Modules affected: findRxcuiByString
Description of change:
Addition of a fourth parameter - searchType. This allows users to specify whether an exact match or normalized string search is to be executed. Previously, exact match searching was done.

Release Date: June 30, 2010
Modules affected:
Description of change:
Introduction of the RxNorm RESTful Web API. For details see the RxNorm RESTful Web API User's Guide.

Release Date: June 10, 2010
Modules affected: findRxcuiById
Description of change:
Allowing search on NUI and SPL_SET_ID.

Release Date: April 14, 2010
Modules affected: getUNII
Description of change:
New function added to user documentation and to the WSDL file.

Release Date: February 15, 2010
Modules affected: getStrength, getQuantity
Description of change:
New functions added to user documentation and to the WSDL file.

Release Date: October 7, 2009
Modules affected: getDisplayTerms
Description of change:
New function added to user documentation and to the WSDL file.

Release Date: August 17, 2009
Modules affected: findRxcuiById, getIdTypes
Description of change:
The GCN identifier has been replaced by GCN_SEQNO.

Release Date: July 8, 2009
Modules affected: getAllRelatedInfo, getRxConceptProperties, getRelatedByType, getTermTypes
Description of change:
The PIN (precise ingredient) term type was added starting with the July 2009 release of the RxNorm data set. RxNorm terms of this type previously had an IN term type. The PIN term type will be returned as part of the structure returned by getAllRelatedInfo. PIN is also now a valid input type for getRelatedByType.

Release Date: April 28, 2009
Modules affected: findRxcuiById, with idType = "NDC"
Description of change:
The change fixes a problem in the findRxcuiById function when used with the NDC identifier type. In certain cases RxCUIs were not returned when the NDC identifier was contained in more than one concept. This problem occurred regardless of the value of the allSourcesFlag parameter.

Release Date: March 23, 2009
Modules affected: getRelatedByType, getAllRelatedInfo
Description of change:
The change fixes a problem in the getRelatedByType and the getAllRelatedInfo functions when the term type (TTY) associated with the RxCUI was a branded pack (BPCK). In certain cases the related ingredient (IN) and clinical drug component (SCDC) concepts were not returned.

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