NAV
Ruby Shell

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. -
Ruby Shell