<!-- BusyBot node reference — https://busybot.net/tools/google-cloud-natural-language/ -->

> Node: Google Cloud Natural Language (`google_cloud_natural_language`) · Action · v1
> Category: AI · Credentials: Google Cloud Natural Language OAuth2 API (`googleCloudNaturalLanguageOAuth2Api`)
> Updated: 2026-08-16

# Google Cloud Natural Language

> Analyze document sentiment using Google Cloud Natural Language.

## Overview

Google Cloud Natural Language tool for analyzing document sentiment. Supports both inline text content and Google Cloud Storage URIs as input sources. Returns overall document sentiment and per-sentence sentiment scores and magnitudes.

**Category:** AI  
**Tool Name:** `google_cloud_natural_language`  
**Version:** 1

**Appearance:** Icon: `lucide-Brain` | Color: `#4285F4`

## Node Type

**Action** — processes input items and produces output

## Input / Output

| Direction | Port(s) |
|-----------|--------|
| Input | `Input` |
| Output | `Output`, `Error` |

## Credentials

This tool requires **Google Cloud Natural Language OAuth2 API** credentials.
See the [Credentials Guide](https://busybot.net/credentials/google-cloud-natural-language-oauth2-api/) for setup instructions.

### Resources

| Resource | Value |
|----------|-------|
| Document | `document` |

### Operations

| Operation | Value | Description |
|-----------|-------|-------------|
| Document: Analyze Sentiment | `analyzeSentiment` | Analyze sentiment of a document |

### Parameters

#### Document: Analyze Sentiment

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Source | `options` | Yes | `content` | The source of the document: a string containing the content or a Google Cloud Storage URI. |
| | | | | Options: `content`, `gcsContentUri` (Google Cloud Storage URI) |
| Content | `string` | Yes | — | The content of the input in string format. Cloud audit logging exempt since it is based on user data. _(shown when Source is `content`)_ |
| Google Cloud Storage URI | `string` | Yes | — | The Google Cloud Storage URI where the file content is located. This URI must be of the form: gs://bucket_name/object_name. _(shown when Source is `gcsContentUri`)_ |
| Options | `collection` | No | `{}` | — |
| — Document Type | `options` | No | `PLAIN_TEXT` | The type of input document. |
| | | | | Options: `HTML`, `PLAIN_TEXT` |
| — Encoding Type | `options` | No | `UTF16` | The encoding type used by the API to calculate sentence offsets. |
| | | | | Options: `NONE`, `UTF8`, `UTF16`, `UTF32` |
| — Language | `options` | No | `en` | The language of the document (if not specified, the language is automatically detected). Both ISO and BCP-47 language codes are accepted. |
| | | | | Options: `ar` (Arabic), `zh` (Chinese (Simplified)), `zh-Hant` (Chinese (Traditional)), `nl` (Dutch), `en` (English), `fr` (French), `de` (German), `id` (Indonesian), `it` (Italian), `ja` (Japanese), `ko` (Korean), `pt` (Portuguese (Brazilian & Continental)), `es` (Spanish), `th` (Thai), `tr` (Turkish), `vi` (Vietnamese) |

#### All Operations

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Authentication | `options` | No | `oAuth2` | Authentication method to use. |
| | | | | Options: `oAuth2` (OAuth2 (recommended)), `serviceAccount` |
| Google Account | `credential` | No | — | Connect or select your Google account. _(shown when Authentication is `oAuth2`)_ |
| Service Account Email | `string` | Yes | — | The email address of the Google service account. _(shown when Authentication is `serviceAccount`)_ |
| Private Key | `string` | Yes | — | The private key from the service account JSON key file. _(shown when Authentication is `serviceAccount`)_ |
| Max Concurrency | `number` | No | `10` | Maximum number of items to process concurrently. |

## Output Data

One output item per input item. The sentiment analysis response is **merged onto the input item JSON**, so the fields the item already carried stay addressable downstream. Binary data is **not** forwarded — attach files after this node, not before it.

The response is passed through exactly as the Google Cloud Natural Language API returns it: the overall document sentiment (a score and a magnitude), the per-sentence breakdown with a score and magnitude for each sentence, and the language the document was analysed in. Run the node once and inspect the output item to see the exact key names before you write expressions against it.

A sentiment **score** runs from -1 (negative) to 1 (positive). A **magnitude** is unbounded and grows with the amount of emotional content, so a long mixed document can have a score near zero and a high magnitude.

## Usage Examples

- Analyze sentiment of a customer review
- Determine whether feedback is positive or negative
- Get per-sentence sentiment scores for a document
- Analyze sentiment of text stored in Google Cloud Storage
- Classify text as positive, neutral, or negative

## Example Configuration

Analyse the sentiment of text carried on the item:

```json
{
  "type": "google_cloud_natural_language",
  "parameters": {
    "resource": "document",
    "operation": "analyzeSentiment",
    "source": "content",
    "content": "{{ $json.review }}"
  }
}
```

Analyse a document stored in Google Cloud Storage, in Spanish:

```json
{
  "type": "google_cloud_natural_language",
  "parameters": {
    "resource": "document",
    "operation": "analyzeSentiment",
    "source": "gcsContentUri",
    "gcsContentUri": "gs://my-bucket/documents/review.txt",
    "options": {
      "documentType": "PLAIN_TEXT",
      "encodingType": "UTF16",
      "language": "es"
    }
  }
}
```

Analyse an HTML document and cap how many items run at once:

```json
{
  "type": "google_cloud_natural_language",
  "parameters": {
    "resource": "document",
    "operation": "analyzeSentiment",
    "source": "content",
    "content": "{{ $json.html }}",
    "options": {
      "documentType": "HTML",
      "encodingType": "UTF8",
      "language": "en"
    },
    "maxConcurrency": 5
  }
}
```

### Error Handling

| Mode | Behavior |
|------|----------|
| **stop** | Halts workflow on first error |
| **continue** | Skips failed items, passes successful ones through |
| **errorPort** | Routes failed items to Error output port |

## Tips

Analyze text sentiment using the Google Cloud Natural Language API.

### Behavior notes

- **Pick the right document type.** Choose `HTML` when the content is markup and the API will ignore the tags; leave it on `PLAIN_TEXT` and the tags are analysed as words.
- **Encoding type only affects offsets.** It decides how the character offsets in the per-sentence results are counted, not how the text is read. Leave it at `UTF16` unless a downstream node slices the original string using those offsets.
- **Leave Language unset to auto-detect.** Set it explicitly only when you already know the language — a wrong value degrades the scores.
- **One item per document.** To score many documents, produce one item per document upstream (a Split Out node works well) rather than concatenating them into one string.