umls-api

• promise-based api to interact with the UMLS terminology service
• umls authentication

NOTE

• after 8 hours a "ETIMEDOUT" error is thrown - requiring need to get

end point support

• search by string (search)
• search by CUI code (cui)

installation

npm install umls-api --save

run tests

npm run test

• or -

yarn test

Example: cui

• you want to lookup CUI=C0009044

node code

const { UmlsApi } = require('umls-api')
const credentialsApiKey = {apikey:'<your-umls-apikey>'}
const credentialsUsernamePassword = {username:'<user>',password:'<pw>'}
// you can use either credentialsApiKey or credentialsUsernamePassword
new UmlsApi(credentialsApiKey)
    .authenticate()
    .then((umls) => 
        umls.cui('C0009044')
        .then((res) => console.log(JSON.stringify(res.data))))

output

{
  "pageSize": 25,
  "pageNumber": 1,
  "pageCount": 1,
  "result": {
    "classType": "Concept",
    "ui": "C0009044",
    "suppressible": false,
    "dateAdded": "09-30-1990",
    "majorRevisionDate": "03-16-2016",
    "status": "R",
    "semanticTypes": [
      {
        "name": "Injury or Poisoning",
        "uri": "https://uts-ws.nlm.nih.gov/rest/semantic-network/2018AB/TUI/T037"
      }
    ],
    "atomCount": 65,
    "attributeCount": 0,
    "cvMemberCount": 0,
    "atoms": "https://uts-ws.nlm.nih.gov/rest/content/2018AB/CUI/C0009044/atoms",
    "definitions": "https://uts-ws.nlm.nih.gov/rest/content/2018AB/CUI/C0009044/definitions",
    "relations": "https://uts-ws.nlm.nih.gov/rest/content/2018AB/CUI/C0009044/relations",
    "defaultPreferredAtom": "https://uts-ws.nlm.nih.gov/rest/content/2018AB/CUI/C0009044/atoms/preferred",
    "relationCount": 5,
    "name": "Closed fracture of carpal bone"
  }
}

Example: search

node code

const { UmlsApi } = require('umls-api')
const credentialsApiKey = {apikey:'<your-umls-apikey>'}
const credentialsUsernamePassword = {username:'<user>',password:'<pw>'}
// you can use either credentialsApiKey or credentialsUsernamePassword
new UmlsApi(credentialsApiKey)
    .authenticate()
    .then((umls) => 
        umls.search({string:'fracture of carpal bone'})
        .then((res) => console.log(JSON.stringify(res.data))))

output

{
  "pageSize": 25,
  "pageNumber": 1,
  "result": {
    "classType": "searchResults",
    "results": [
      {
        "ui": "C0009044",
        "rootSource": "SNOMEDCT_US",
        "uri": "https://uts-ws.nlm.nih.gov/rest/content/2018AB/CUI/C0009044",
        "name": "Closed fracture of carpal bone"
      },
      {
        "ui": "C0016644",
        "rootSource": "MTH",
        "uri": "https://uts-ws.nlm.nih.gov/rest/content/2018AB/CUI/C0016644",
        "name": "Fracture of carpal bone"
      },
      {
        "ui": "C0159765",
        "rootSource": "MTH",
        "uri": "https://uts-ws.nlm.nih.gov/rest/content/2018AB/CUI/C0159765",
        "name": "Open fracture of carpal bone, unspecified"
      },
      {
        "ui": "C0272654",
        "rootSource": "SNOMEDCT_US",
        "uri": "https://uts-ws.nlm.nih.gov/rest/content/2018AB/CUI/C0272654",
        "name": "Fracture of scaphoid bone of wrist"
      },
      {
        "ui": "C0272656",
        "rootSource": "SNOMEDCT_US",
        "uri": "https://uts-ws.nlm.nih.gov/rest/content/2018AB/CUI/C0272656",
        "name": "Fracture of triquetral bone of wrist"
      },
      {
        "ui": "C0282014",
        "rootSource": "SNOMEDCT_US",
        "uri": "https://uts-ws.nlm.nih.gov/rest/content/2018AB/CUI/C0282014",
        "name": "Fracture of trapezium of wrist"
      },
      {
        "ui": "C0559421",
        "rootSource": "SNOMEDCT_US",
        "uri": "https://uts-ws.nlm.nih.gov/rest/content/2018AB/CUI/C0559421",
        "name": "Fracture of lunate bone of wrist"
      },
      {
        "ui": "C0559422",
        "rootSource": "SNOMEDCT_US",
        "uri": "https://uts-ws.nlm.nih.gov/rest/content/2018AB/CUI/C0559422",
        "name": "Fracture of pisiform bone of wrist"
      },
      {
        "ui": "C0559424",
        "rootSource": "SNOMEDCT_US",
        "uri": "https://uts-ws.nlm.nih.gov/rest/content/2018AB/CUI/C0559424",
        "name": "Fracture of trapezoidal bone of wrist"
      },
      {
        "ui": "C0559425",
        "rootSource": "SNOMEDCT_US",
        "uri": "https://uts-ws.nlm.nih.gov/rest/content/2018AB/CUI/C0559425",
        "name": "Fracture of hamate bone of wrist"
      },
      {
        "ui": "C0559426",
        "rootSource": "SNOMEDCT_US",
        "uri": "https://uts-ws.nlm.nih.gov/rest/content/2018AB/CUI/C0559426",
        "name": "Fracture of capitate bone of wrist"
      },
      {
        "ui": "C0840635",
        "rootSource": "ICD10AM",
        "uri": "https://uts-ws.nlm.nih.gov/rest/content/2018AB/CUI/C0840635",
        "name": "Fracture of carpal bone, unspecified"
      },
      {
        "ui": "C2213932",
        "rootSource": "MEDCIN",
        "uri": "https://uts-ws.nlm.nih.gov/rest/content/2018AB/CUI/C2213932",
        "name": "malunion of fracture of carpal bone"
      },
      {
        "ui": "C2214345",
        "rootSource": "MEDCIN",
        "uri": "https://uts-ws.nlm.nih.gov/rest/content/2018AB/CUI/C2214345",
        "name": "nonunion of fracture of carpal bone"
      },
      {
        "ui": "C3669570",
        "rootSource": "SNOMEDCT_VET",
        "uri": "https://uts-ws.nlm.nih.gov/rest/content/2018AB/CUI/C3669570",
        "name": "Fracture of fourth carpal bone of equine limb"
      },
      {
        "ui": "C3669572",
        "rootSource": "SNOMEDCT_VET",
        "uri": "https://uts-ws.nlm.nih.gov/rest/content/2018AB/CUI/C3669572",
        "name": "Fracture of radial carpal bone of equine limb"
      },
      {
        "ui": "C3669573",
        "rootSource": "SNOMEDCT_VET",
        "uri": "https://uts-ws.nlm.nih.gov/rest/content/2018AB/CUI/C3669573",
        "name": "Fracture of intermediate carpal bone of equine limb"
      },
      {
        "ui": "C3669927",
        "rootSource": "SNOMEDCT_VET",
        "uri": "https://uts-ws.nlm.nih.gov/rest/content/2018AB/CUI/C3669927",
        "name": "Fracture of accessory carpal bone of equine limb"
      },
      {
        "ui": "C3669936",
        "rootSource": "SNOMEDCT_VET",
        "uri": "https://uts-ws.nlm.nih.gov/rest/content/2018AB/CUI/C3669936",
        "name": "Fracture of ulnar carpal bone of equine limb"
      },
      {
        "ui": "C3670076",
        "rootSource": "SNOMEDCT_VET",
        "uri": "https://uts-ws.nlm.nih.gov/rest/content/2018AB/CUI/C3670076",
        "name": "Fracture of third carpal bone"
      },
      {
        "ui": "C0272662",
        "rootSource": "SNOMEDCT_US",
        "uri": "https://uts-ws.nlm.nih.gov/rest/content/2018AB/CUI/C0272662",
        "name": "Quervain's fracture"
      },
      {
        "ui": "C0434897",
        "rootSource": "SNOMEDCT_US",
        "uri": "https://uts-ws.nlm.nih.gov/rest/content/2018AB/CUI/C0434897",
        "name": "Fracture dislocation of lunate"
      },
      {
        "ui": "C0478305",
        "rootSource": "ICD10",
        "uri": "https://uts-ws.nlm.nih.gov/rest/content/2018AB/CUI/C0478305",
        "name": "Fracture of other carpal bone(s)"
      },
      {
        "ui": "C2012741",
        "rootSource": "MEDCIN",
        "uri": "https://uts-ws.nlm.nih.gov/rest/content/2018AB/CUI/C2012741",
        "name": "open treatment of fracture of carpal bone"
      },
      {
        "ui": "C2164887",
        "rootSource": "MEDCIN",
        "uri": "https://uts-ws.nlm.nih.gov/rest/content/2018AB/CUI/C2164887",
        "name": "delayed union of fracture of carpal bone"
      }
    ]
  }
}

resources

• axios
• os
• parse5 for parsing html
• UMLS REST API / UTS endpoints
• UMLS API: search
• umls authentication
• umls glossary
• umls Term Types

terminology

• Unified Medical Language System (UMLS)
• UMLS Terminology Services (UTS)
• CUI : Concept Identifier

steps to make things work

1. get Ticket-Granting-Ticket (TGT) - btw, your TGT will be valid for 8 hours.
2. get a service ticket (ST) by POST-ing to https://utslogin.nlm.nih.gov/cas/v1/api-key/{api-key} with header [Content-Type=application/x-www-form-urlencoded] and paramters [service=http://umlsks.nlm.nih.gov] this will return a ST like ST-380814-VBmBEOdgwj7cgLFinb9b-cas
3. now use the ST in requests to UMLS (e.g. https://uts-ws.nlm.nih.gov/rest/search/current?string=diabetes&ticket={yourServiceTicket})
4. for every new request go to step 2 and repeat. Some time over the next 8 hours the TGT will expire (not sure how you are informed) so you will need to acquire a new TGT.