Caution: The Healthcare Natural Language API is deprecated and will be shut down on May 27, 2026. For more information, seeDeprecations.

The Healthcare Natural Language API is a part of the Cloud Healthcare API thatuses natural language models to extract healthcare information from medicaltext.

This conceptual guide explains the basics of using theHealthcare Natural Language API, including:

• The types of requests you can make to the Healthcare Natural Language API
• How to construct requests to the Healthcare Natural Language API
• How to handle responses from the Healthcare Natural Language API

Overview

The Healthcare Natural Language API extracts healthcare information frommedical text. This healthcare information can include:

• Medical concepts, such as medications, procedures, and medical conditions
• Functional features, such as temporal relationships, subjects, and certaintyassessments
• Relations, such as side effects and medication dosage

Note: You don't need to create a dataset in the Cloud Healthcare API to usethe Healthcare Natural Language API.

Choosing between the Healthcare Natural Language API and AutoML Entity Extraction for Healthcare

The Healthcare Natural Language API offers pre-trained natural language models toextract medical concepts and relationships from medical text. TheHealthcare Natural Language API maps text into a predefined set ofmedical knowledge categories.

AutoML Entity Extraction for Healthcare lets you create a customentity extraction model trained using your own annotated medical text and usingyour own categories. For more information, see theAutoML Entity Extraction for Healthcare documentation.

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

Healthcare Natural Language API features

The Healthcare Natural Language API inspects medical text for medical concepts andrelations. You perform entity analysis using theanalyzeEntitiesmethod.

Entity analysis requests

The Healthcare Natural Language API is a REST API and consists of JSON requestsand responses. The following sections show how to extract different medicalinsights from a given medical text:

• Extract entities, relations, and contextual attributes
• Include licensed vocabularies
• Extract output as a FHIR R4 bundle

The entity analysis request contains the following fields:

• documentContent:The data for the request, which consists of medical text. The maximum size ofthe medical text is 20,000 Unicode characters.
• licensedVocabularies[]:Optional. TheSNOMED CT vocabulary. Available only for US users.
• alternativeOutputFormat:Optional. The FHIR bundle format.

Entity analysis response fields

The entity analysis returns a set of detected medical knowledge mentions, medicalconcepts, and relations between medical knowledge mentions, including thefollowing:

• entityMentions: occurrences of medical knowledge entities in the sourcemedical text. Each entity mention has the following fields:

  • mentionId: a unique identifier for an entity mention in the response.
  • type: themedical knowledge category ofthe entity mention.
  • text: consists of thetextContent field, and describes the excerpt ofthe medical text containing the entity mention, andoffset, the locationof the entity mention in the source medical text.
  • temporalAssessment: specifies how the linked entity relates to theentity mention, one ofCURRENT,CLINICAL_HISTORY,FAMILY_HISTORY,UPCOMING, orOTHER.
  • certaintyAssessment: the negation or qualification of the medicalconcept, one ofLIKELY,SOMEWHAT_LIKELY,UNCERTAIN,SOMEWHAT_UNLIKELY,UNLIKELY, orCONDITIONAL.
  • subject: specifies the subject that the medical concept relates to,one ofPATIENT,FAMILY_MEMBER, orOTHER.
  • linkedEntities: a list of medical concepts that might be related to thisentity mention. Linked entities specify theentityId, whichlinks a medical concept to an an entity inentities.

• entities: describes the medical concepts from the linked entities fields.Each entity is described using the following fields:

  • entityId: a unique identifier from thelinkedEntities field.
  • preferredTerm: a preferred term for the medical concept.
  • vocabularyCodes: the representation of the medical concept insupportedmedical vocabularies.

• relationships: define directed relationships between entity mentions.In the sample, the subject of the relationship is "Insulin regimen human" andthe object of the relationship is "5 units".

• confidence: an indication of the model's confidence in the relationship as anumber between 0 and 1.

Apart from the listed fields, the response might also contain theadditionalInfofield, which states any additional description about the entity mention type.SeeAdditional information.

Supported languages

The Healthcare Natural Language API only supports extracting healthcare information from English text.

Supported medical vocabularies

The Healthcare Natural Language API supports the following medical vocabularies:

• Foundational Model of Anatomy
• Gene Ontology
• HUGO Gene Nomenclature Committee
• Human Phenotype Ontology
• ICD-10 Procedure Coding System
• ICD-10-CM
• ICD-9-CM
• LOINC
• MeSH
• MedlinePlus Health Topics
• Metathesaurus Names
• NCBI Taxonomy
• NCI Thesaurus
• National Drug File
• Online Mendelian Inheritance in Man
• RXNORM
• SNOMED CT (available for US users only)

Supported medical knowledge categories

The Healthcare Natural Language API assigns a medical knowledge category to theentityMentions.type field.A list of supported medical knowledge categories is as follows. The entity mention types that belong to the oncology, social determinants of health (SDOH), and protected health information (PHI) groups are only available inPreview:

Group	Medical knowledge category	Description
General	ANATOMICAL_STRUCTURE	A complex part of the human body, such as cells, organs, and systems.
	BODY_FUNCTION	A function carried out by the human body.
	BF_RESULT	The result of a body function.
	BODY_MEASUREMENT	A normal measurement of the human body, such as vital signs, obtained without any complex tests or procedures using basic instruments, such as a thermometer or a stethoscope.
	BM_RESULT	The result of a body measurement.
	BM_UNIT	The unit for a body measurement.
	BM_VALUE	The value of a body measurement.
	LABORATORY_DATA	The results of testing a bodily sample.
	LAB_RESULT	A qualitative description of laboratory data, such as "increased", "decreased", "positive", or "negative".
	LAB_VALUE	The value of an instance of the laboratory data.
	LAB_UNIT	The unit of measurement for the laboratory value.
	MEDICAL_DEVICE	A physical or virtual instrument.
	MEDICINE	A drug or other preparation for the treatment or prevention of a disease.
	MED_DOSE	A dose of a medication.
	MED_DURATION	The period of administration of a medication.
	MED_FORM	The physical characteristics of a specific medication.
	MED_FREQUENCY	The frequency at which a medication is taken.
	MED_ROUTE	A location in the body where a medication is administered.
	MED_STATUS	The status of an existing medication, such as "continue", "start", "restart", "stop", "switch", "increase", and "decrease".
	MED_STRENGTH	The amount of active ingredient in a dose of a medication.
	MED_UNIT	The unit of measurement for the active ingredient in a medication.
	MED_TOTALDOSE	The quantity of medication to take at one time.
	PROBLEM	A medical condition, including findings and diseases.
	PROCEDURE	A diagnostic or treatment procedure.
	PROCEDURE_RESULT	The results of a procedure.
	PROC_METHOD	The method used to conduct a procedure.
	SEVERITY	The severity of the medical condition.
	SUBSTANCE_ABUSE	A description of abuse of a psychoactive substance.
Oncology(Preview)	CLINICAL_STATUS	The status of a cancer case such as "active", "recurring", "relapsing", and "resolved".
	DATE	A date annotation, such as the date of diagnosis, date of procedure, or date of a radiation treatment. It extracts all the elements of a date and might not include the year.
	DIMENSIONS	The measurements of a tumor, a mass, or an abnormal growth.
	GENE_STUDIED	The genes studied which directly or indirectly lead to tumor formation, such as BRCA1, p53, and ALK.
	HISTOLOGICAL_GRADE	A classification system to grade the appearance of a cancerous cell.
	LAB_SPECIMEN	Biological material collected from the body for testing or sampling.
	RADIATION_DOSAGE	The amount of radiation given to a patient.
	ONSET	A date annotation to represent the date when a patient first observed cancer-related problems.
	VARIATION_CODE	A code given to the specific genomic variant that's detected under a major coding system such asClinVar andHGVS.
Social determinants of health (SDoH) (Preview)	AGE	An age identifier. It includes phrases describing age, such as "looks younger than stated age", "middle-aged", "78 years old", or "teen". Note: HIPAA classifies the age of a person as PHI only when it's above 90. For more information, seeSummary of the HIPAA Privacy Rule.
	FAMILY	Phrases describing the patient's family structure or relatives, such as "married with two kids", "brother", "wife", "supportive parents", or "divorced".
	LIVING_SITUATION	Phrases describing the patient's living situation, such as "with roommates", "has 24/7 homecare nurse", or "moved recently".
	SOCIAL_IDENTITY	Phrases describing the patient's or the family's social identity including race, ethnicity, sexual orientation, religion, nationality, languages spoken or not spoken, or country of origin.
	PHYSICAL_APPEARANCE	Phrases describing the patient's or the family's most noticeable or evident physical trait, such as "scar on the right cheek", "Down's syndrome", "obese", or "left leg amputated".
	OCCUPATION	Phrases describing the patient's or family's occupation and employment status, such as "retired mother", "worked as a welder for 20 years", or "lost job last year".
Protected health information (PHI) (Preview)	PERSON_NAME	A generic name identifier for a person. Includes titles, such as "Dr.", "Mrs.", or "MD"
	ORGANIZATION_NAME	An identifier for a medical organization that collects PHI, such as a clinic, nursing home, or hospital.
	GENERIC_ID	A generic ID that identifies medical records, patients, doctors, hospitals, such as the patient's SSN, or a provider's number.
	LOCATION	A geographic location that might contain names and numbers for buildings, streets, cities, states, or ZIP code.
	PHONE_NUMBER	A number to indicate a phone number, fax number, or pager number.
	EMAIL_ADDRESS	An email address identifier.
	URL	A website's address.
	ZIPCODE	A ZIP code identifier.

Supported functional feature categories

The Healthcare Natural Language API can infer functional features, or attributes,of an entity mention from context. For example, in the statement"Kusuma's mother has diabetes", the condition "diabetes" has the functionalfeature ofsubjectFAMILY_MEMBER.

Temporal relationships

Temporal relationships, returned in thetemporalAssessment field, describehow this entity mention relates to the subject temporally.

The Healthcare Natural Language API supports the following temporal relationships:

• CURRENT
• CLINICAL_HISTORY
• FAMILY_HISTORY
• UPCOMING
• OTHER

Subjects

Subjects, returned in thesubject field, describe the individual the entitymention relates to.

The Healthcare Natural Language API supports the following subjects:

• PATIENT
• FAMILY_MEMBER
• OTHER

Certainty assessments

Certainty assessments, returned in thecertaintyAssessment field, describethe original note taker's confidence. For example, if the original notecontains "The patient has a sore throat", the certainty assessmentreturns aLIKELY value to indicate the note taker's confidence that itwas likely that the patient had a sore throat. If the original note contains "The patient doesnot have a sore throat", the certainty assessment returns anUNLIKELYvalue to indicate the note taker's confidence that it was unlikelythat the patient had a sore throat.

Certainty assessments can be one of the following values:

• LIKELY
• SOMEWHAT_LIKELY
• UNCERTAIN
• SOMEWHAT_UNLIKELY
• UNLIKELY
• CONDITIONAL

Additional information

TheadditionalInfo field provides additional details about an entitymention. For example, theadditionalInfo field for aDATE entity mention mightconsist of details about the type of the date, categorized as one of the following:

• ADMISSION_DATE
• CONSULTATION_DATE
• DISCHARGE_DATE
• SERVICE_DATE
• VISIT_DATE
• DIAGNOSIS_DATE
• MED_STARTED_DATE
• MED_ENDED_DATE
• NOTE_DATE
• PROCEDURE_DATE
• RADIATION_STARTED_DATE
• RADIATION_ENDED_DATE
• STAGE_DATE

Supported relationships between entity mentions

The Healthcare Natural Language API can infer relationships between entitymentions based on the surrounding medical text. In the response, the subject ofthe relationship is identified bysubjectId and the object of therelationship is identified byobjectId.

The Healthcare Natural Language API supports the following relationships betweenentity mentions:

Subject	Object
ANATOMICAL_STRUCTURE	MEDICAL_DEVICE
BODY_FUNCTION	BF_RESULT
BODY_MEASUREMENT	BM_RESULT
BODY_MEASUREMENT	BM_UNIT
BODY_MEASUREMENT	BM_VALUE
LABORATORY_DATA	LAB_RESULT
LABORATORY_DATA	LAB_UNIT
LABORATORY_DATA	LAB_VALUE
MEDICINE	MED_DOSE
MEDICINE	MED_DURATION
MEDICINE	MED_FORM
MEDICINE	MED_FREQUENCY
MEDICINE	MED_ROUTE
MEDICINE	MED_STATUS
MEDICINE	MED_STRENGTH
MEDICINE	MED_TOTALDOSE
MEDICINE	MED_UNIT
PROBLEM	ANATOMICAL_STRUCTURE
PROBLEM	MEDICINE
PROBLEM	PROCEDURE
PROBLEM	SEVERITY
PROCEDURE	ANATOMICAL_STRUCTURE
PROCEDURE	PROC_METHOD
PROCEDURE	PROCEDURE_RESULT
SUBSTANCE_ABUSE	SEVERITY

Healthcare Natural Language API output as a FHIR bundle

When you request theanalyzeEntities method with thealternativeOutputFormatfield set toFHIR_BUNDLE, the response includes the following JSON objects:

• The entity mentions, the entities, and the relationships
• A FHIR R4 bundle represented as a string, that includes all the entities, theentity mentions, and the relationships in JSON format

To create the FHIR R4 bundle, the Healthcare Natural Language API maps the entity mentions,entities, and relationships to FHIR resources and their elements. The followingtable lists some of these mappings.

Healthcare Natural Language API entity mentions	Medical Knowledge Category	FHIR R4 resources and elements
PROBLEM		Condition
PROBLEM		Condition.category
PROBLEM		Condition.status
PROBLEM	ANATOMICAL_STRUCTURE	Condition.bodySite
PROBLEM	ANATOMICAL_STRUCTURE	Condition.evidence
PROBLEM	SEVERITY	Condition.severity
PROCEDURE		Procedure
PROCEDURE		Procedure.status
PROCEDURE		Procedure.code
PROCEDURE	ANATOMICAL_STRUCTURE	Procedure.bodySite
PROCEDURE	MEDICAL_DEVICE	Procedure.usedCode
PROCEDURE	PROBLEM	Procedure.reasonReference
MEDICINE		MedicationStatement
MEDICINE		MedicationStatement.status
MEDICINE		MedicationStatement.medication
MEDICINE	PROBLEM	MedicationStatement.reasonReference
MEDICINE	MED_DOSE	MedicationStatement.dosage.doseAndRate.doseQuantity
MEDICINE	MED_FREQUENCY	MedicationStatement.dosage.text
MEDICINE	MED_ROUTE	MedicationStatement.dosage.route
MEDICINE	MED_STRENGTH	MedicationStatement.dosage.doseAndRate.doseQuantity
MEDICINE	MED_UNIT	MedicationStatement.dosage.doseAndRate.doseQuantity

To extract entities from text as a FHIR R4 bundle, seeExtract output as a FHIR R4 bundle.