The Unified Medical Language System® (UMLS®) is in the process of moving to a new authentication method (Fall 2020 Changes to UMLS Terminology Services (UTS)). The new login method required an update to our SKR Web API to allow for the UTS API Key instead of password. Please read through the section entitled "API Authentication" from the above link to identify your own UTS API Key which will need to be included in calls to our SKR Web API.
This necessitates you update to our latest version of the SKR Web API (Version 2.4) which is a complete replacement to previous releases. Please follow the directions for downloading and installing the SKR Web API.
For Web API access to our tools, you must have activated a UMLS Terminology Services (UTS) account. For more information please visit our Help about UTS accounts Web page. This account is free with only the minor requirement of filing a brief annual report on your use of the UMLS.
Users are also responsible for compliance with the UMLS Metathesaurus License Agreement which requires you to respect the copyrights of the constituent vocabularies.
The Web API package is protected under the MetaMap Terms and Conditions. Please review prior to downloading the Web API package.
|Version 1.3||Initial Public Release||September 6, 2007|
|Version 1.4||Minor Change Release (Updated defaults)||July 2, 2008|
|Version 1.5||Minor Change Release (Updated defaults)||July 30, 2009|
|Version 2.0||Updated for UTS Authentication and Simplified||June 15, 2011|
|Version 2.1||Updated to allow looping calls without re-authentication||June 1, 2012|
|Version 2.3||Moved from http to https and skr.nlm.nih.gov to ii.nlm.nih.gov||October 27, 2016|
|Version 2.4||Moved to UTS API authentication and new UTS Authentication Process||December 31, 2020|
There are six example programs included in the "examples" directory to illustrate how to incorporate the Web API into your application. Two of the examples (GenericBatch.java and GenericBatchNew.java) show how to access the Scheduler Batch facility. MMInteractive and SRInteractive.java examples show how to access Interactive MetaMap and Interactive SemRep respectively. The last two examples GenericBatchUser.java and MMInteractiveUser.java illustrate how to
specify the username and password within the program to eliminate the need for
prompting when running.
For a list of the available options, please select the appropriate program name: MetaMap and MTI.
Example program for submitting a new Generic Batch with Validation job
("GenericObject(true)" turns on validation) request to the Scheduler to
run. You will be prompted for your username and password and if they
are alright, the job is submitted to the Scheduler and the results are
returned in the String "results" below.
This example shows how to setup a basic Generic Batch with Validation job with a small file (sample.txt) with ASCII MEDLINE formatted citations as input data. You must set the Email_Address variable and use the UpLoad_File to specify the data to be processed. This example also shows the user setting the SilentEmail option which tells the Scheduler to NOT send email upon completing the job.
This example is set to run the MTI (Medical Text Indexer) program using the -opt1L_DCMS and -E options. You can also setup any environment variables that will be needed by the program by setting the Batch_Env field.
NOTE: The "-E" option/argument is very important and should be included with whatever program (MetaMap, SemRep, MTI) you decided to run! The reason is that this version of the Generic Batch does validation and the -E option tells the various programs to include a marker denoting when a successful result has been found.
Same as GenericBatch.java above, except you can enter any of the
options and the inputfile on the command line. The usage of the
program and available options are listed below:
NOTE: The "-E" option/argument is very important and should be included with whatever program you decided to run! The reason is that this version of the Generic Batch does validation and the -E option tells the various programs to include a marker denoting when a successful result has been found.
usage: GenericBatchNew [options] inputFilename allowed options: --email <address> : set email address. (required option) --command <name> : batch command: metamap, semrep, etc. (default: MTI -opt1_DCMS -E) --note <notes> : batch notes --silent : don't send email after job completes. --silent-errors : Silent on Errors --singleLineInput : Single Line Delimited Input --singleLinePMID : Single Line Delimited Input w/ID --priority : request a Run Priority Level: 0, 1, or 2
This example shows how to setup a basic Interactive MetaMap request.
This runs the latest version of MetaMap with 1516 (2015AB) version
of the UMLS Metathesaurus ("KSOURCE", "1516"), with "ignore_word_order" (-i)
and "all_derivational_variants" (D) set as arguments to MetaMap. The
default "Human Readable" output will be produced.
NOTE: The "-E" option/argument is NOT required for Interactive use.
This example shows how to setup a basic Interactive SemRep request.
This runs the latest version of SemRep with Full Fielded Output (-D).
NOTE: The "-E" option/argument is NOT required for Interactive use.
|GenericBatchUser.java This example is the same as "GenericBatchNew.java" above, except that the username and password are set in the program so that the user is not prompted when the program runs. Please Note: Although we understand the operational need for being able to specify the username and password within a program, you must also be aware of the security risks when using this setup. Please take care to secure the software you create using this option.|
|MMInteractiveUser.java This example is the same as "MMInteractive.java" above, except that the username and password are set in the program so that the user is not prompted when the program runs. Please Note: Although we understand the operational need for being able to specify the username and password within a program, you must also be aware of the security risks when using this setup. Please take care to secure the software you create using this option.|
The Web API has been designed to allow you to interact with our web-based Scheduler using our Batch and Interactive facilities. Interactive access is currently only available for the MetaMap and SemRep programs.
|File to Upload||UpLoad_File||String|
|Silent on Errors||ESilent||Boolean|
|Single Line Delimited Input||SingLine||Boolean|
|Single Line Delimited Input w/ID||SingLinePMID||Boolean|
|Requested Run Priority Level||RPriority||String|
|No Completion Email||SilentEmail||Boolean|
|(1.2 mb)||Presentation from NLM APIs Webinar on Web API, April 2012|
|(12.8 mb)||Presentation from NLM APIs Webinar on Web API, April 2012 (PDF version, no slide animations)|