SNOMED CT Terminology Server REST API operations

Source: R/rest-api.R

Low-level wrapper functions based on httr for interfacing with the operations built in the Snowstorm API

api_concept(
  conceptId,
  endpoint = snomedizer_options_get("endpoint"),
  branch = snomedizer_options_get("branch"),
  catch404 = TRUE
)

api_concepts(
  term = NULL,
  conceptIds = NULL,
  ecl = NULL,
  eclStated = NULL,
  activeFilter = NULL,
  searchAfter = NULL,
  endpoint = snomedizer_options_get("endpoint"),
  branch = snomedizer_options_get("branch"),
  limit = snomedizer_options_get("limit"),
  offset = 0,
  catch404 = TRUE,
  ...
)

api_concept_descendants(
  conceptId,
  stated = FALSE,
  limit = snomedizer_options_get("limit"),
  offset = 0,
  endpoint = snomedizer_options_get("endpoint"),
  branch = snomedizer_options_get("branch"),
  catch404 = TRUE
)

api_concept_descriptions(
  conceptId,
  endpoint = snomedizer_options_get("endpoint"),
  branch = snomedizer_options_get("branch"),
  catch404 = TRUE
)

api_all_branches(
  endpoint = snomedizer_options_get("endpoint"),
  catch404 = TRUE
)

api_branch(
  endpoint = snomedizer_options_get("endpoint"),
  branch = snomedizer_options_get("branch"),
  catch404 = TRUE,
  ...
)

api_branch_descendants(
  endpoint = snomedizer_options_get("endpoint"),
  branch = snomedizer_options_get("branch"),
  catch404 = TRUE,
  ...
)

api_descriptions(
  conceptIds = NULL,
  endpoint = snomedizer_options_get("endpoint"),
  branch = snomedizer_options_get("branch"),
  offset = 0,
  limit = snomedizer_options_get("limit"),
  catch404 = TRUE,
  ...
)

api_version(endpoint = snomedizer_options_get("endpoint"), catch404 = TRUE)

api_browser_concepts(
  conceptId,
  descendantCountForm = c(NULL, "inferred", "stated", "additional"),
  endpoint = snomedizer_options_get("endpoint"),
  branch = snomedizer_options_get("branch"),
  catch404 = TRUE
)

api_browser_concept_ancestors(
  conceptId,
  form = "inferred",
  endpoint = snomedizer_options_get("endpoint"),
  branch = snomedizer_options_get("branch"),
  catch404 = TRUE
)

api_browser_concept_children(
  conceptId,
  form = "inferred",
  includeDescendantCount = TRUE,
  endpoint = snomedizer_options_get("endpoint"),
  branch = snomedizer_options_get("branch"),
  catch404 = TRUE
)

api_browser_concept_parents(
  conceptId,
  form = "inferred",
  includeDescendantCount = TRUE,
  endpoint = snomedizer_options_get("endpoint"),
  branch = snomedizer_options_get("branch"),
  catch404 = TRUE
)

api_browser_concept_descriptions(
  term,
  active = NULL,
  module = NULL,
  language = NULL,
  type = NULL,
  semanticTag = NULL,
  semanticTags = NULL,
  preferredIn = NULL,
  acceptableIn = NULL,
  preferredOrAcceptableIn = NULL,
  conceptActive = NULL,
  conceptRefset = NULL,
  groupByConcept = FALSE,
  searchMode = "STANDARD",
  limit = snomedizer_options_get("limit"),
  offset = 0,
  endpoint = snomedizer_options_get("endpoint"),
  branch = snomedizer_options_get("branch"),
  catch404 = TRUE
)

api_descriptions_semantic_tags(
  endpoint = snomedizer_options_get("endpoint"),
  branch = snomedizer_options_get("branch"),
  catch404 = TRUE
)

api_relationships(
  endpoint = snomedizer_options_get("endpoint"),
  branch = snomedizer_options_get("branch"),
  active = NULL,
  source = NULL,
  type = NULL,
  destination = NULL,
  characteristicType = NULL,
  limit = snomedizer_options_get("limit"),
  offset = 0,
  catch404 = TRUE,
  ...
)

api_relationship(
  endpoint = snomedizer_options_get("endpoint"),
  branch = snomedizer_options_get("branch"),
  relationshipId,
  catch404 = TRUE,
  ...
)

api_all_code_systems(
  endpoint = snomedizer_options_get("endpoint"),
  forBranch = NULL,
  catch404 = TRUE
)

api_code_system(
  endpoint = snomedizer_options_get("endpoint"),
  shortName,
  catch404 = TRUE
)

api_code_system_all_versions(
  endpoint = snomedizer_options_get("endpoint"),
  shortName,
  showFutureVersions = FALSE,
  showInternalReleases = FALSE,
  catch404 = TRUE
)

api_browser_refset_members(
  referenceSet = NULL,
  referenceSetModule = NULL,
  referencedComponentId = NULL,
  active = NULL,
  offset = NULL,
  searchAfter = NULL,
  endpoint = snomedizer_options_get("endpoint"),
  branch = snomedizer_options_get("branch"),
  limit = snomedizer_options_get("limit"),
  catch404 = TRUE
)

api_refset_members(
  referenceSet = NULL,
  referenceSetModule = NULL,
  referencedComponentId = NULL,
  active = NULL,
  offset = NULL,
  searchAfter = NULL,
  targetComponent = NULL,
  mapTarget = NULL,
  owlExpression.conceptId = NULL,
  owlExpression.gci = NULL,
  endpoint = snomedizer_options_get("endpoint"),
  branch = snomedizer_options_get("branch"),
  limit = snomedizer_options_get("limit"),
  catch404 = TRUE
)

Arguments

conceptId

character string of a SNOMED CT concept identifier (for example: "233604007")

endpoint

URL of a SNOMED CT Terminology Server REST API endpoint. See snomedizer_options.

branch

a string for the name of the API endpoint branch to use (most commonly "MAIN"). See snomedizer_options.

catch404

whether to display a warning if the API operation returns a '404 Not Found' status. Default is TRUE.

term

character vector of terms to search

conceptIds

a character vector of SNOMED CT concept identifiers (for example: c("233604007", "68566005"))

ecl

a character expression constraint query (with full relationship inference). Consult the Expression Constraint Language guide for more detail.

eclStated

a character expression constraint query (limited to stated relationships). Consult the Expression Constraint Language guide for more detail.

activeFilter

optional boolean:

  • TRUE returns only active terminology

  • FALSE returns only inactive terminology

  • NULL (the default) returns both active and inactive terminology

searchAfter

integer for the number of results to skip. May be used for for querying more that 10,000 records (current limit on results returned)

limit

a positive integer for the maximum number of results to return. See snomedizer_options. The maximum limit on public endpoints is 10,000.

offset

an integer indicating the number of results to skip

...

other REST API parameters

stated

a boolean indicating whether to limit search to descendants whose relationship is stated rather than inferred. Default is FALSE.

descendantCountForm

a character string indicating whether to report the count of descendant concepts based on stated or inferred relationships. Must be one of "inferred", "stated", or "additional". Default is NULL for no descendant count reported.

form

a character string indicating which ancestors/parents or descendants/children to extract based on stated or inferred relationships. Must be one of "inferred" (default), "stated", or "additional".

includeDescendantCount

a boolean indicating whether a number of children/descendants counter should be included in the result

active

optional boolean:

  • TRUE returns only active terminology

  • FALSE returns only inactive terminology

  • NULL (the default) returns both active and inactive terminology

module

character vector of SNOMED CT modules to include (example: "900000000000207008")

language

vector of two-character language codes to include (example: c("en", "de")).

type

character vector of concept codes defining the type of description or the type of attribute/relationship to include, depending on the function:

  • see api_concept_descendants("900000000000446008") for valid description type concepts.

  • see api_concept_descendants("106237007") for valid attributes (relationship types) concepts.

semanticTag

character string of a description semantic tag to include (example: "attribute"). See api_descriptions_semantic_tags() for a list of valid description semantic tags.

semanticTags

character vector of description semantic tags to include (example: c("attribute", "finding")). See api_descriptions_semantic_tags() for a list of valid description semantic tags.

preferredIn

character vector of description language reference sets (example: "900000000000509007"). The description must be preferred in at least one of these to match.

acceptableIn

character vector of description language reference sets (example: "900000000000509007"). The description must be acceptable in at least one of these to match.

preferredOrAcceptableIn

character vector of description language reference sets (example: "900000000000509007"). The description must be preferred OR acceptable in at least one of these to match.

conceptActive

optional boolean:

  • TRUE returns only active concepts

  • FALSE returns only inactive concepts

  • NULL (the default) returns both active and inactive concepts

conceptRefset

character vector of reference sets concept identifiers to include (example: "900000000000497000" for CTV3 terminology). See api_concept_descendants("900000000000455006") for valid reference set concepts.

groupByConcept

a boolean indicating whether to group descriptions by concept. Default is FALSE.

searchMode

a character string for the search mode. Must be either "STANDARD" (default) or "REGEX".

source

a character vector of concepts to be included as sources defined by the relationship

destination

concept character string restricting the range of the relationships to be included in results

characteristicType

a character string indicating whether to include results for:

  • all relationships: NULL (the default)

  • only stated relationships: "STATED_RELATIONSHIP"

  • only inferred relationships: "INFERRED_RELATIONSHIP"

  • only additional relationships: ""ADDITIONAL_RELATIONSHIP" (for instance, 123005000 | Part of (attribute) |)

This parameter corresponds to 900000000000449001 | Characteristic type (core metadata concept)

relationshipId

string of a relationship concept

forBranch

a character name of a single branch (eg "MAIN") for which to fetch code systems results. The default (NULL) will return all code systems.

shortName

character name of a code system (eg "SNOMEDCT", "SNOMEDCT-UK")

showFutureVersions

a boolean indicating whether to include all code systems (NULL), only future code systems (TRUE), or no future code systems (FALSE, the default)

showInternalReleases

a boolean indicating whether to include all terminology releases (NULL), only internal releases (TRUE), or only external releases (FALSE, the default)

referenceSet

a string for a reference set identifier or ECL expression can be used to limit the reference sets searched. Example: "<723564002"

referenceSetModule

a string identifier for a SNOMED CT module containing the reference sets to include. An ECL expression can be used to limit the modules searched, for example: "<900000000000445007"

referencedComponentId

a character vector of identifiers of SNOMED CT components to be included. For Map Reference Sets, this refers to the SNOMED CT concept that is mapped to the other terminology or code system

targetComponent

string identifier the target code (concept or description) in an Association Reference Set. Consult the Association Reference Set data structure for detail.

mapTarget

target code to which the SNOMED CT concept represented the referencedComponentId is mapped in the target code system, classification, or terminology (eg ICD-10). This is only used for Map Reference Sets

owlExpression.conceptId

a string for a concept identifier within an owlExpression. Consult the SNOMED CT OWL Guide for detail.

owlExpression.gci

a boolean indicating whether to return axiom members with a GCI owlExpression (TRUE), without (FALSE), or all members (NULL, the default). Consult the SNOMED CT OWL Guide for detail.

Value

An httr

response() object.

Disclaimer

In order to use SNOMED CT, a licence is required which depends both on the country you are based in, and the purpose of your work. See details on snomedizer.

Examples

# look up the pneumonia concept
api_concept(conceptId = "233604007")
#> Response [https://snowstorm.ihtsdotools.org/snowstorm/snomed-ct/MAIN/concepts/233604007]
#>   Date: 2022-07-08 08:44
#>   Status: 200
#>   Content-Type: application/json
#>   Size: 370 B
#> {
#>   "conceptId" : "233604007",
#>   "active" : true,
#>   "definitionStatus" : "FULLY_DEFINED",
#>   "moduleId" : "900000000000207008",
#>   "effectiveTime" : "20150131",
#>   "fsn" : {
#>     "term" : "Pneumonia (disorder)",
#>     "lang" : "en"
#>   },
#> ...
api_concepts(term = "pneumonia")
#> Response [https://snowstorm.ihtsdotools.org/snowstorm/snomed-ct/MAIN/concepts?term=pneumonia&limit=50&offset=0]
#>   Date: 2022-07-08 08:44
#>   Status: 200
#>   Content-Type: application/json
#>   Size: 22 kB
#> {
#>   "items" : [ {
#>     "conceptId" : "60363000",
#>     "active" : false,
#>     "definitionStatus" : "PRIMITIVE",
#>     "moduleId" : "900000000000207008",
#>     "effectiveTime" : "20020131",
#>     "fsn" : {
#>       "term" : "Pneumonia (disorder)",
#>       "lang" : "en"
#> ...
api_concepts(conceptIds = c("233604007", "68566005"))
#> Response [https://snowstorm.ihtsdotools.org/snowstorm/snomed-ct/MAIN/concepts?conceptIds=233604007&conceptIds=68566005&limit=50&offset=0]
#>   Date: 2022-07-08 08:44
#>   Status: 200
#>   Content-Type: application/json
#>   Size: 1.02 kB
#> {
#>   "items" : [ {
#>     "conceptId" : "68566005",
#>     "active" : true,
#>     "definitionStatus" : "FULLY_DEFINED",
#>     "moduleId" : "900000000000207008",
#>     "effectiveTime" : "20020131",
#>     "fsn" : {
#>       "term" : "Urinary tract infectious disease (disorder)",
#>       "lang" : "en"
#> ...

# get the content of the server request
pneumonia <- httr::content(api_concepts(term = "pneumonia"), limit = 1)
str(pneumonia$items[[1]])
#> List of 9
#>  $ conceptId       : chr "60363000"
#>  $ active          : logi FALSE
#>  $ definitionStatus: chr "PRIMITIVE"
#>  $ moduleId        : chr "900000000000207008"
#>  $ effectiveTime   : chr "20020131"
#>  $ fsn             :List of 2
#>   ..$ term: chr "Pneumonia (disorder)"
#>   ..$ lang: chr "en"
#>  $ pt              :List of 2
#>   ..$ term: chr "Pneumonia"
#>   ..$ lang: chr "en"
#>  $ id              : chr "60363000"
#>  $ idAndFsnTerm    : chr "60363000 | Pneumonia (disorder) |"