**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.

### HTTP request

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

The URL uses [gRPC Transcoding](https://google.aip.dev/127) 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(`https://docs.cloud.google.com/healthcare-api/docs/reference/rest/v1/projects.locations.services.nlp/analyzeEntities#LicensedVocabulary`) ], "alternativeOutputFormat": enum(`https://docs.cloud.google.com/healthcare-api/docs/reference/rest/v1/projects.locations.services.nlp/analyzeEntities#AlternativeOutputFormat`) } ``` |

| Fields ||
|---|---|
| `documentContent` | `string` documentContent is a document to be annotated. |
| `licensedVocabularies[]` | ``enum(`https://docs.cloud.google.com/healthcare-api/docs/reference/rest/v1/projects.locations.services.nlp/analyzeEntities#LicensedVocabulary`)`` A list of licensed vocabularies to use in the request, in addition to the default unlicensed vocabularies. |
| `alternativeOutputFormat` | ``enum(`https://docs.cloud.google.com/healthcare-api/docs/reference/rest/v1/projects.locations.services.nlp/analyzeEntities#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(`https://docs.cloud.google.com/healthcare-api/docs/reference/rest/v1/projects.locations.services.nlp/analyzeEntities#EntityMention`) } ], "entities": [ { object(`https://docs.cloud.google.com/healthcare-api/docs/reference/rest/v1/projects.locations.services.nlp/analyzeEntities#Entity`) } ], "relationships": [ { object(`https://docs.cloud.google.com/healthcare-api/docs/reference/rest/v1/projects.locations.services.nlp/analyzeEntities#EntityMentionRelationship`) } ], // The following is a list of mutually exclusive fields. At most one of the // fields will be set in a response: "fhirBundle": string // End of mutually exclusive fields. } ``` |

| Fields ||
|---|---|
| `entityMentions[]` | ``object(`https://docs.cloud.google.com/healthcare-api/docs/reference/rest/v1/projects.locations.services.nlp/analyzeEntities#EntityMention`)`` The `entityMentions` field contains all the annotated medical entities that were mentioned in the provided document. |
| `entities[]` | ``object(`https://docs.cloud.google.com/healthcare-api/docs/reference/rest/v1/projects.locations.services.nlp/analyzeEntities#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(`https://docs.cloud.google.com/healthcare-api/docs/reference/rest/v1/projects.locations.services.nlp/analyzeEntities#EntityMentionRelationship`)`` relationships contains all the binary relationships that were identified between entity mentions within the provided document. |
| The alternative supported format if the config was included in the request. The following is a list of mutually exclusive fields. At most one of the fields will be set in a response: ||
| `fhirBundle` | `string` The FHIR bundle ([`R4`](http://hl7.org/fhir/R4/bundle.html)) that includes all the entities, the entity mentions, and the relationships in JSON format. |
| End of mutually exclusive fields. ||

### 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](https://docs.cloud.google.com/docs/authentication#authorization-gcp).

## 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(`https://docs.cloud.google.com/healthcare-api/docs/reference/rest/v1/projects.locations.services.nlp/analyzeEntities#TextSpan`) }, "linkedEntities": [ { object(`https://docs.cloud.google.com/healthcare-api/docs/reference/rest/v1/projects.locations.services.nlp/analyzeEntities#LinkedEntity`) } ], "temporalAssessment": { object(`https://docs.cloud.google.com/healthcare-api/docs/reference/rest/v1/projects.locations.services.nlp/analyzeEntities#Feature`) }, "certaintyAssessment": { object(`https://docs.cloud.google.com/healthcare-api/docs/reference/rest/v1/projects.locations.services.nlp/analyzeEntities#Feature`) }, "subject": { object(`https://docs.cloud.google.com/healthcare-api/docs/reference/rest/v1/projects.locations.services.nlp/analyzeEntities#Feature`) }, "confidence": number } ``` |

| 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(`https://docs.cloud.google.com/healthcare-api/docs/reference/rest/v1/projects.locations.services.nlp/analyzeEntities#TextSpan`)`` text is the location of the entity mention in the document. |
| `linkedEntities[]` | ``object(`https://docs.cloud.google.com/healthcare-api/docs/reference/rest/v1/projects.locations.services.nlp/analyzeEntities#LinkedEntity`)`` linkedEntities are candidate ontological concepts that this entity mention may refer to. They are sorted by decreasing confidence. |
| `temporalAssessment` | ``object(`https://docs.cloud.google.com/healthcare-api/docs/reference/rest/v1/projects.locations.services.nlp/analyzeEntities#Feature`)`` How this entity mention relates to the subject temporally. Its value is one of: CURRENT, CLINICAL_HISTORY, FAMILY_HISTORY, UPCOMING, ALLERGY |
| `certaintyAssessment` | ``object(`https://docs.cloud.google.com/healthcare-api/docs/reference/rest/v1/projects.locations.services.nlp/analyzeEntities#Feature`)`` The certainty assessment of the entity mention. Its value is one of: LIKELY, SOMEWHAT_LIKELY, UNCERTAIN, SOMEWHAT_UNLIKELY, UNLIKELY, CONDITIONAL |
| `subject` | ``object(`https://docs.cloud.google.com/healthcare-api/docs/reference/rest/v1/projects.locations.services.nlp/analyzeEntities#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. |

## 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. |