VSAC API Resources

VSAC API Resources
Official websites use .gov
.gov
website belongs to an official government
organization in the United States.
Secure .gov websites use HTTPS
lock
) or
means you’ve safely connected to
the .gov website. Share sensitive information only on official,
secure websites.
VSAC API Resources
UMLS License Requirement
The VSAC APIs require a UMLS account. If you do not have a UMLS account, you may apply for a
license
on the
UMLS Terminology Services (UTS)
website.
In order to avoid overloading our servers, NLM requires that users send no more than 20
requests per
second
per IP address. Requests that exceed this limit may not be serviced, and service will not be
restored until
the request rate falls beneath the limit. To limit the number of requests that you send to
the APIs,
NLM
recommends caching results for a 12-24 hour period. This policy is in place to ensure that
the
service
remains available and accessible to all users. If you have a specific use case that requires
you to
send a
large number of requests to one of our APIs, and thus exceed the request rate limit outlined
in this
policy,
please contact us. NLM staff will evaluate your request and determine if an exception may be
granted. We
invite you to develop computer and mobile applications using National Library of Medicine
(NLM)
resources.
We request that any application that makes use of NLM data include the following statement:
"This
product
uses publicly available data from the U.S. National Library of Medicine (NLM), National
Institutes of
Health, Department of Health and Human Services; NLM is not responsible for the product
and does
not
endorse or recommend this or any other product."
Developers may not use the
NLM name
and/or
logo in conjunction with their applications.
DISCLAIMER: It is not the intention of NLM to provide specific medical advice, but rather to
provide
users
with information to better understand their health and their medications. NLM urges you to
consult
with a
qualified physician for medical advice.
FHIR
Terminology Service for VSAC Resources
The
FHIR
Terminology
Service for VSAC Resources
is a RESTful API service for accessing the VSAC value sets
and
supported
code
systems.
The FHIR Terminology Service for VSAC Resources authentication service requires a free
UMLS account
Use basic authentication with your UMLS API Key.
For example, if you are using a RESTful client platform such as Postman, choose:
Authorization Type = Basic Auth
username = ‘apikey’ or leave it blank
password = user’s actual UMLS API Key
For software developers, here is a
Java example
of
embedding
VSAC FHIR
API call within a program.
You can find your API Key in the My Profile area of the
UMLS
Terminology
Services (UTS)
after signing in. If the API Key field in your UTS profile is
blank,
click
Edit
Profile, select the Generate New API Key checkbox, then scroll down and click Save
Profile. Your
new
API Key
is now available for use. An API Key remains active as long as the associated UTS
account is
active.
Base
URI,
Capability Statement, Sample Queries
VSAC SVS API
The VSAC SVS API is based on the
IHE
SVS
Technical Framework, section 2.2.21 Sharing Value Set Integration Profile (SVS)
, and the
IHE SVS XML
Schema
Content (SVS API) URL
Two Available VSAC SVS API Content Requests
RetrieveValueSet
Use this request to retrieve only the value set concept list.
This request does not retrieve value set metadata content.
RetrieveMultipleValueSets
Use this request to retrieve value set metadata content as
well as the value set concept list.
Utility API URL
Authentication URL: https://vsac.nlm.nih.gov/vsac/ws (Deprecated and discontinued by
November
2023.
This URL
was for use with the TGT/STS authentication method.)
The VSAC SVS API authentication service requires a free
UMLS
account
Use basic authentication with your UMLS API Key.
For example, if you are using a platform such as Postman, choose:
Authorization Type = Basic Auth
username = ‘apikey’ or leave it blank
password = user’s actual UMLS API Key
For software developers, here is a
Java example
of
embedding a
VSAC SVS
API call within a program.
You can find your API Key in the My Profile area of the
UMLS
Terminology
Services (UTS)
after signing in. If the API Key field in your UTS profile is
blank,
click
Edit
Profile, select the Generate New API Key checkbox, then scroll down and click Save
Profile.
Your
new
API Key
is now available for use. An API Key remains active as long as the associated UTS
account is
active.
NOTE:
The Ticket Granting Ticket authentication for the VSAC SVS API has
been
deprecated. The
VSAC SVS API authentication method will switch exclusively to the API key authentication
method
by
the end
of November 2023. If you have a need to use this deprecated TGT/ST authentication method
between
now
and the
end of November 2023, see
Ticket-Granting
Ticket and
Service Ticket Documentation
and remember to append
"&ticket={ST}" to each of your VSAC SVS API calls.
Endpoints to search and retrieve VSAC content
Use basic authentication with your UMLS API Key.
Basic
URL    https://vsac.nlm.nih.gov/vsac/svs
Request Method
Path
Click to
view use
cases, sample calls and output
Description
Related Utility Calls
Click
to
view
use
cases, sample calls and output
GET
/RetrieveMultipleValueSets?id={oid}
Retrieve Most Recent Value Set Expansions:
includes
value
set
metadata
and concept list.
GET
/RetrieveValueSet?id={oid}
Retrieve Most Recent Value Set Expansions:
includes
only
value
set
concept list, no metadata.
GET
/RetrieveMultipleValueSets?id={oid}&release={releaseName}
Retrieve Value Set Expansions Published by a Program
Release
GET
/RetrieveMultipleValueSets?id={oid}&version={version}
Retrieve Value Set Expansion for a Specified Expansion
Version
GET
/RetrieveMultipleValueSets?id={oid}&profile={profileName}
Retrieve Value Set Expansion Calculated with Expansion
Profile:
Use the
utility call
profile
to retrieve a specified program's (example: "CMS
eCQM
and
Hybrid
Measure") latest expansion profile.
profile
GET
/RetrieveMultipleValueSets?id={oid}&profile={profileName}&includeDraft=yes
Retrieve Value Set Expansion of a Draft Value Set
Definition:
Use the
includeDraft parameter to retrieve a temporary expansion of draft
value
set
content.
Only VSAC authors and stewards, who are members of at least one VSAC
author
or
steward
group, have permissions to retrieve any draft content.
profile
GET
/RetrieveMultipleValueSets?tagName={tagName}&tagValue={tagValue}
Retrieve Expansions for All Value Sets Specified by a CMS
eMeasure
ID,
or
eMeasure Identifier, or NQF Number
GET
/RetrieveMultipleValueSets?id={oid}&effectiveDate={yyyymmdd}
Retrieve a Value Set Expansion Published on or before a
Specific
Date
GET
/RetrieveMultipleValueSets?id={oid}&effectiveDate={yyyymmdd}&programType=eCQM
Retrieve a Value Set Expansion Published on or before a
Specific
Date
in the most recent eCQM program release.
Parameter
Click to view use
cases,
sample
calls
and
output
Description
Use Case
effectiveDate
A date on or before which a published value set expansion is published and
available
in the
VSAC
public repository.
Retrieve a Value Set Expansion Published on or before a Specific
Date
id
Value set object unique identifier (OID).
includeDraft
Allows retrieval of a non-published draft value set definition. Value is
'yes'
or
'no'.
Retrieve Value Set Expansion of a Draft Value Set
Definition
latest profile
A specified program's latest expansion profile label that defines a
calculation
algorithm
that
applies predetermined code system versions and legacy codes. Example: 'eCQM
Update
2020-05-07'.
Retrieve Value Set Expansion Calculated with Expansion
Profile
profile
An expansion profile label that defines a calculation algorithm that applies
predetermined
code
system versions and legacy codes. Examples: 'eCQM Update 2019-05-10', or
'Most
Recent Code
System Versions in VSAC'.
Retrieve Value Set Expansion Calculated with Expansion
Profile
program
"Program" is the word VSAC applies to the administrative organization and/or
application
that
sponsors, authors and stewards a published release of value sets that
together
serve
purpose.
A program has a pre-arranged agreement with VSAC to publish their value sets
as
group.
VSAC Utility API Calls: 'programs' and 'latest profile' for
program:
Retrieve all release names and releaseDates for a given program name
Retrieve all published program releases (release names) for a given
value
set OID
and
program name
Return the value of the most recently available expansion profile to
be
used
by the
specified program in an upcoming VSAC program release of that
program's
value set
content. Value of latest profile is subject to change according to
the
goals
of the
program it represents
programs
Retrieve all program name values for programs supported by VSAC.
VSAC Utility API Calls: 'programs' and 'latest profile' for
program:
Retrieve available values for programs that will enable you to then
retrieve
release
name values for a program of interest.
programType
The name of a program that contains the requested OID. Available value: eCQM
Retrieve a Value Set Expansion Published on or before a Specific
Date:
by a
specified program.
release
Name of a program release. A program release contains multiple pre-selected
value
sets
designated by the program's release manager.
Retrieve Value Set Expansions Published by a Program
Release
tagName
A tag for a collection of value sets, for example: 'CMS eMeasure ID'. Must
be
used
together
with
'tagValue'.
Retrieve Expansions for All Value Sets Specified by a CMS eMeasure
ID,
or
eMeasure
Identifier, or NQF Number
tagNames
Retrieves all supported tagNames.
Retrieve Expansions for All Value Sets Specified by a CMS eMeasure
ID,
or
eMeasure
Identifier, or NQF Number
tagValue
The value of a member within a collection (tagName) of value sets. For
example,
'CMS68v9' is
one
of the valid values (tagValue) within the tagName CMS eMeasure ID.
Retrieve Expansions for All Value Sets Specified by a CMS eMeasure
ID,
or
eMeasure
Identifier, or NQF Number
tagValues
Retrieves all supported tagValues.
Retrieve Expansions for All Value Sets Specified by a CMS eMeasure
ID,
or
eMeasure
Identifier, or NQF Number
version
A release version label that uniquely identifies a specific value set
expansion.
For
example:
'eCQM Update 2017-05-05' or '20170505'.
Retrieve Value Set Expansion for a Specified Expansion
Version
All the value set transactions described in this document are represented by a RESTful
URL
and
one or
more
request parameters. The HTTP request uses the GET method for RetrieveValueSet and
RetrieveMultipleValueSets.
Encode each parameter as an HTTP Get parameter. The Content-Type field of the HTTP
header
shall
be
'text/xml'. The HTTP request returns an error code if the request parameters are
invalid, or
if
the
specified parameter combination is not supported. The request returns an HTTP status
code of
404, with
an
HTTP Warning header containing warning code 111, and warning text 'INV: Invalid search
parameters'. A
request with valid parameters and parameter combinations that finds no matching value
set is
not
an
error.
It will return an empty body with HTTP status code of 200.
Last Reviewed: September 7, 2023