Use the Healthcare Natural Language API

This page explains how to enable the Healthcare Natural Language API, configure permissions, and call the analyzeEntities method to extract medical insights from medical text.

Overview

The Healthcare Natural Language API provides machine learning solutions for deriving insights from medical text. The Healthcare Natural Language API is part of the Cloud Healthcare API. For an overview of the Healthcare Natural Language API, see the Healthcare Natural Language API conceptual documentation .

The Healthcare Natural Language API parses unstructured medical text such as medical records or insurance claims. It then generates a structured data representation of the medical knowledge entities stored in these data sources for downstream analysis and automation. For example, you can:

Extract information about medical concepts like diseases, medications, medical devices, procedures, and their clinically relevant attributes
Map medical concepts to standard medical vocabularies such as RxNorm, ICD-10, MeSH, and SNOMED CT (US and UK users only)
Derive medical insights from text and integrate them with data analytics products in Google Cloud

Available locations

The Healthcare Natural Language API is available in the following locations:

Location name	Location description
`asia-south1`	Mumbai, India
`australia-southeast1`	Sydney, Australia
`europe-west2`	London, UK
`europe-west4`	Netherlands
`northamerica-northeast1`	Montréal, Canada
`us-central1`	Iowa, USA

Enable the Healthcare Natural Language API

Before you begin using the Healthcare Natural Language API, you must enable the API for your Google Cloud project. You can use the Healthcare Natural Language API without enabling or using features of the Cloud Healthcare API.

To enable the API, complete the following steps:

Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Go to project selector

Verify that billing is enabled for your Google Cloud project .

Create a service account:

In the Google Cloud console, go to the Create service account page.
Go to Create service account
Select your project.
In the Service account name field, enter a name. The Google Cloud console fills in the Service account ID field based on this name.

In the Service account description field, enter a description. For example, Service account for quickstart .
Click Create and continue .
Grant the Project > Owner role to the service account.

To grant the role, find the Select a role list, then select Project > Owner .

Note : The Role field affects which resources the service account can access in your project. You can revoke these roles or grant additional roles later. In production environments, do not grant the Owner, Editor, or Viewer roles. Instead, grant a predefined role or custom role that meets your needs.
Click Continue .
Click Done to finish creating the service account.

Do not close your browser window. You will use it in the next step.

Create a service account key:

In the Google Cloud console, click the email address for the service account that you created.
Click Keys .
Click Add key , and then click Create new key .
Click Create . A JSON key file is downloaded to your computer.
Click Close .

Set the environment variable GOOGLE_APPLICATION_CREDENTIALS to the path of the JSON file that contains your credentials. This variable applies only to your current shell session, so if you open a new session, set the variable again.

Example:Linux or macOS

 export 
  
 GOOGLE_APPLICATION_CREDENTIALS 
 = 
 "  KEY_PATH 
 
"

Replace KEY_PATH with the path of the JSON file that contains your credentials.

For example:

 export 
  
 GOOGLE_APPLICATION_CREDENTIALS 
 = 
 "/home/user/Downloads/service-account-file.json"

Example:Windows

For PowerShell:

 $env 
:GOOGLE_APPLICATION_CREDENTIALS = 
 "  KEY_PATH 
 
"

Replace KEY_PATH with the path of the JSON file that contains your credentials.

For example:

 $env 
:GOOGLE_APPLICATION_CREDENTIALS = 
 "C:\Users\username\Downloads\service-account-file.json"

For command prompt:

 set 
  
 GOOGLE_APPLICATION_CREDENTIALS 
 = 
  KEY_PATH

Replace KEY_PATH with the path of the JSON file that contains your credentials.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Go to project selector

Verify that billing is enabled for your Google Cloud project .

Create a service account:

In the Google Cloud console, go to the Create service account page.
Go to Create service account
Select your project.
In the Service account name field, enter a name. The Google Cloud console fills in the Service account ID field based on this name.

In the Service account description field, enter a description. For example, Service account for quickstart .
Click Create and continue .
Grant the Project > Owner role to the service account.

To grant the role, find the Select a role list, then select Project > Owner .

Note : The Role field affects which resources the service account can access in your project. You can revoke these roles or grant additional roles later. In production environments, do not grant the Owner, Editor, or Viewer roles. Instead, grant a predefined role or custom role that meets your needs.
Click Continue .
Click Done to finish creating the service account.

Do not close your browser window. You will use it in the next step.

Create a service account key:

In the Google Cloud console, click the email address for the service account that you created.
Click Keys .
Click Add key , and then click Create new key .
Click Create . A JSON key file is downloaded to your computer.
Click Close .

Example:Linux or macOS

 export 
  
 GOOGLE_APPLICATION_CREDENTIALS 
 = 
 "  KEY_PATH 
 
"

Replace KEY_PATH with the path of the JSON file that contains your credentials.

For example:

 export 
  
 GOOGLE_APPLICATION_CREDENTIALS 
 = 
 "/home/user/Downloads/service-account-file.json"

Example:Windows

For PowerShell:

 $env 
:GOOGLE_APPLICATION_CREDENTIALS = 
 "  KEY_PATH 
 
"

Replace KEY_PATH with the path of the JSON file that contains your credentials.

For example:

 $env 
:GOOGLE_APPLICATION_CREDENTIALS = 
 "C:\Users\username\Downloads\service-account-file.json"

For command prompt:

 set 
  
 GOOGLE_APPLICATION_CREDENTIALS 
 = 
  KEY_PATH

Replace KEY_PATH with the path of the JSON file that contains your credentials.

Enable the Cloud Healthcare API.

Enable the API

Install the Google Cloud CLI.
If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity .
To initialize the gcloud CLI, run the following command:
```
gcloud  
init
```

Set up permissions

To use the features in this guide, you must have the healthcare.nlpservice.analyzeEntities permission , which is included in the healthcare.nlpServiceViewer role .

To assign this role, run the gcloud projects add-iam-policy-binding command:

gcloud  
projects  
add-iam-policy-binding  
 PROJECT_ID 
  
 \ 
  
--member  
serviceAccount: SERVICE_ACCOUNT_ID 
  
 \ 
  
--role  
roles/healthcare.nlpServiceViewer

Extract entities, relations, and contextual attributes

The Healthcare Natural Language API uses context-aware models to extract medical entities, relations, and contextual attributes. Each text entity is extracted into a medical dictionary entry. To extract this level of medical insights from medical text, use the projects.locations.services.nlp.analyzeEntities method.

To include the SNOMED CT licensed vocabulary in your entity mentions, see Include licensed vocabularies .

To extract medical insights from medical text using the Healthcare Natural Language API, make a POST request and specify the target text in the documentContent field. The maximum size of the medical text is 20,000 Unicode characters.

The following samples show how to use the analyzeEntities method to extract medical insights from the medical text "Insulin regimen 5 units IV will be administered for diabetes.".

REST

Before using any of the request data, make the following replacements:

PROJECT_ID : the ID of your Google Cloud project
LOCATION : the dataset location

Request JSON body:

{
  "documentContent": "Insulin regimen 5 units IV will be administered for diabetes."
}

To send your request, choose one of these options:

curl

Note: The following command assumes that you have logged in to the gcloud CLI with your user account by running gcloud init or gcloud auth login , or by using Cloud Shell , which automatically logs you into the gcloud CLI . You can check the currently active account by running gcloud auth list .

Save the request body in a file named request.json . Run the following command in the terminal to create or overwrite this file in the current directory:

cat > request.json << 'EOF'
{
  "documentContent": "Insulin regimen 5 units IV will be administered for diabetes."
}
EOF

Then execute the following command to send your REST request:

curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-d @request.json \
"https://healthcare.googleapis.com/v1/projects/ PROJECT_ID 
/locations/ LOCATION 
/services/nlp:analyzeEntities"

PowerShell

Note: The following command assumes that you have logged in to the gcloud CLI with your user account by running gcloud init or gcloud auth login . You can check the currently active account by running gcloud auth list .

Save the request body in a file named request.json . Run the following command in the terminal to create or overwrite this file in the current directory:

@'
{
  "documentContent": "Insulin regimen 5 units IV will be administered for diabetes."
}
'@  | Out-File -FilePath request.json -Encoding utf8

Then execute the following command to send your REST request:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
-Method POST `
-Headers $headers `
-ContentType: "application/json" `
-InFile request.json `
-Uri "https://healthcare.googleapis.com/v1/projects/ PROJECT_ID 
/locations/ LOCATION 
/services/nlp:analyzeEntities" | Select-Object -Expand Content

If the request is successful, the response includes the following information:

Recognized medical knowledge entities
Functional features
Relations between the recognized entities
Contextual attributes
Mappings of the medical knowledge entities into standard terminologies

For a list of supported entity, attribute, and relation types, see the Healthcare Natural Language API features .

The following response identifies Therapeutic Insulin, the entity with code C581 in the NCI terminology system, as the medication. The response also includes the confidence score assigned to the response. For more information about the response fields, see the analyzeEntities documentation.

Response

{
  "entityMentions": [
    {
      "mentionId": "1",
      "type": "MEDICINE",
      "text": {
        "content": "Insulin regimen",
        "beginOffset": 0
      },
      "linkedEntities": [
        {
          "entityId": "UMLS/C0021641"
        },
        {
          "entityId": "UMLS/C0795635"
        },
        {
          "entityId": "UMLS/C1533581"
        },
        {
          "entityId": "UMLS/C3537244"
        },
        {
          "entityId": "UMLS/C3714501"
        }
      ],
      "temporalAssessment": {
        "value": "UPCOMING",
        "confidence": 0.95375925302505493
      },
      "certaintyAssessment": {
        "value": "LIKELY",
        "confidence": 0.618984580039978
      },
      "subject": {
        "value": "PATIENT",
        "confidence": 0.99964696168899536
      },
      "confidence": 0.62128835916519165
    },
    {
      "mentionId": "2",
      "type": "MED_DOSE",
      "text": {
        "content": "5 units",
        "beginOffset": 16
      },
      "confidence": 0.78806477785110474
    },
    {
      "mentionId": "3",
      "type": "MED_ROUTE",
      "text": {
        "content": "IV",
        "beginOffset": 24
      },
      "linkedEntities": [
        {
          "entityId": "UMLS/C0348016"
        }
      ],
      "confidence": 0.8927428126335144
    },
    {
      "mentionId": "4",
      "type": "PROBLEM",
      "text": {
        "content": "diabetes",
        "beginOffset": 52
      },
      "linkedEntities": [
        {
          "entityId": "UMLS/C0011847"
        },
        {
          "entityId": "UMLS/C0011849"
        },
        {
          "entityId": "UMLS/C0241863"
        }
      ],
      "temporalAssessment": {
        "value": "CURRENT",
        "confidence": 0.91680806875228882
      },
      "certaintyAssessment": {
        "value": "LIKELY",
        "confidence": 0.98018729686737061
      },
      "subject": {
        "value": "PATIENT",
        "confidence": 0.99965417385101318
      },
      "confidence": 0.99518013000488281
    }
  ],
  "entities": [
    {
      "entityId": "UMLS/C0011847",
      "preferredTerm": "Diabetes",
      "vocabularyCodes": [
        "ICD10CM/E11",
        "LNC/LA10529-8",
        "LNC/LP128793-9",
        "LNC/MTHU040702",
        "MTH/NOCODE",
        "OMIM/MTHU050182"
      ]
    },
    {
      "entityId": "UMLS/C0011849",
      "preferredTerm": "Diabetes Mellitus",
      "vocabularyCodes": [
        "HPO/HP:0000819",
        "ICD10CM/E08-E13",
        "ICD9CM/250",
        "LNC/LA14291-1",
        "LNC/LA27539-8",
        "LNC/LP74722-7",
        "LNC/MTHU020781",
        "MEDLINEPLUS/4",
        "MSH/D003920",
        "MTH/NOCODE",
        "MTH/U000263",
        "NCI/C2985",
        "OMIM/MTHU036798"
      ]
    },
    {
      "entityId": "UMLS/C0021641",
      "preferredTerm": "Insulin",
      "vocabularyCodes": [
        "FMA/83365",
        "LNC/LA15805-7",
        "LNC/LP14676-8",
        "LNC/LP16325-0",
        "LNC/LP32542-0",
        "LNC/LP70329-5",
        "LNC/MTHU002108",
        "LNC/MTHU019392",
        "MSH/D007328",
        "MTH/NOCODE"
      ]
    },
    {
      "entityId": "UMLS/C0241863",
      "preferredTerm": "Diabetic",
      "vocabularyCodes": [
        "LNC/LA26134-9"
      ]
    },
    {
      "entityId": "UMLS/C0348016",
      "preferredTerm": "Intravenous",
      "vocabularyCodes": [
        "LNC/LA9437-0",
        "LNC/LP32453-0",
        "MTH/NOCODE",
        "NCI/C13346"
      ]
    },
    {
      "entityId": "UMLS/C0795635",
      "preferredTerm": "insulin, regular, human",
      "vocabularyCodes": [
        "LNC/LP17001-6",
        "MSH/D061386",
        "MTH/NOCODE",
        "NCI/C29125",
        "RXNORM/253182",
        "VANDF/4017559",
        "VANDF/4017569",
        "VANDF/4019786"
      ]
    },
    {
      "entityId": "UMLS/C1533581",
      "preferredTerm": "Therapeutic Insulin",
      "vocabularyCodes": [
        "MTH/NOCODE",
        "NCI/C581"
      ]
    },
    {
      "entityId": "UMLS/C3537244",
      "preferredTerm": "Insulins",
      "vocabularyCodes": [
        "MSH/D061385",
        "MTH/NOCODE"
      ]
    },
    {
      "entityId": "UMLS/C3714501",
      "preferredTerm": "Insulin Drug Class",
      "vocabularyCodes": [
        "MTH/NOCODE",
        "VANDF/4021631"
      ]
    }
  ],
  "relationships": [
    {
      "subjectId": "1",
      "objectId": "2",
      "confidence": 0.99964696168899536
    },
    {
      "subjectId": "1",
      "objectId": "3",
      "confidence": 0.99964696168899536
    },
    {
      "subjectId": "4",
      "objectId": "1",
      "confidence": 0.68552839756011963
    }
  ]
}

Use the Healthcare Natural Language API Stay organized with collections Save and categorize content based on your preferences.

Overview

Available locations

Enable the Healthcare Natural Language API

Set up permissions

Extract entities, relations, and contextual attributes

REST

curl

PowerShell

Response

Include licensed vocabularies

REST

curl

PowerShell

Response

Extract output as a FHIR R4 bundle

REST

curl

PowerShell

Response

Use the Healthcare Natural Language API