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 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:

  1. 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.
  2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Go to project selector

  3. Make sure that billing is enabled for your Google Cloud project.

  4. Create a service account:

    1. In the Google Cloud console, go to the Create service account page.

      Go to Create service account
    2. Select your project.
    3. 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.

    4. Click Create and continue.
    5. Grant the Project > Owner role to the service account.

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

    6. Click Continue.
    7. Click Done to finish creating the service account.

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

  5. Create a service account key:

    1. In the Google Cloud console, click the email address for the service account that you created.
    2. Click Keys.
    3. Click Add key, and then click Create new key.
    4. Click Create. A JSON key file is downloaded to your computer.
    5. Click Close.
  6. 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.

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

    Go to project selector

  8. Make sure that billing is enabled for your Google Cloud project.

  9. Create a service account:

    1. In the Google Cloud console, go to the Create service account page.

      Go to Create service account
    2. Select your project.
    3. 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.

    4. Click Create and continue.
    5. Grant the Project > Owner role to the service account.

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

    6. Click Continue.
    7. Click Done to finish creating the service account.

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

  10. Create a service account key:

    1. In the Google Cloud console, click the email address for the service account that you created.
    2. Click Keys.
    3. Click Add key, and then click Create new key.
    4. Click Create. A JSON key file is downloaded to your computer.
    5. Click Close.
  11. 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.

  12. Enable the Cloud Healthcare API.

    Enable the API

  13. Install the Google Cloud CLI.
  14. 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

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

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.

Include licensed vocabularies

By default, Healthcare Natural Language API responses include the supported medical vocabularies.

You can include the SNOMED Clinical Terms, US Version (SNOMEDCT_US) vocabulary in the response if your request meets the following requirements:

  • The API request originates in the US.
  • The licensedVocabularies field in the request body has the value SNOMEDCT_US.

If you don't require the SNOMED CT vocabulary, then none of these restrictions apply.

The following sample shows how to include the SNOMED CT licensed vocabulary in the LicensedVocabularies object 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.",
  "licensedVocabularies": [
    "SNOMEDCT_US",
    "ICD10CM"
  ]
}

To send your request, choose one of these options:

curl

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.",
  "licensedVocabularies": [
    "SNOMEDCT_US",
    "ICD10CM"
  ]
}
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

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.",
  "licensedVocabularies": [
    "SNOMEDCT_US",
    "ICD10CM"
  ]
}
'@  | 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 vocabulary codes from the SNOMEDCT_US and ICD10CM licensed vocabularies. The output is the following and the requested licensed vocabulary codes are in bold:

Extract output as a FHIR R4 bundle

You can extract entities from text and map them to FHIR R4 resources and elements. The resulting FHIR R4 bundle includes all entities, entity mentions, and relationships in JSON format. For example, the Healthcare Natural Language API maps the base entity PROBLEM to the Condition FHIR R4 resource and the entity PROBLEM.ANATOMICAL_STRUCTURE to the Condition.bodySite FHIR element. For a list of other mappings, see Healthcare Natural Language API output as a FHIR bundle.

The following samples show how to extract medical insights from the medical text "Insulin regimen 5 units IV will be administered for diabetes." in a FHIR R4 bundle. For more information, see AlternativeOutputFormat object.

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.",
  "alternativeOutputFormat": "FHIR_BUNDLE"
}

To send your request, choose one of these options:

curl

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.",
  "alternativeOutputFormat": "FHIR_BUNDLE"
}
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

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.",
  "alternativeOutputFormat": "FHIR_BUNDLE"
}
'@  | 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 contains a JSON object with the following entries:
  • The recognized entity mentions with the entities and their relationships in a format similar to the output in Extract entities, relations, and contextual attributes.
  • A fhirBundle key containing a string-formatted FHIR Bundle resource. The FHIR bundle includes all the entities, the entity mentions, and the relationships in JSON format.