NLM logo

We welcome your feedback on our customer service form. Please use "UMLS REST API feedback" in your subject line.

Check out the Postman sample collection to help you get started using the UMLS REST API.

API Terms of Service

Searching the UMLS

URIs | Query Parameters | Sample Output | Paging through results

URIs with /search support the following use cases:

Note that ‘current’ in the URI can always be used to search against the latest UMLS publication.
You may use any valid UMLS release back to 2008AA in your URI if you would like to search against a particular version of the UMLS.

URIs

The base URI is https://uts-ws.nlm.nih.gov/rest

Sample URI Description Returned JSON Object classType
/search/current?string=fracture of carpal bone Retrieves CUIs for a search term - python example searchResults
/search/current?string=fracture of carpal bone&searchType=exact Uses ‘exact’ searching searchResults
/search/current?string=fracture of carpal bone&sabs=SNOMEDCT_US&returnIdType=code Returns SNOMEDCT concepts associated with a search term searchResults
/search/current?string=9468002&inputType=sourceUi&searchType=exact&sabs=SNOMEDCT_US Returns UMLS CUIs associated with a SNOMEDCT_US concept - python example searchResults
/search/current?string=C0009044&sabs=SNOMEDCT_US&returnIdType=code Returns SNOMED CT concepts associated with a UMLS CUI - python example searchResults

Query Parameters

Parameter name Required? Y/N Description Valid Values Default value Usage Note
apiKey Y An API key is required for each call to the API. Visit your UTS profile to obtain your API key. n/a n/a n/a
string Y A human readable term, such as ‘gestational diabetes’, or a code from a source vocabulary, such as 11687002 from SNOMEDCT_US. Any term or code in the UMLS. n/a n/a
inputType N Specifies the data type you are using as your search parameter. ‘atom’, ‘code’,‘sourceConcept’,‘sourceDescriptor’,‘sourceUi’,‘tty’ ‘atom’ Use ‘sourceUi’ if you aren’t sure if the identifier you’re providing is a code, source concept, or source descriptor. Using ‘tty’ is for advanced use cases and will extract codes from a specified vocabulary according to term type.
includeObsolete N Return content that is a result of matches on obsolete terms. true or false false n/a
includeSuppressible N Return content that is a result of matches on suppressible terms. true or false false n/a
returnIdType N Specifies the type of identifier you wish to retrieve. ‘aui’,‘concept’,‘code’,‘sourceConcept’,‘sourceDescriptor’, ‘sourceUi’ ‘concept’ Use ‘code’,‘sourceConcept’, ‘sourceDescriptor’, or ‘sourceUi’ if you prefer source-asserted identifiers rather than CUIs in your search results.
sabs N Comma-separated list of source vocabularies to include in your search Any root source abbreviation in the UMLS. See the “Abbreviation” column for a list of UMLS source vocabulary abbreviations. All UMLS source vocabularies Use a comma between each source abbreviation to specify more than one.
searchType N Type of search you wish to use. ‘exact’,‘words’,‘leftTruncation’, ‘rightTruncation’, ‘normalizedString’, ‘normalizedWords’ ‘words’ Use ‘exact’ when using inputType = ‘code’, ‘sourceConcept’, ‘sourceDescriptor’, or ‘sourceUi’. More information…
partialSearch N Return partial matches for your query. true or false false n/a
pageNumber N Whole number that specifies which page of results to fetch. 1,2,3, etc 1 n/a
pageSize N Whole number that specifies the number of results to include per page. 1,2,3, etc 25 n/a

Expected Behaviors for the searchType Parameter

Sample Output

The default search parameters will return CUIs and their names. If you ask for codes, sourceConcept, or sourceDescriptor as your returnIdType, you will get back source-asserted identifiers instead of CUIs.

Sample output for https://uts-ws.nlm.nih.gov/rest/search/current?string=fracture of carpal bone&apiKey=YOUR_APIKEY…

{

    "pageSize": 25,
    "pageNumber": 1,
    "result": 

{

    "classType": "searchResults",
    "results": 

[

{

    "ui": "C0009044",
    "rootSource": "SNOMEDCT_US",
    "uri": "https://uts-ws.nlm.nih.gov/rest/content/2015AA/CUI/C0009044",
    "name": "Closed fracture carpal bone"

},
{

    "ui": "C0016644",
    "rootSource": "MTH",
    "uri": "https://uts-ws.nlm.nih.gov/rest/content/2015AA/CUI/C0016644",
    "name": "Fracture of carpal bone"

},
{

    "ui": "C0159765",
    "rootSource": "MTH",
    "uri": "https://uts-ws.nlm.nih.gov/rest/content/2015AA/CUI/C0159765",
    "name": "Open fracture of carpal bone, unspecified"

},
...
        ]
    }

}

Specifying returnIdType = ‘code’,‘sourceConcept’,or ‘sourceDescriptor’ will result in output as follows:

Sample output for https://uts-ws.nlm.nih.gov/rest/search/current?string=fracture of carpal bone&returnIdType=sourceConcept&apiKey=YOUR_APIKEY…

{

    "pageSize": 25,
    "pageNumber": 1,
    "result": 

{

    "classType": "searchResults",
    "results": 

[

{

    "ui": "9468002",
    "rootSource": "SNOMEDCT_US",
    "uri": "https://uts-ws.nlm.nih.gov/rest/content/2015AA/source/SNOMEDCT_US/9468002",
    "name": "Closed fracture carpal bone"

},
{

    "ui": "C34488",
    "rootSource": "NCI",
    "uri": "https://uts-ws.nlm.nih.gov/rest/content/2015AA/source/NCI/C34488",
    "name": "Closed Fracture of Carpal Bone"

},
{

    "ui": "34696",
    "rootSource": "MEDCIN",
    "uri": "https://uts-ws.nlm.nih.gov/rest/content/2015AA/source/MEDCIN/34696",
    "name": "closed fracture of carpal bone"

},
...
        ]
    }

}

Paging through results

Many times a search will return more than one page of results. Json data returned by the /search endpoint will tell you what page number you are on,
but the current implementation does not tell you how many total pages of results there are as a result of your search. So how do you know when you’ve reached the end of
your search results? On the /search endpoint, the end of your search results will always:

{
    "pageSize": 25, 
    "pageNumber": 2, //your final page number may be different.  
    "result": {
        "classType": "searchResults", 
        "results": [
            {
                "ui": "NONE", 
                "name": "NO RESULTS"
            }
        ]
    }
}

This structure will also be displayed if your original search returns null.