Ontology API v1
An ontology is the complete set of relationships among concepts, contexts, and codings. A concept is a group of codings that originate from the same or different coding systems. For example, the concept that groups codes that describe the medical condition of acne might contain ICD-10 code L70 and SNOMED code 11381005. A context is a group of related concepts. For example, to better understand and identify conditions a context might be created that contains the concepts for acne, type 1 diabetes, type 2 diabetes, and hypertension. Concepts are uniquely identified in a context by aliases.
Ontology data is processed into the system from HealtheIntent nightly. Currently, this API can be used only to retrieve data. Access is restricted by tenant, and tenants have access to only the contexts to which they are granted access. If you want to access ontology data using this API, contact your Cerner support team.
URL: https://cernerdemo.api.us-1.healtheintent.com/ontology/v1
Contexts
Contexts are the groups of related concepts that make up an ontology.
Retrieve a List of Contexts
Example Request:
require 'httparty' # Using HTTParty 0.16.2
require 'json'
headers = {
'Authorization' => '<auth_header>',
'Accept' => 'application/json'
}
result = HTTParty.get('https://cernerdemo.api.us-1.healtheintent.com/ontology/v1/contexts', headers: headers)
print JSON.pretty_generate(result)
# You can also use wget
curl -X GET https://cernerdemo.api.us-1.healtheintent.com/ontology/v1/contexts \
-H 'Authorization: {auth_header}' \
-H 'Accept: application/json'
Example response
{
"items": [
{
"id": "301C26DD38E14028B202B77BF24D091E",
"name": "CDQ Hypertension"
}
],
"totalResults": 1,
"firstLink": "https://cernerdemo.api.us-1.healtheintent.com/contexts?offset=0&limit=20",
"lastLink": "https://cernerdemo.api.us-1.healtheintent.com/contexts?offset=0&limit=20"
}
GET /contexts
Retrieves a list of contexts.
Parameters
Parameter | In | Type | Required | Default | Description | Accepted Values |
---|---|---|---|---|---|---|
id | query | array[string] | false | N/A | Filters the list of results to only those with the specified context ID.This query parameter can be repeated multiple times to query for multiple IDs at a time. | - |
name | query | string | false | N/A | Filters the list of results to only items that contain the specified name. Partial matching is allowed. | - |
offset | query | integer(int32) | false | 0 | The number of results to skip from the beginning of the list of results (typically for the purpose of paging). The minimum offset is 0. There is no maximum offset. | - |
limit | query | integer(int32) | false | 20 | The maximum number of results to display per page. The minimum limit is 1. The maximum limit is 100. | - |
Response Statuses
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK | OK | Contexts |
400 | Bad Request | Bad Request | Error |
401 | Unauthorized | Unauthorized | Error |
403 | Forbidden | Forbidden | Error |
Retrieve a List of Concepts
Example Request:
require 'httparty' # Using HTTParty 0.16.2
require 'json'
headers = {
'Authorization' => '<auth_header>',
'Accept' => 'application/json'
}
result = HTTParty.get('https://cernerdemo.api.us-1.healtheintent.com/ontology/v1/contexts/37686A3F9C66452ABA66803ECC144344/concepts', headers: headers)
print JSON.pretty_generate(result)
# You can also use wget
curl -X GET https://cernerdemo.api.us-1.healtheintent.com/ontology/v1/contexts/37686A3F9C66452ABA66803ECC144344/concepts \
-H 'Authorization: {auth_header}' \
-H 'Accept: application/json'
Example response
{
"items": [
{
"name": "Asthma Control Questionnaire Score",
"aliases": [
"DEPRESSION_SCREEN_POSITIVE_WITH_INTERVENTION_CLIN",
"DEPRESSION_SCREENING_POSITIVE_WITH_INTERVENTION_CLIN"
],
"representativeCodings": [
{
"code": "445531003",
"systems": [
"2.16.840.1.113883.6.96",
"2.16.840.1.113883.2.1.3.2.4.15"
]
}
]
}
],
"totalResults": 1,
"firstLink": "https://cernerdemo.api.us-1.healtheintent.com/contexts/37686A3F9C66452ABA66803ECC144344/concepts?offset=0&limit=20",
"lastLink": "https://cernerdemo.api.us-1.healtheintent.com/contexts/37686A3F9C66452ABA66803ECC144344/concepts?offset=0&limit=20"
}
GET /contexts/{contextId}/concepts
Retrieves a list of the concepts that are present in the specified context. Only codes marked as representative are retrieved for each concept in the response.
Parameters
Parameter | In | Type | Required | Default | Description | Accepted Values |
---|---|---|---|---|---|---|
contextId | path | string | true | N/A | The ID of the context. | - |
code | query | string | false | N/A | Filters the response to only items that contain the specified code. If this parameter is specified, the system parameter must also be provided because the coding system defines the meaning of the codes it contains. | - |
system | query | string | false | N/A | Filters the response to only items that contain the specified system ID. If this parameter is specified, the code parameter must also be provided. | - |
name | query | string | false | N/A | Filters the list of results to only items that contain the specified name. Partial matching is allowed. | - |
offset | query | integer(int32) | false | 0 | The number of results to skip from the beginning of the list of results (typically for the purpose of paging). The minimum offset is 0. There is no maximum offset. | - |
limit | query | integer(int32) | false | 20 | The maximum number of results to display per page. The minimum limit is 1. The maximum limit is 100. | - |
Response Statuses
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK | OK | Concepts |
400 | Bad Request | Bad Request | Error |
401 | Unauthorized | Unauthorized | Error |
403 | Forbidden | Forbidden | Error |
404 | Not Found | Not Found | Error |
Retrieve a Single Concept
Example Request:
require 'httparty' # Using HTTParty 0.16.2
require 'json'
headers = {
'Authorization' => '<auth_header>',
'Accept' => 'application/json'
}
result = HTTParty.get('https://cernerdemo.api.us-1.healtheintent.com/ontology/v1/contexts/37686A3F9C66452ABA66803ECC144344/concepts/ASTHMA_ACTION_PLAN_PROC', headers: headers)
print JSON.pretty_generate(result)
# You can also use wget
curl -X GET https://cernerdemo.api.us-1.healtheintent.com/ontology/v1/contexts/37686A3F9C66452ABA66803ECC144344/concepts/ASTHMA_ACTION_PLAN_PROC \
-H 'Authorization: {auth_header}' \
-H 'Accept: application/json'
Example response
{
"name": "Asthma Control Questionnaire Score",
"aliases": [
"DEPRESSION_SCREEN_POSITIVE_WITH_INTERVENTION_CLIN",
"DEPRESSION_SCREENING_POSITIVE_WITH_INTERVENTION_CLIN"
],
"representativeCodings": [
{
"code": "445531003",
"systems": [
"2.16.840.1.113883.6.96",
"2.16.840.1.113883.2.1.3.2.4.15"
]
}
]
}
GET /contexts/{contextId}/concepts/{conceptAlias}
Retrieves the concept in the context that is identified by the specified concept alias. Multiple URLs may retrieve the same concept because a single concept can have multiple aliases. Additionally, aliases can be removed from a concept; if this occurs and a request is sent to the previously valid URL for the alias, the API sends a 404 status code (Not Found).
Parameters
Parameter | In | Type | Required | Default | Description | Accepted Values |
---|---|---|---|---|---|---|
conceptAlias | path | string | true | N/A | The unique ID of the concept in the context. This value is not necessarily unique across contexts. | - |
contextId | path | string | true | N/A | The ID of the context. | - |
Response Statuses
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK | OK | Concept |
400 | Bad Request | Bad Request | Error |
401 | Unauthorized | Unauthorized | Error |
403 | Forbidden | Forbidden | Error |
404 | Not Found | Not Found | Error |
Retrieve a List of Codings
Example Request:
require 'httparty' # Using HTTParty 0.16.2
require 'json'
headers = {
'Authorization' => '<auth_header>',
'Accept' => 'application/json'
}
result = HTTParty.get('https://cernerdemo.api.us-1.healtheintent.com/ontology/v1/contexts/23565CBCEF0A4F06994731E706936E55/concepts/ACETAMINOPHEN_DIPHENHYDRAMINE_PHENYLEPHRINE_MED/codings', headers: headers)
print JSON.pretty_generate(result)
# You can also use wget
curl -X GET https://cernerdemo.api.us-1.healtheintent.com/ontology/v1/contexts/23565CBCEF0A4F06994731E706936E55/concepts/ACETAMINOPHEN_DIPHENHYDRAMINE_PHENYLEPHRINE_MED/codings \
-H 'Authorization: {auth_header}' \
-H 'Accept: application/json'
Example response
{
"items": [
{
"code": "445531003",
"systems": [
"2.16.840.1.113883.6.96",
"2.16.840.1.113883.2.1.3.2.4.15"
]
}
],
"totalResults": 1,
"firstLink": "https://cernerdemo.api.us-1.healtheintent.com/ontology/v1/contexts/23565CBCEF0A4F06994731E706936E55/concepts/ACETAMINOPHEN_DIPHENHYDRAMINE_PHENYLEPHRINE_MED/codings?offset=0&limit=20",
"lastLink": "https://cernerdemo.api.us-1.healtheintent.com/ontology/v1/contexts/23565CBCEF0A4F06994731E706936E55/concepts/ACETAMINOPHEN_DIPHENHYDRAMINE_PHENYLEPHRINE_MED/codings?offset=0&limit=20"
}
GET /contexts/{contextId}/concepts/{conceptAlias}/codings
Retrieves a list of all of the codes that are present in a concept.
Parameters
Parameter | In | Type | Required | Default | Description | Accepted Values |
---|---|---|---|---|---|---|
contextId | path | string | true | N/A | The ID of the context. | - |
conceptAlias | path | string | true | N/A | The unique ID of the concept in the context. This value is not necessarily unique across contexts. | - |
system | query | string | false | N/A | The ID of a code system. Filters the response to codes belonging to only the specified code system. | - |
offset | query | integer(int32) | false | 0 | The number of results to skip from the beginning of the list of results (typically for the purpose of paging). The minimum offset is 0. There is no maximum offset. | - |
limit | query | integer(int32) | false | 250 | The maximum number of results to display per page. The minimum limit is 0. The maximum limit is 250. | - |
Response Statuses
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK | OK | Codings |
400 | Bad Request | Bad Request | Error |
401 | Unauthorized | Unauthorized | Error |
403 | Forbidden | Forbidden | Error |
404 | Not Found | Not Found | Error |
Schema Definitions
Contexts
Name | Type | Required | Description | Accepted Values |
---|---|---|---|---|
items | [Context] | true | An array containing the current page of results. | - |
totalResults | integer(int32) | false | The total number of results for the specified parameters. | - |
firstLink | string | true | The first page of results. | - |
lastLink | string | false | The last page of results. | - |
prevLink | string | false | The previous page of results. | - |
nextLink | string | false | The next page of results. | - |
Context
Name | Type | Required | Description | Accepted Values |
---|---|---|---|---|
id | string | true | The unique ID of the context. IDs are in all caps and do not include dashes. | - |
name | string | true | The human-readable description of the context. | - |
Error
Name | Type | Required | Description | Accepted Values |
---|---|---|---|---|
code | integer(int32) | true | The HTTP response status code that represents the error. | - |
message | string | true | A human-readable description of the error. | - |
errorDetails | [ErrorDetail] | false | A list of additional error details. | - |
ErrorDetail
Name | Type | Required | Description | Accepted Values |
---|---|---|---|---|
domain | string | false | A subsystem or context where an error occurred. | - |
reason | string | false | A codified value that represents the specific error that caused the current error status. | - |
message | string | false | A human-readable description of an error. | - |
locationType | string | false | The location or type of the field that caused an error. | query, header, path, formData, body |
location | string | false | The name of the field that caused an error. | - |
Concepts
Name | Type | Required | Description | Accepted Values |
---|---|---|---|---|
items | [Concept] | true | An array containing the current page of results. | - |
totalResults | integer(int32) | false | The total number of results for the specified parameters. | - |
firstLink | string | true | The first page of results. | - |
lastLink | string | false | The last page of results. | - |
prevLink | string | false | The previous page of results. | - |
nextLink | string | false | The next page of results. | - |
Concept
Name | Type | Required | Description | Accepted Values |
---|---|---|---|---|
name | string | false | The human-readable description of the concept. | - |
aliases | [string] | false | The unique IDs of the concept in a context. | - |
representativeCodings | [Coding] | false | A list of representative codes in the concept. A code is marked as representative when it is considered the best code to represent the meaning of the concept. Concepts are not required to have any representative codes, but usually only one exists if it does. | - |
Coding
Name | Type | Required | Description | Accepted Values |
---|---|---|---|---|
code | string | false | The unique ID of a code in a coding system. | - |
systems | [string] | false | The list of possible IDs of the code system that defines the meaning of the code ID. Multiple system IDs are possible because as time goes on the systems can be expanded or clarified while the underlying codes are left unchanged. For example, a certain system might use a value of 2.16.840.1.113883.6.2 to represent all ICD-9-CM codes but later be divided to add two additional systems of 2.16.840.1.113883.6.103 and 2.16.840.1.113883.6.104 to repesent diagnosis and procedure ICDM-CM codes respectively. | - |
Codings
Name | Type | Required | Description | Accepted Values |
---|---|---|---|---|
items | [Coding] | true | An array containing the current page of results. | - |
totalResults | integer(int32) | false | The total number of results for the specified parameters. | - |
firstLink | string | true | The first page of results. | - |
lastLink | string | false | The last page of results. | - |
prevLink | string | false | The previous page of results. | - |
nextLink | string | false | The next page of results. | - |