0
# Google Cloud Language
1
2
A comprehensive Python client library for Google Cloud Natural Language API that provides natural language understanding technologies to developers. The library enables developers to perform advanced text analysis operations including sentiment analysis for determining emotional tone, entity recognition and analysis for identifying people, places, organizations and other entities, content classification for categorizing text into predefined categories, syntax analysis for understanding grammatical structure, and content moderation for detecting harmful content.
3
4
## Package Information
5
6
- **Package Name**: google-cloud-language
7
- **Package Type**: Python client library
8
- **Language**: Python
9
- **Installation**: `pip install google-cloud-language`
10
- **Documentation**: https://cloud.google.com/python/docs/reference/language/latest
11
- **License**: Apache 2.0
12
13
## Core Imports
14
15
```python
16
from google.cloud import language
17
```
18
19
For specific API versions:
20
21
```python
22
from google.cloud import language_v1
23
from google.cloud import language_v1beta2
24
from google.cloud import language_v2
25
```
26
27
Import specific client classes:
28
29
```python
30
from google.cloud.language import LanguageServiceClient
31
from google.cloud.language import LanguageServiceAsyncClient
32
```
33
34
Import for type annotations:
35
36
```python
37
from typing import Optional, Union, Sequence, Tuple, MutableMapping, MutableSequence
38
from google.api_core import gapic_v1
39
from google.api_core.retry import OptionalRetry
40
```
41
42
## Basic Usage
43
44
```python
45
from google.cloud import language
46
47
# Initialize the client
48
client = language.LanguageServiceClient()
49
50
# Create a document object
51
document = language.Document(
52
content="Google Cloud Natural Language API is amazing!",
53
type_=language.Document.Type.PLAIN_TEXT
54
)
55
56
# Analyze sentiment
57
response = client.analyze_sentiment(
58
request={"document": document}
59
)
60
61
# Access results
62
sentiment = response.document_sentiment
63
print(f"Sentiment score: {sentiment.score}")
64
print(f"Sentiment magnitude: {sentiment.magnitude}")
65
66
# Analyze entities
67
entities_response = client.analyze_entities(
68
request={"document": document}
69
)
70
71
for entity in entities_response.entities:
72
print(f"Entity: {entity.name}, Type: {entity.type_.name}")
73
```
74
75
## Architecture
76
77
The Google Cloud Language library is organized around three main API versions:
78
79
- **v1 (Stable)**: Complete feature set including sentiment analysis, entity analysis, entity sentiment analysis, syntax analysis, text classification, and content moderation
80
- **v1beta2 (Beta)**: Same features as v1, may include experimental capabilities
81
- **v2 (Simplified)**: Streamlined API focusing on core NLP tasks (sentiment, entities, classification, moderation) without syntax analysis
82
83
The library provides both synchronous and asynchronous clients, multiple transport options (gRPC, REST), and comprehensive error handling with Google Cloud authentication integration.
84
85
## Capabilities
86
87
### Client Management
88
89
Core client classes for interacting with the Google Cloud Natural Language API, supporting both synchronous and asynchronous operations with configurable transport layers.
90
91
```python { .api }
92
class LanguageServiceClient:
93
def __init__(self, *, credentials=None, transport=None, client_options=None, client_info=None): ...
94
95
class LanguageServiceAsyncClient:
96
def __init__(self, *, credentials=None, transport=None, client_options=None, client_info=None): ...
97
```
98
99
[Client Management](./client-management.md)
100
101
### Sentiment Analysis
102
103
Analyzes the emotional tone and attitude in text content, providing sentiment scores and magnitude measurements to understand how positive, negative, or neutral the text is.
104
105
```python { .api }
106
def analyze_sentiment(
107
self,
108
request: Optional[Union[AnalyzeSentimentRequest, dict]] = None,
109
*,
110
document: Optional[Document] = None,
111
encoding_type: Optional[EncodingType] = None,
112
retry: OptionalRetry = gapic_v1.method.DEFAULT,
113
timeout: Union[float, object] = gapic_v1.method.DEFAULT,
114
metadata: Sequence[Tuple[str, Union[str, bytes]]] = ()
115
) -> AnalyzeSentimentResponse: ...
116
```
117
118
[Sentiment Analysis](./sentiment-analysis.md)
119
120
### Entity Analysis
121
122
Identifies and extracts named entities (people, places, organizations, etc.) from text, providing detailed information about each entity including type, salience, and mentions within the text.
123
124
```python { .api }
125
def analyze_entities(
126
self,
127
request: Optional[Union[AnalyzeEntitiesRequest, dict]] = None,
128
*,
129
document: Optional[Document] = None,
130
encoding_type: Optional[EncodingType] = None,
131
retry: OptionalRetry = gapic_v1.method.DEFAULT,
132
timeout: Union[float, object] = gapic_v1.method.DEFAULT,
133
metadata: Sequence[Tuple[str, Union[str, bytes]]] = ()
134
) -> AnalyzeEntitiesResponse: ...
135
```
136
137
[Entity Analysis](./entity-analysis.md)
138
139
### Entity Sentiment Analysis (v1/v1beta2 only)
140
141
Combines entity recognition with sentiment analysis to determine the sentiment associated with each identified entity, useful for understanding opinions about specific people, places, or topics.
142
143
```python { .api }
144
def analyze_entity_sentiment(
145
self,
146
request: Optional[Union[AnalyzeEntitySentimentRequest, dict]] = None,
147
*,
148
document: Optional[Document] = None,
149
encoding_type: Optional[EncodingType] = None,
150
retry: OptionalRetry = gapic_v1.method.DEFAULT,
151
timeout: Union[float, object] = gapic_v1.method.DEFAULT,
152
metadata: Sequence[Tuple[str, Union[str, bytes]]] = ()
153
) -> AnalyzeEntitySentimentResponse: ...
154
```
155
156
[Entity Sentiment Analysis](./entity-sentiment-analysis.md)
157
158
### Syntax Analysis (v1/v1beta2 only)
159
160
Provides linguistic analysis including part-of-speech tagging, dependency parsing, and token-level information to understand the grammatical structure and linguistic properties of text.
161
162
```python { .api }
163
def analyze_syntax(
164
self,
165
request: Optional[Union[AnalyzeSyntaxRequest, dict]] = None,
166
*,
167
document: Optional[Document] = None,
168
encoding_type: Optional[EncodingType] = None,
169
retry: OptionalRetry = gapic_v1.method.DEFAULT,
170
timeout: Union[float, object] = gapic_v1.method.DEFAULT,
171
metadata: Sequence[Tuple[str, Union[str, bytes]]] = ()
172
) -> AnalyzeSyntaxResponse: ...
173
```
174
175
[Syntax Analysis](./syntax-analysis.md)
176
177
### Text Classification
178
179
Categorizes text documents into predefined classification categories, enabling automated content organization and filtering based on subject matter and themes.
180
181
```python { .api }
182
def classify_text(
183
self,
184
request: Optional[Union[ClassifyTextRequest, dict]] = None,
185
*,
186
document: Optional[Document] = None,
187
retry: OptionalRetry = gapic_v1.method.DEFAULT,
188
timeout: Union[float, object] = gapic_v1.method.DEFAULT,
189
metadata: Sequence[Tuple[str, Union[str, bytes]]] = ()
190
) -> ClassifyTextResponse: ...
191
```
192
193
[Text Classification](./text-classification.md)
194
195
### Content Moderation
196
197
Detects and flags potentially harmful, inappropriate, or unsafe content in text, providing moderation categories and confidence scores for content filtering applications.
198
199
```python { .api }
200
def moderate_text(
201
self,
202
request: Optional[Union[ModerateTextRequest, dict]] = None,
203
*,
204
document: Optional[Document] = None,
205
retry: OptionalRetry = gapic_v1.method.DEFAULT,
206
timeout: Union[float, object] = gapic_v1.method.DEFAULT,
207
metadata: Sequence[Tuple[str, Union[str, bytes]]] = ()
208
) -> ModerateTextResponse: ...
209
```
210
211
[Content Moderation](./content-moderation.md)
212
213
### Combined Analysis
214
215
Performs multiple types of analysis in a single API call for efficiency, allowing you to get sentiment, entities, syntax, classification, and moderation results simultaneously.
216
217
```python { .api }
218
def annotate_text(
219
self,
220
request: Optional[Union[AnnotateTextRequest, dict]] = None,
221
*,
222
document: Optional[Document] = None,
223
features: Optional[AnnotateTextRequest.Features] = None,
224
encoding_type: Optional[EncodingType] = None,
225
retry: OptionalRetry = gapic_v1.method.DEFAULT,
226
timeout: Union[float, object] = gapic_v1.method.DEFAULT,
227
metadata: Sequence[Tuple[str, Union[str, bytes]]] = ()
228
) -> AnnotateTextResponse: ...
229
```
230
231
[Combined Analysis](./combined-analysis.md)
232
233
## Core Types
234
235
### Request and Response Types
236
237
```python { .api }
238
class AnalyzeSentimentRequest:
239
document: Document
240
encoding_type: EncodingType
241
242
class AnalyzeSentimentResponse:
243
document_sentiment: Sentiment
244
language: str
245
sentences: MutableSequence[Sentence]
246
247
class AnalyzeEntitiesRequest:
248
document: Document
249
encoding_type: EncodingType
250
251
class AnalyzeEntitiesResponse:
252
entities: MutableSequence[Entity]
253
language: str
254
255
class AnalyzeEntitySentimentRequest:
256
document: Document
257
encoding_type: EncodingType
258
259
class AnalyzeEntitySentimentResponse:
260
entities: MutableSequence[Entity]
261
language: str
262
263
class AnalyzeSyntaxRequest:
264
document: Document
265
encoding_type: EncodingType
266
267
class AnalyzeSyntaxResponse:
268
sentences: MutableSequence[Sentence]
269
tokens: MutableSequence[Token]
270
language: str
271
272
class ClassifyTextRequest:
273
document: Document
274
classification_model_options: ClassificationModelOptions
275
276
class ClassifyTextResponse:
277
categories: MutableSequence[ClassificationCategory]
278
279
class ModerateTextRequest:
280
document: Document
281
282
class ModerateTextResponse:
283
moderation_categories: MutableSequence[ClassificationCategory]
284
285
class AnnotateTextRequest:
286
document: Document
287
features: AnnotateTextRequest.Features
288
encoding_type: EncodingType
289
290
class Features:
291
extract_syntax: bool
292
extract_entities: bool
293
extract_document_sentiment: bool
294
extract_entity_sentiment: bool
295
classify_text: bool
296
moderate_text: bool
297
298
class AnnotateTextResponse:
299
sentences: MutableSequence[Sentence]
300
tokens: MutableSequence[Token]
301
entities: MutableSequence[Entity]
302
document_sentiment: Sentiment
303
language: str
304
categories: MutableSequence[ClassificationCategory]
305
moderation_categories: MutableSequence[ClassificationCategory]
306
```
307
308
### Document
309
310
```python { .api }
311
class Document:
312
class Type(proto.Enum):
313
TYPE_UNSPECIFIED = 0
314
PLAIN_TEXT = 1
315
HTML = 2
316
317
content: str
318
gcs_content_uri: str
319
type_: Type
320
language: str
321
```
322
323
### Sentiment
324
325
```python { .api }
326
class Sentiment:
327
magnitude: float
328
score: float
329
```
330
331
### Entity
332
333
```python { .api }
334
class Entity:
335
class Type(proto.Enum):
336
UNKNOWN = 0
337
PERSON = 1
338
LOCATION = 2
339
ORGANIZATION = 3
340
EVENT = 4
341
WORK_OF_ART = 5
342
CONSUMER_GOOD = 6
343
OTHER = 7
344
PHONE_NUMBER = 9
345
ADDRESS = 10
346
DATE = 11
347
NUMBER = 12
348
PRICE = 13
349
350
name: str
351
type_: Type
352
metadata: MutableMapping[str, str]
353
salience: float
354
mentions: MutableSequence[EntityMention]
355
sentiment: Sentiment
356
```
357
358
### TextSpan
359
360
```python { .api }
361
class TextSpan:
362
content: str
363
begin_offset: int
364
```
365
366
### EntityMention
367
368
```python { .api }
369
class EntityMention:
370
class Type(proto.Enum):
371
TYPE_UNKNOWN = 0
372
PROPER = 1
373
COMMON = 2
374
375
text: TextSpan
376
type_: Type
377
sentiment: Sentiment
378
probability: float
379
```
380
381
### ClassificationCategory
382
383
```python { .api }
384
class ClassificationCategory:
385
name: str
386
confidence: float
387
```
388
389
### Token (v1/v1beta2 only)
390
391
```python { .api }
392
class Token:
393
text: TextSpan
394
part_of_speech: PartOfSpeech
395
dependency_edge: DependencyEdge
396
lemma: str
397
```
398
399
### PartOfSpeech (v1/v1beta2 only)
400
401
```python { .api }
402
class PartOfSpeech:
403
class Tag(proto.Enum):
404
UNKNOWN = 0
405
ADJ = 1
406
ADP = 2
407
ADV = 3
408
CONJ = 4
409
DET = 5
410
NOUN = 6
411
NUM = 7
412
PRON = 8
413
PRT = 9
414
PUNCT = 10
415
VERB = 11
416
X = 12
417
AFFIX = 13
418
419
tag: Tag
420
aspect: Aspect
421
case: Case
422
form: Form
423
gender: Gender
424
mood: Mood
425
number: Number
426
person: Person
427
proper: Proper
428
reciprocity: Reciprocity
429
tense: Tense
430
voice: Voice
431
```
432
433
### DependencyEdge (v1/v1beta2 only)
434
435
```python { .api }
436
class DependencyEdge:
437
class Label(proto.Enum):
438
UNKNOWN = 0
439
ROOT = 54
440
NSUBJ = 28
441
DOBJ = 18
442
# ... (additional labels available)
443
444
head_token_index: int
445
label: Label
446
```
447
448
### ClassificationModelOptions (v1/v1beta2 only)
449
450
```python { .api }
451
class ClassificationModelOptions:
452
class V1Model(proto.Message):
453
pass
454
455
class V2Model(proto.Message):
456
pass
457
458
v1_model: V1Model
459
v2_model: V2Model
460
```
461
462
### Sentence
463
464
```python { .api }
465
class Sentence:
466
text: TextSpan
467
sentiment: Sentiment
468
```
469
470
### EncodingType
471
472
```python { .api }
473
class EncodingType(proto.Enum):
474
NONE = 0
475
UTF8 = 1
476
UTF16 = 2
477
UTF32 = 3
478
```