MetaMap: http://metamap.nlm.nih.gov link to UMLS Knowledge Source Specialist Lexicon MTI : ../MTI/index.shtml SemRep: http://semrep.nlm.nih.gov Indexing Inititiave: Web API Home page logo
Contact Us | Copyright | Privacy | Accessibility | Freedom of Information Act   
  Indexing Initiative > Web API
This Java-based API to the Indexing Initiative Scheduler facility was created to provide users with the ability to programmatically submit jobs to the Scheduler Batch and Interactive facilities instead of using the web-based interface.

Three programs are accessible via the Web API:
MetaMap, the NLM Medical Text Indexer (MTI), and SemRep. The functionality in these programs includes: automatic indexing of MEDLINE citations, concept-based query expansion, analysis of complex Metathesaurus strings, accurate identification of the terminology and relationships in anatomical documents, and the extraction of chemical binding relations from biomedical text.

Whenever you see Information Mark Symbol in the text below, it means that additional information is available by selecting the symbol.

Contents:

Web API Download With Source Button

Third Party and Associated Licenses Used:

For specifics on the licensing and copyright information on each of these packages, please visit their respective link. Notices/Attributions will also be found in the source code when and where required.

Prerequisites and Notices:


Download:

Change History
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 Notes Sizes
Web API Download With Source Button 2.1 Libraries, Examples, Documentation, and all Source Code 1.3MB

Installation:

To install the Web API, do the following:
  1. Make a top level directory to store the Web API program.

  2. Go to the Web API page from the Indexing Initiative homepage.

  3. Download the latest version of the Web API into the directory created in #1.

  4. Change directory to the directory created in #1

  5. Extract the jar files from the downloaded jar file - SKR_Web_API_V2_1.jar.
    • On Windows:Run winzip, pkzip, or zip on the downloaded file.

    • On Unix:Run the java jar program on the jar file: java sun.tools.jar.Main xf SKR_Web_API_V2_1.jar

  6. This will create a directory called "Web_API_V2_1" in the directory you created in #1 and fill it with all of the program files needed.

  7. Now, change to this new directory: cd Web_API_V2_1

  8. You are now ready to run. Look at the example programs in the "examples" subdirectory for ideas on what to do.

Overview of What Happens:

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.


Example Programs:

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.

GenericBatch.java 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.
 
GenericBatchNew.java 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:
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
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.
 
MMInteractive.java This example shows how to setup a basic Interactive MetaMap request. This runs the latest version of MetaMap with 1011 (2010AB) version of the UMLS Metathesaurus ("KSOURCE", "1011"), 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.
 
SRInteractive.java 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.

Sample Batch Commands:


How to Compile and Run:


Programming Notes:

Required Fields
General Description Name Type
Email Address Email_Address String
File to Upload UpLoad_File String


Optional Fields
General Description Name Type
Silent on Errors Question Mark Symbol: Help about Silent on Errors ESilent Boolean
Single Line Delimited Input   Question Mark Symbol: Help about Single Line Delimited Input SingLine Boolean
Single Line Delimited Input w/ID Question Mark Symbol: Help about Single Line Delimited Input w/ ID SingLinePMID Boolean
Requested Run Priority Level Question Mark Symbol: Help about Requested Run Priority Levels RPriority String
No Completion Email Question Mark Symbol: Help about the No Completion Email option SilentEmail Boolean

Presentation from NLM APIs Webinar on Web API:

The following presentation describing the MetaMap/MTI Web API (Web API) was delivered as part of the April 10, 2012 NLM APIs webinar. For more information on other NLM APIs and/or to see the full recorded webinar, please visit the NLM API page.

Presentation from NLM APIs Webinar on Web API - PowerPoint (1.2 mb) Presentation from NLM APIs Webinar on Web API, April 2012
Presentation from NLM APIs Webinar on Web API - PDF (12.8 mb) Presentation from NLM APIs Webinar on Web API, April 2012 (PDF version, no slide animations)

Copyright, Privacy, Accessibility, Contact Us
National Library of Medicine, National Institutes of Health,
Health & Human Services, Freedom of Information Act
link to http://www.usa.gov/ - image is USA.gov logo Last Modified: February 07, 2014