Method: nlp.analyzeEntities

Full name: projects.locations.services.nlp.analyzeEntities

Analyze heathcare entity in a document. Its response includes the recognized entity mentions and the relationships between them. nlp.analyzeEntities uses context aware models to detect entities. This method can only analyze documents written in English.

HTTP request

POST https://healthcare.googleapis.com/v1beta1/{nlpService=projects/*/locations/*/services/nlp}:analyzeEntities

The URL uses gRPC Transcoding syntax.

Path parameters

Parameters
nlpService

string

The resource name of the service of the form: "projects/{projectId}/locations/{locationId}/services/nlp".

Request body

The request body contains data with the following structure:

JSON representation 
{
  "documentContent": string,
  "licensedVocabularies": [
    enum(LicensedVocabulary)
  ],
  "alternativeOutputFormat": enum(AlternativeOutputFormat)
}
Fields
documentContent

string

documentContent is a document to be annotated.
licensedVocabularies[]

enum(LicensedVocabulary)

A list of licensed vocabularies to use in the request, in addition to the default unlicensed vocabularies.
alternativeOutputFormat

enum(AlternativeOutputFormat)

Optional. Alternative output format to be generated based on the results of analysis.

Response body

Includes recognized entity mentions and relationships between them.

If successful, the response body contains data with the following structure:

JSON representation 
{
  "entityMentions": [
    {
      object(EntityMention)
    }
  ],
  "entities": [
    {
      object(Entity)
    }
  ],
  "relationships": [
    {
      object(EntityMentionRelationship)
    }
  ],

  // Union field alternative_output_format can be only one of the following:
  "fhirBundle": string
  // End of list of possible types for union field alternative_output_format.
}
Fields
entityMentions[]

object(EntityMention)

The entityMentions field contains all the annotated medical entities that were mentioned in the provided document.
entities[]

object(Entity)

The union of all the candidate entities that the entityMentions in this response could link to. These are UMLS concepts or normalized mention content.
relationships[]

object(EntityMentionRelationship)

relationships contains all the binary relationships that were identified between entity mentions within the provided document.
Union field alternative_output_format. The alternative supported format if the config was included in the request. alternative_output_format can be only one of the following:
fhirBundle

string

The FHIR bundle (R4) that includes all the entities, the entity mentions, and the relationships in JSON format.

Authorization scopes

Requires one of the following OAuth scopes:

  • https://www.googleapis.com/auth/cloud-healthcare
  • https://www.googleapis.com/auth/cloud-platform

For more information, see the Authentication Overview.

LicensedVocabulary

Predefined list of available licensed vocabularies

Enums
LICENSED_VOCABULARY_UNSPECIFIED No licensed vocabulary specified.
ICD10CM ICD-10-CM vocabulary
SNOMEDCT_US SNOMED CT (US version) vocabulary

AlternativeOutputFormat

Predefined list of available alternative output formats

Enums
ALTERNATIVE_OUTPUT_FORMAT_UNSPECIFIED No alternative output format is specified.
FHIR_BUNDLE FHIR bundle output.

EntityMention

An entity mention in the document.

JSON representation 
{
  "mentionId": string,
  "type": string,
  "text": {
    object(TextSpan)
  },
  "linkedEntities": [
    {
      object(LinkedEntity)
    }
  ],
  "temporalAssessment": {
    object(Feature)
  },
  "certaintyAssessment": {
    object(Feature)
  },
  "subject": {
    object(Feature)
  },
  "confidence": number,
  "additionalInfo": [
    {
      object(Feature)
    }
  ]
}
Fields
mentionId

string

mentionId uniquely identifies each entity mention in a single response.
type

string

The semantic type of the entity: UNKNOWN_ENTITY_TYPE, ALONE, ANATOMICAL_STRUCTURE, ASSISTED_LIVING, BF_RESULT, BM_RESULT, BM_UNIT, BM_VALUE, BODY_FUNCTION, BODY_MEASUREMENT, COMPLIANT, DOESNOT_FOLLOWUP, FAMILY, FOLLOWSUP, LABORATORY_DATA, LAB_RESULT, LAB_UNIT, LAB_VALUE, MEDICAL_DEVICE, MEDICINE, MED_DOSE, MED_DURATION, MED_FORM, MED_FREQUENCY, MED_ROUTE, MED_STATUS, MED_STRENGTH, MED_TOTALDOSE, MED_UNIT, NON_COMPLIANT, OTHER_LIVINGSTATUS, PROBLEM, PROCEDURE, PROCEDURE_RESULT, PROC_METHOD, REASON_FOR_NONCOMPLIANCE, SEVERITY, SUBSTANCE_ABUSE, UNCLEAR_FOLLOWUP.
text

object(TextSpan)

text is the location of the entity mention in the document.
linkedEntities[]

object(LinkedEntity)

linkedEntities are candidate ontological concepts that this entity mention may refer to. They are sorted by decreasing confidence.
temporalAssessment

object(Feature)

How this entity mention relates to the subject temporally. Its value is one of: CURRENT, CLINICAL_HISTORY, FAMILY_HISTORY, UPCOMING, ALLERGY
certaintyAssessment

object(Feature)

The certainty assessment of the entity mention. Its value is one of: LIKELY, SOMEWHAT_LIKELY, UNCERTAIN, SOMEWHAT_UNLIKELY, UNLIKELY, CONDITIONAL
subject

object(Feature)

The subject this entity mention relates to. Its value is one of: PATIENT, FAMILY_MEMBER, OTHER
confidence

number

The model's confidence in this entity mention annotation. A number between 0 and 1.
additionalInfo[]

object(Feature)

Additional information about the entity mention. For example, for an entity mention of type DATE this can be its more specific date types from the following list: 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

TextSpan

A span of text in the provided document.

JSON representation 
{
  "content": string,
  "beginOffset": integer
}
Fields
content

string

The original text contained in this span.
beginOffset

integer

The unicode codepoint index of the beginning of this span.

LinkedEntity

EntityMentions can be linked to multiple entities using a LinkedEntity message lets us add other fields, e.g. confidence.

JSON representation 
{
  "entityId": string
}
Fields
entityId

string

entityId is a concept unique identifier. These are prefixed by a string that identifies the entity coding system, followed by the unique identifier within that system. For example, "UMLS/C0000970". This also supports ad hoc entities, which are formed by normalizing entity mention content.

Feature

A feature of an entity mention.

JSON representation 
{
  "value": string,
  "confidence": number
}
Fields
value

string

The value of this feature annotation. Its range depends on the type of the feature.
confidence

number

The model's confidence in this feature annotation. A number between 0 and 1.

Entity

The candidate entities that an entity mention could link to.

JSON representation 
{
  "entityId": string,
  "preferredTerm": string,
  "vocabularyCodes": [
    string
  ]
}
Fields
entityId

string

entityId is a first class field entityId uniquely identifies this concept and its meta-vocabulary. For example, "UMLS/C0000970".
preferredTerm

string

preferredTerm is the preferred term for this concept. For example, "Acetaminophen". For ad hoc entities formed by normalization, this is the most popular unnormalized string.
vocabularyCodes[]

string

Vocabulary codes are first-class fields and differentiated from the concept unique identifier (entityId). vocabularyCodes contains the representation of this concept in particular vocabularies, such as ICD-10, SNOMED-CT and RxNORM. These are prefixed by the name of the vocabulary, followed by the unique code within that vocabulary. For example, "RXNORM/A10334543".

EntityMentionRelationship

Defines directed relationship from one entity mention to another.

JSON representation 
{
  "subjectId": string,
  "objectId": string,
  "confidence": number
}
Fields
subjectId

string

subjectId is the id of the subject entity mention.
objectId

string

objectId is the id of the object entity mention.
confidence

number

The model's confidence in this annotation. A number between 0 and 1.