# Get Terms for a Concept

## Overview

Each concept is associated with descriptions. Each description is an association between a human-readable phrase (term) and a particular SNOMED CT concept.

There are different types of descriptions and there may be descriptions of each of the following types in several languages:

* A synonym is a word or phrase that expresses the meaning of a SNOMED CT concept in a specified language.
  * Synonyms are terms that represent the meaning of the concept in a way that is familiar and readily understandable. However, when taken out of context a synonym may not be unambiguous and in some cases the same term may be associated with more than one concept.
  * Each concept has at least one synonym and a concepts may have several synonyms. One of the synonym descriptions in each language is marked as the preferred term for the associated concept and others may be marked as acceptable for use. The preferred term is the term deemed to be the most clinically appropriate way of expressing a concept in specified language context.
* A fully specified name is a description that represents the meaning of a concept in a way that is unambiguous and independent of the context in which it is used.
  * Fully specified names are essential for disambiguation of the meaning of a concept. These term used in the fully specified name includes a hierarchy tag that specifies the branch of the SNOMED CT hierarchy the concept is in. The hierarchy tag is enclosed in brackets at the end of the term.
  * There is only one fully specified name in each language. In some languages there may not be a fully specified name, in which case the English fully specified name may be used where necessary for disambiguation.
* A text definition is a narrative text explanation of the meaning of a concept that may exceed the maximum permitted length for a fully specified name.
  * Text definitions are only included for some concepts where longer terms are deemed to be necessary or useful to add clarity to the meaning of the concept.

## Requirements and Options

Terminology services must enable access to the term in each active description associated with an identified concept. They should also be able to selectively filter the descriptions for which terms are returned based on the following criteria:

* Active status (description.active)
  * Inactive descriptions associated with a concept should not be returned unless explicitly requested.
* Description type (description.typeId)
  * Fully specified name
  * Synonyms (including the preferred term)
  * Textual definitions (and other types where these are used)
* Acceptability in a specified Language Reference Set
  * Preferred: To access the fully specified name or preferred term
  * Acceptable: To access synonyms

The required services are listed in the table below.

{% hint style="success" %}
The services described in [Get a Concept, Description or Relationship](https://docs.snomed.org/snomed-ct-practical-guides/snomed-ct-terminology-services-guide/4-terminology-service-types/4.2-get-a-concept-description-or-relationship) require access to data about individual components based on their unique identifiers. Therefore, a service that gets a description is only required to return the data in the identified description. However, some implementations of those services may also meet some of the requirements for getting terms associated with a concept.

* Services that get concepts may also return some or all of the terms associated with the selected concept.
  * For example, the Snowstorm service that retrieves an identified concept also returns the fully specified name and preferred term for that concept in one language.
  * Similarly, the FHIR service returns a single display term and may optionally also return other associated terms as designations.
* Services that get relationships may also return terms associated with the concepts identified by those relationships.
  {% endhint %}

#### Services Required

<table data-full-width="true"><thead><tr><th>Service Name and Status</th><th width="206.34765625">Input</th><th>Output</th></tr></thead><tbody><tr><td><p><a data-footnote-ref href="#user-content-fn-1"><strong>Get fully specified name of a concept</strong></a></p><ul><li>Get the fully specified name of a concept in US English (or in a specified language reference set).</li></ul><p><strong>REQUIRED</strong></p></td><td><ul><li>Edition and version<br></li><li>Concept identifier</li><li>Language refset set identifier (optional)</li></ul></td><td><ul><li>Description not found: Return appropriate error message</li><li><p>Description found: Return data associated with the description:</p><ul><li>Required: id, term, caseSignificanceId</li><li><p>Optional:</p><ul><li>typeId (which will always be <a href="http://snomed.info/id/900000000000207008">900000000000207008 | fully specified name|</a> )</li><li>languageCode</li></ul></li></ul></li></ul></td></tr><tr><td><p><a data-footnote-ref href="#user-content-fn-2"><strong>Get preferred term of a concept</strong></a></p><ul><li>Get the preferred term of a concept in US English (or in a specified language reference set).</li></ul><p><strong>REQUIRED</strong></p></td><td><ul><li>Edition and version</li><li>Concept identifier</li><li>Language refset set identifier (optional)</li></ul></td><td><ul><li>Description not found: Return appropriate error message</li><li><p>Description found: Return data associated with the description:</p><ul><li>Required: id, term, caseSignificanceId</li><li><p>Optional:</p><ul><li>typeId (which will always be <a href="http://snomed.info/id/900000000000013009">900000000000013009 | synonym|</a> )</li><li>languageCode</li></ul></li></ul></li></ul></td></tr><tr><td><p><strong>Get all terms for a concept</strong></p><ul><li>Get the terms from all descriptions associated with a concept<br></li></ul><p><strong>REQUIRED</strong><br></p></td><td><ul><li>Edition and version</li><li>Concept identifier</li><li>Include inactive descriptions (optional)</li></ul></td><td><ul><li>Descriptions not found: Return appropriate error message</li><li><p>Descriptions found: Return data associated with each of the descriptions found</p><ul><li>This data must include the id, term, active status, description type, language code and case sensitivity</li><li>It should also include the acceptability of the term in one or more language reference sets</li></ul></li></ul></td></tr><tr><td><p><a data-footnote-ref href="#user-content-fn-3"><strong>Get filtered terms for a concept</strong></a></p><ul><li><p>Get terms from descriptions associated with a particular concept filtered by one or more of the following</p><ul><li>Status of the description (<em>active:</em> 1=true, 0=false)</li><li>Term (<em>term:</em> matching a phrase or pattern)</li><li>Description type (<em>typeId:</em> fully specified name, synonym, textual definition)</li><li>Language (<em>languageCode</em>)</li><li>Acceptability in a specified language reference set (<em>refset</em>.<em>acceptabilityId:</em> preferred, acceptable)</li></ul></li></ul><p><strong>CONDITIONAL</strong></p></td><td><ul><li>Edition and version</li><li>Concept identifier</li><li><p>Filters</p><ul><li>Active</li><li>TypeId</li><li>Language code</li><li>Language refset identifier</li><li>Language refset acceptability</li></ul></li></ul></td><td><ul><li>Descriptions not found: Return appropriate error message</li><li><p>Descriptions found: Return data associated with the descriptions found<br></p><ul><li>This data must include the id, term and case sensitivity</li><li>It must also include the term, active status, description type, language code</li></ul></li></ul></td></tr></tbody></table>

## Interdependencies

#### Required By

* Use Cases
  * [explore-and-review-snomed-ct](https://docs.snomed.org/snomed-ct-practical-guides/snomed-ct-terminology-services-guide/3-terminology-service-use-cases/explore-and-review-snomed-ct "mention")
  * [support-ehr-data-entry](https://docs.snomed.org/snomed-ct-practical-guides/snomed-ct-terminology-services-guide/3-terminology-service-use-cases/support-ehr-data-entry "mention")
  * [display-ehr-data](https://docs.snomed.org/snomed-ct-practical-guides/snomed-ct-terminology-services-guide/3-terminology-service-use-cases/display-ehr-data "mention")
  * [ehr-reporting-and-analytics](https://docs.snomed.org/snomed-ct-practical-guides/snomed-ct-terminology-services-guide/3-terminology-service-use-cases/ehr-reporting-and-analytics "mention")
  * [support-terminology-authoring-and-review](https://docs.snomed.org/snomed-ct-practical-guides/snomed-ct-terminology-services-guide/3-terminology-service-use-cases/support-terminology-authoring-and-review "mention")

#### Depends On

* Service Types
  * [4.1-select-edition-and-version](https://docs.snomed.org/snomed-ct-practical-guides/snomed-ct-terminology-services-guide/4-terminology-service-types/4.1-select-edition-and-version "mention")

{% hint style="info" %}
This service requires access to description acceptability data in a language reference set. This could be regarded as a dependency on [Get Data from a Reference Set](https://docs.snomed.org/snomed-ct-practical-guides/snomed-ct-terminology-services-guide/4-terminology-service-types/4.10-get-data-from-a-reference-set). However, access to language reference set data is an essential part of the process of displaying appropriate terms for a concept. Therefore access to the language reference set is included as an integral part of this service and is not declared as a distinct dependency.
{% endhint %}

## Service Examples <a href="#id-4.3gettermsforaconcept-serviceexamples" id="id-4.3gettermsforaconcept-serviceexamples"></a>

{% hint style="success" %}
The Snowstorm and FHIR examples are presented in plain text and URL encoded versions. Always use the "Encoded URL" when testing the example service requests. The plain text version is included to aid readability but using this version in a service request may result in errors. These errors result from characters that have to be encoded as they are not permitted in a URL (see [IETF RFC1738](https://www.ietf.org/rfc/rfc1738.txt)).
{% endhint %}

### Snowstorm API

<table data-full-width="true"><thead><tr><th width="172.984375">Service Name</th><th>API Call</th><th>Result</th></tr></thead><tbody><tr><td><strong>Get fully specified name of a concept</strong><br><br><strong>Get preferred term of a concept</strong></td><td><pre data-overflow="wrap"><code>GET [snowstorm]/[branchPath]/concepts/[conceptId]
</code></pre><p>for example</p><pre data-overflow="wrap"><code>GET [snowstorm]/MAIN/2020-01-31/concepts/6025007
</code></pre><hr><p><em>Encoded URL</em></p><pre data-overflow="wrap"><code>GET [snowstorm]/MAIN%2F2020-01-31/concepts/6025007
</code></pre></td><td><p>Returns a JSON representation of data about the selected concept. This include both the fully specified name and the preferred term.</p><p>This is the same Snowstorm API call used in <a data-mention href="4.2-get-a-concept-description-or-relationship">4.2-get-a-concept-description-or-relationship</a>to get the concept by identifier. If the fully specified name and/or preferred term there is no need for a specific service to get these terms.</p></td></tr><tr><td><strong>Get all terms for a concept</strong></td><td><pre data-overflow="wrap"><code>GET [snowstorm]/[branchPath]/concepts/[conceptId]/descriptions
</code></pre><p>for example</p><pre data-overflow="wrap"><code>GET [snowstorm]/MAIN/2020-01-31/concepts/6025007/descriptions
</code></pre><hr><p><em>Encoded URL</em></p><pre data-overflow="wrap"><code>GET [snowstorm]/MAIN%2F2020-01-31/concepts/6025007/descriptions
</code></pre></td><td><p>Returns a JSON representation of data about all descriptions in the selected edition and version that are associated with the concept specified.</p><p>The descriptions returned include:</p><ul><li>Active and inactive descriptions</li><li>All types of descriptions</li><li>Descriptions in all languages that are present in the selected edition</li></ul><p>The data return for each description includes all data present in the description release file and acceptability data derived from language reference sets. The following items have specific roles in filtering descriptions and presenting the terms they contain:</p><ul><li>The <strong>active</strong> value (true or false) can be used to exclude inactive descriptions.</li><li><p>The <strong>typeId</strong> value can be used to filter descriptions of specific types.</p><ul><li>The additional a text token <strong>type</strong> provides a human readable representation.</li></ul></li><li>The <strong>lang</strong> value contains the language code and this can be used to filter descriptions.</li><li>The <strong>acceptabilityMap</strong> contains text tokens for the acceptability of the description in one or more language reference sets.</li><li>The <strong>caseSignificance</strong> value contains a text token indicate whether all or part of a term is case-sensitive. This can be used to enable the case of a term to be adjusted to fit the context of use except in when this would be incorrect or liable to alter the meaning.</li></ul></td></tr><tr><td><strong>Get filtered terms for a concept</strong></td><td>Use the API call above to get all terms for a concept and then filter using the returned data.</td><td>Same as above</td></tr></tbody></table>

{% hint style="info" %}
Snowstorm supports selection of the language(s) in which terms will be returned. This is specified using HTTP request header Accept-Language. The values used with this include the identifiers of the language reference sets to be applied.

For example

{\
"Accept": "application/json",\
\&#xNAN;**"Accept-Language": "en-X-900000000000509007,en-X-900000000000508004,en"**\
}
{% endhint %}

### FHIR API

<table data-full-width="true"><thead><tr><th width="140.5390625">Service Name</th><th>API Call</th><th>Result</th></tr></thead><tbody><tr><td><strong>Get all descriptions for a concept</strong></td><td><pre data-overflow="wrap"><code>GET [fhir]/CodeSystem/$lookup?system=http://snomed.info/sct&#x26;code=[conceptId]
</code></pre><p>for example</p><pre data-overflow="wrap"><code><strong>GET [fhir]/CodeSystem/$lookup?system=http://snomed.info/sct&#x26;code=6025007
</strong></code></pre></td><td><p>Returns a JSON representation of data about the selected concept. This include both the fully specified name and all synonyms of the concept.</p><p>This is the same FHIR API call used in <a href="4.2-get-a-concept-description-or-relationship">Get a Concept, Description or Relationship</a> to get concept by identifier. If the fully specified name and/or preferred term there is no need for a specific service to get these terms.</p></td></tr></tbody></table>

### MySQL Example Database

<table data-full-width="true"><thead><tr><th width="259.51171875">Service Name</th><th width="301.64453125">API Call</th><th>Result</th></tr></thead><tbody><tr><td><strong>Get fully specified name of a concept</strong></td><td><pre class="language-sql" data-overflow="wrap"><code class="lang-sql">SELECT term,caseSignificanceId FROM snap_fsn WHERE conceptId=[conceptId]
</code></pre><p>for example</p><pre class="language-sql" data-overflow="wrap"><code class="lang-sql">SELECT term,caseSignificanceId FROM snap_fsn WHERE conceptId=6025007
</code></pre></td><td>Returns the fully specified name of a specified concept and its caseSignificanceId.</td></tr><tr><td><strong>Get preferred term of a concept</strong></td><td><pre class="language-sql" data-overflow="wrap"><code class="lang-sql">SELECT term,caseSignificanceId FROM snap_pref WHERE conceptId=[conceptId]
</code></pre><p>for example</p><pre class="language-sql" data-overflow="wrap"><code class="lang-sql">SELECT term,caseSignificanceId FROM snap_pref WHERE conceptId=6025007
</code></pre></td><td>Returns the preferred term of a specified concept and its caseSignificanceId</td></tr><tr><td><strong>Get all synonyms of a concept</strong></td><td><pre class="language-sql" data-overflow="wrap"><code class="lang-sql">SELECT term,caseSignificanceId FROM snap_synall WHERE conceptId=[conceptId]
</code></pre><p>for example</p><pre class="language-sql" data-overflow="wrap"><code class="lang-sql">SELECT term,caseSignificanceId FROM snap_synall WHERE conceptId=6025007
</code></pre></td><td><a data-footnote-ref href="#user-content-fn-4">Returns all the preferred term of a specified concept and with their caseSignificanceId values.</a></td></tr><tr><td><strong>Get all terms for a concept</strong></td><td><pre class="language-sql" data-overflow="wrap"><code class="lang-sql">SELECT * FROM snap_description WHERE conceptId=[conceptId]
</code></pre><p>for example</p><pre class="language-sql" data-overflow="wrap"><code class="lang-sql">SELECT * FROM snap_description WHERE conceptId=6025007
</code></pre></td><td>Returns all descriptions of all concepts together with all the data for each of those descriptions in the concept file.</td></tr><tr><td><a data-footnote-ref href="#user-content-fn-5"><strong>Set language configuration</strong></a></td><td><pre class="language-sql" data-overflow="wrap"><code class="lang-sql">CALL setLanguage([configId],[languageCode]);
</code></pre><p>for example</p><pre class="language-sql" data-overflow="wrap"><code class="lang-sql">CALL setLanguage(0,'en-GB');
</code></pre></td><td><p>After this setting is made all references to views including the prefix <strong>snap_</strong> and the suffixes <strong>_fsn</strong>, <strong>_pref</strong>, <strong>_syn</strong>, <strong>_synall</strong> will use the language reference set for GB English (rather than the default language US English).</p><p>Other languages supported by the the installed Edition can also be specified in a similar way.</p></td></tr></tbody></table>

{% hint style="info" %}
The SNOMED CT MySQL example database is **not** designed as a terminology server and is **not** intended for use in a live system . It is referenced in this guide as an illustration that some readers may find helpful. For more information about the SNOMED CT example database see the [SNOMED CT - SQL Practical Guide](https://app.gitbook.com/o/h8Z6qGxuQrzM9vbx5bPT/s/LnTo62BQeQSW6tBNKv0T/).
{% endhint %}

<a href="https://docs.google.com/forms/d/e/1FAIpQLScTmbZIf0UEQwYDkY27EEWBkaiYkHSbR0_9DmFrMLXoQLyL7Q/viewform?usp=pp_url&#x26;entry.1767247133=SNOMED+Terminology+Services+Guide&#x26;entry.670899847=Get%20Terms%20for%20a%20Concept" class="button primary">Provide Feedback</a>

[^1]: This requirement is identified as a special case as it is a common requirement. However, it can be met indirectly by either:

    * *Get concept by identifier* if that service returns the fully specified name in addition to data from the concept file.
    * *Get filtered terms for a concept* with appropriate filter settings.

[^2]: This requirement is identified as a special case as it is a common requirement. However, it can be met indirectly by either:

    * *Get concept by identifier* if that service returns the preferred term in addition to data from the concept file.
    * *Get filtered terms for a concept* with appropriate filter settings.

[^3]: If data necessary to support filtering is provided by "get all descriptions" service, filtering can be done by the client application. In this case, a specific filtered service may not be required.

[^4]: The view snap\_synall includes both preferred and acceptable synonyms. So it includes the the preferred term. The view snap\_syn can be used in the same way and this excludes the preferred term.

[^5]: The queries above for fully specified name, preferred terms and synonyms rely on a language configuration to determine which descriptions are used. By default the US English the setting is applied. However, this can be changed using the setLanguage procedure call shown here.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.snomed.org/snomed-ct-practical-guides/snomed-ct-terminology-services-guide/4-terminology-service-types/4.3-get-terms-for-a-concept.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.