FHIR CodeSystem Operations for HGVS

This API supports two FHIR CodeSystem operations for HGVS: the $validate-code operation for HGVS expression validation and the $lookup operation that currently only returns the NCBI's SPDI (Sequence Position Deletion Insertion) if available. We also have an interactive webpage that allows you to validate HGVS expressions online, which is powered by this API.

The $lookup operation is exclusively backed by the NCBI's Variation Service; the $validate-code operation is backed by the NCBI's Variation Service with the Mutalyzer Services as a fallback when NCBI's results are inconclusive. Please note that this is not a full terminology server and supports only a subset of the parameters for the two operations, which are detailed below.

Some NCBI API services limit number of requests per second (rps). Please be mindful and issue no more than 1 request per second to help ensure a smooth experience for you and for all the other users.

The $validate-code operation

Per the FHIR specification on CodeSystem Operations, the $validate-code operation is for "Code System based Validation", to validate that a coded value is in the code system.

Request URL formats - note that the "FHIR-VERSION" is a placeholder that currently can be "STU3" or "R4": The FHIR $validate-code operation parameters supported by this specific implementation:
Parameter Description
code The HGVS expression to be validated. Required.
url The HGVS CodeSystem url. Required for request "format-1" and must be "http://varnomen.hgvs.org"
_format The response format, currently can only be xml ("xml", "text/xml", "application/xml", or "application/fhir+xml") or json ("json", "application/json", "application/fhir+json"). This is optional and defaults to "application/fhir+json". You may also use the "Accept" header to specify the response format, but the _format parameter, when specified, has higher priority. Note that if you make a request from the browser (address bar), your browser may send "Accept" headers. Therefore, when _format is not specified, the response format may depend on what "Accept" headers are being sent by your browser.
Example $validate-code request & response

For request:

    https://clinicaltables.nlm.nih.gov/fhir/R4/CodeSystem/$validate-code?_format=application/fhir%2Bjson&url=http://varnomen.hgvs.org&code=NC_000001.10:g.12345T%3EA
The response is: 
    {
      "resourceType": "Parameters",
      "parameter": [
        {
            "name": "result",
            "valueBoolean": true
        }
      ]
    }

The $lookup operation

Per FHIR specification on CodeSystem Operations, the $lookup operation is for "Concept Look Up & Decomposition". Given a code/system, or a Coding, get additional details about the concept, including definition, status, designations, and properties. For this specific implementation, the lookup result provides only NCBI's SPDI if available.

Request URL format - note that the "FHIR-VERSION" is a placeholder that currently can be "STU3" or "R4": The FHIR $lookup operation parameters supported by this specific implementation:
Parameter Description
code The HGVS expression to be looked up. Required.
system The HGVS CodeSystem url. Required and must be "http://varnomen.hgvs.org"
_format The response format, currently can only be xml ("xml", "text/xml", "application/xml", or "application/fhir+xml") or json ("json", "application/json", "application/fhir+json"). Optional, default to "application/fhir+json". You may also use the "Accept" header to specify the response format, but the _format parameter, when specified, has higher priority. Note that if you make a request from the browser (address bar), your browser may send "Accept" headers. Therefore, when _format is not specified, the response format may depend on what "Accept" headers are being sent by your browser.
Example $lookup request & response

For request:

    https://clinicaltables.nlm.nih.gov/fhir/R4/CodeSystem/$lookup?_format=application/fhir%2Bjson&system=http://varnomen.hgvs.org&code=NC_000001.10:g.12345T%3EA
The response is: 
    {
      "resourceType": "Parameters",
      "parameter": [
        {
          "name": "name",
          "valueString": "HGVS"
        },
        {
          "name": "display",
          "valueString": "NC_000001.10:g.12345T>A"
        },
        {
          "name": "property",
          "part": [
            {
              "name": "code",
              "valueCode": "spdi"
            },
            {
              "name": "value",
              "valueString": "NC_000001.10:12344:T:A"
            }
          ]
        }
      ]
    }

For more in-depth descriptions on the FHIR CodeSystem operations, please refer to the FHIR Spec.