This is how we came up with the app:

Chintan mentions:

It was one  of those late spring days in NYC, we were coding our patient portal app for the New York eHealth Collaborative Challenge. They provided us with oh-so-SHIN-NY API, but it sent us raw CCDA files and we wanted to display patient friendly lab result names. So we coded up this API that was called by our Javascript client on the patient portal to display nicer lab names.

How is it different from the UMLS Terminology Services?

Our goal with Health Vocabulary REST API was to create a developer friendly API that abstracts-away a lot of UMLS specific notions to support rapid app development. The UTS provides a full-fledged web services based interface. Additionally, this API server can be hosted and managed locally.

Health Vocab API Info:

• Developed in Python/Django
• Open Source
• Core developer: Chintan Patel
• source code at: https://github.com/chintanop/health-vocabulary-rest-api

Current resources provided for consumption(i.e: you can query for):

• Concept Resource
• Terminology Code resource
• Terminology Relationship resource
• Terminology Mapping resource

Many other resources can be identified as per needs, and dataset we have at hand.

Install/Set up

1. Check out the code into your local.
2. Edit *settings.py( and update DATABASE settings to point to your local database.
3. Create corresponding database tables, python manage.py syncdb.
4. Load the MRCONSO.sql, MRREL.sql, MRSTY.sql (pronounced as Mr. Conso, Mr. Rel, Mr. Sty) into database from command line as follows:mysql -u<user> -p<password> <db_name> < MRCONSO.sql

   alter table MRCONSO add column id int auto_increment primary key;

   mysql -u<user> -p<password> <db_name> < MRREL.sql

   alter table MRREL add column id int auto_increment primary key;

   mysql -u<user> -p<password> <db_name> < MRSTY.sql

   alter table MRSTY add column id int auto_increment primary key;

5. Run the app, python manage.py runserver
6. For production environment, it is advised to host the app inside a WSGI container.

API operations

NOTE: The required field are marked as “bold” in the API parameters

1. GET /concepts

Search concepts by term and source terminology (SAB).

Parameters:

• term: Any source medical term, e.g. diabetes
• sabs: A comma separated list of source vocabularies to restrict the concepts. The full list of vocabulary abbreviations is available here.
• tty: Source term type to restrict the terms, e.g. PT for ‘designated preferred name’, MH for ‘main heading’. The full list of source term types is available here.
• sty – Semantic type to restrict the terms, e.g.T047 for ‘Disease or Syndrome’, T200 for ‘Clinical Drug’. The full list of semantic types is available here.
• partial: 1/0 (if partial=1 then term will be partial term matches will be returned. if partial =0 then all matches will be returned. default =0)

Returns: A list of concept objects

Example: http://havoc.appliedinformaticsinc.com/concepts?term=neoplasms&sabs=MSH&tty=MH&sty=T191&partial=0&demo=true

2. GET /concepts_bulk

Search concepts by terms in bulk and source terminology (SAB).

Parameters:

• terms: A comma separate list of terms
• sabs: A comma separated list of source vocabularies to restrict the concepts
• partial: 1/0 (if partial=1 then term will be partial term matches will be returned. if partial =0 then all matches will be returned. default =0) delimiter: delimiter which separates the terms, default is comma(,)

Returns: A list of concept objects

Example: http://havoc.appliedinformaticsinc.com/concepts_bulk?terms=neoplasms:diabetes&sabs=MSH&partial=0&delimiter=:&demo=true

3. GET /concepts/:cui

Get full details for a concept (specified by CUI).

Parameters:

cui: concept id

Returns A Concept object

Example: http://havoc.appliedinformaticsinc.com/concepts/C0027651?demo=true

4. GET /concepts/:cui/children

Get all children for a given concept. By default it will get all children based on UMLS (REL=CHD/RN) or the relationships can be restricted to a given vocabulary.

Parameters:

• cui: concept id
• sab: The source vocabs to restrict the child definition. Currently supported: MeSH and SNOMEDCT
• explode: 1/0 – if set to 1 then get all children recursively. Currently supported vocabularies: MeSH

Returns: A list of Concept objects

Example: http://havoc.appliedinformaticsinc.com/concepts/C0027651/children?sabs=MSH&explode=0&demo=true

5. GET /concepts/:cui/parents

Get all parents for a given concept. By default it will get all parents based on UMLS (REL=PAR/RB) or the relationships can be restricted to a given vocabulary.

Parameters:

• cui: concept id
• sab: The source vocabs to restrict the child definition. explode: 1/0 – if set to 1 then get all parents recursively. Currently supported vocabularies: MeSH

Returns: A list of Concept objects

Example: http://havoc.appliedinformaticsinc.com/concepts/C0027651/parents?sabs=MSH&explode=0&demo=true

6. GET /concepts_bulk/:cui,:cui,:cui/parents

Get all parents for a given list of concepts. By default it will get all parents based on UMLS (REL=PAR,RB) or the relationships can be restricted to a given vocabulary.

Parameters:

• cui list:: list of comma seperated cuis
• sab: The source vocabs to restrict the child definition.
• explode: 1/0 – if set to 1 then get all parents recursively. Currently supported vocabularies: MeSH

Returns: A list of Concept objects for each provided CUI

Example: http://havoc.appliedinformaticsinc.com/concepts_bulk/C0027651,%20C0006826/parents?demo=true

7. GET /concepts/:cui/synonyms

Get all synonym strings for a given Concept (:cui). Optionally, restrict the synonyms to a list of vocabularies.

Parameters:

• cui: concept id
• sabs: A List of source vocabularies

Returns: A list of strings, e.g. [“diabetes”, “diabetes type 2”,…]

Example: http://havoc.appliedinformaticsinc.com/concepts/C0027651/synonyms?demo=true

8. GET /rel/:sab/:code/:rel_type

Get all target codes related to a given vocab/code pair by relationship rel_type.

Parameters:

• sab: The vocabulary abbreviation or short name, e.g. SNOMEDCT, LOINC.
• code: The value of code to be looked up, e.g. 111-ABC degree: Control the number of hops in the graph
• rel_type: The relationship to be looked up, e.g. is_diagnosed_by, causative_agent_of. The full list of relationship attribute types is available here.

Returns: A list of Concept objects

Example: http://havoc.appliedinformaticsinc.com/rel/MSH/D009369/associated_with/?demo=true

**

Code API

** The following set of APIs work with vocabulary codes.

9. GET /codes

Search all codes.

Parameters:

• code: Search for a given code
• sabs: Restrict the search a given set of vocabularies

Returns: A list of Code objects.

Example: http://havoc.appliedinformaticsinc.com/codes?code=D009369&sab=MSH&demo=true

10. GET /codes/:code/sabs/:sab

Get details about a code.

Parameters:

• code: Get details about a code
• sab: In a given source vocabulary

Returns: A Code object.

Example: http://havoc.appliedinformaticsinc.com/codes/D009369/sab/MSH/?demo=true

11. GET /codes/:code1/sabs/:sab1/mapping/:sab2

Get semantically equivalent mappings for code1 in sab1 in sab2

Parameters:

• code1: Get details about a code
• sab1: In a given source vocabulary
• sab2: The target vocabulary to find a code in sab2

Returns: A list of Code objects (one or more mappings).

Example: http://havoc.appliedinformaticsinc.com/map/MSH/D009369/WHO/?demo=true

More resources:

• http://blog.appliedinformaticsinc.com/getting-started-with-metamorphosys-the-umls-installation-tool/
• http://blog.appliedinformaticsinc.com/umls-metathesaurs-tool-mysql-load-scripts-database-browse/
• http://blog.appliedinformaticsinc.com/umls-metathesaurs-loading-umls-schema-data-to-mysql/
• http://blog.appliedinformaticsinc.com/rest-api-over-umls-terminologies/