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:
- 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.
-
Make sure 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.
- 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. -
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
-
Make sure 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.
- 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. -
Enable the Cloud Healthcare API.
- Install the Google Cloud CLI.
-
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 projectLOCATION
: 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 valueSNOMEDCT_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 projectLOCATION
: 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
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 projectLOCATION
: 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
- 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.