0
# Google Cloud Vision API
1

2
A comprehensive Python client library for Google Cloud Vision API that provides image analysis capabilities including object detection, text recognition, face detection, landmark identification, and more. The library offers both synchronous and asynchronous clients with convenient helper methods for common use cases.
3

4
## Package Information
5

6
- **Package Name**: google-cloud-vision
7
- **Language**: Python  
8
- **Version**: v3.10.2
9
- **Installation**: `pip install google-cloud-vision`
10

11
## Core Imports
12

13
```python
14
from google.cloud import vision
15
```
16

17
Common for image annotation:
18

19
```python
20
from google.cloud.vision import ImageAnnotatorClient, Image, Feature
21
```
22

23
For product search:
24

25
```python
26
from google.cloud.vision import ProductSearchClient
27
```
28

29
## Basic Usage
30

31
```python
32
from google.cloud.vision import ImageAnnotatorClient, Image
33

34
# Initialize the client
35
client = ImageAnnotatorClient()
36

37
# Analyze an image from a URL
38
image = Image(source={'image_uri': 'https://example.com/image.jpg'})
39
response = client.annotate_image({'image': image})
40

41
# Access detection results
42
labels = response.label_annotations
43
faces = response.face_annotations
44
text = response.text_annotations
45

46
# Use convenience methods for specific features
47
response = client.label_detection(image)
48
response = client.face_detection(image, max_results=10)
49
response = client.text_detection(image)
50

51
# Analyze local image file
52
with open('local_image.jpg', 'rb') as image_file:
53
    content = image_file.read()
54
    
55
image = Image(content=content)
56
response = client.annotate_image({'image': image})
57

58
# Batch processing multiple images
59
images = [Image(source={'image_uri': f'https://example.com/image{i}.jpg'}) 
60
          for i in range(3)]
61
requests = [{'image': img, 'features': [{'type_': Feature.Type.LABEL_DETECTION}]} 
62
           for img in images]
63
response = client.batch_annotate_images(requests=requests)
64

65
for image_response in response.responses:
66
    print(f"Labels: {[label.description for label in image_response.label_annotations]}")
67
```
68

69
## Architecture
70

71
Google Cloud Vision API is organized around two main client types and a rich type system:
72

73
- **ImageAnnotatorClient**: Primary client for image analysis operations, enhanced with VisionHelpers for convenience methods and single-feature detection methods
74
- **ProductSearchClient**: Specialized client for product catalog management and product-based image search  
75
- **Type System**: Comprehensive data types for requests, responses, geometry, annotations, and configuration
76

77
The library provides multiple API versions (v1 stable, plus beta versions v1p1beta1 through v1p4beta1) with the main `google.cloud.vision` module exposing the stable v1 API.
78

79
### Design Patterns
80

81
The library follows several key patterns:
82
- **Convenience Methods**: VisionHelpers provides `annotate_image()` that auto-detects all features when none specified
83
- **Single-Feature Methods**: Dynamically generated methods like `face_detection()`, `text_detection()` for common operations  
84
- **Batch Operations**: Support for processing multiple images efficiently
85
- **Async Support**: Full async client implementations for non-blocking operations
86
- **Flexible Input**: Support for image URIs, local files, raw bytes, and file handles
87

88
## Capabilities
89

90
### Image Analysis and Annotation
91

92
Core image analysis functionality including face detection, object localization, text recognition, landmark detection, logo detection, and image properties analysis. Provides both batch and single-image processing with extensive customization options.
93

94
```python { .api }
95
class ImageAnnotatorClient:
96
    def annotate_image(self, request, *, retry=None, timeout=None, metadata=()) -> AnnotateImageResponse: ...
97
    def batch_annotate_images(self, requests, *, retry=None, timeout=None, metadata=()) -> BatchAnnotateImagesResponse: ...
98
    def batch_annotate_files(self, requests, *, retry=None, timeout=None, metadata=()) -> BatchAnnotateFilesResponse: ...
99
    def async_batch_annotate_images(self, requests, output_config, *, retry=None, timeout=None, metadata=()) -> Operation: ...
100
    def async_batch_annotate_files(self, requests, *, retry=None, timeout=None, metadata=()) -> Operation: ...
101
    
102
    # Single-feature convenience methods (dynamically generated)
103
    def face_detection(self, image, *, max_results=None, retry=None, timeout=None, metadata=(), **kwargs) -> AnnotateImageResponse: ...
104
    def landmark_detection(self, image, *, max_results=None, retry=None, timeout=None, metadata=(), **kwargs) -> AnnotateImageResponse: ...
105
    def logo_detection(self, image, *, max_results=None, retry=None, timeout=None, metadata=(), **kwargs) -> AnnotateImageResponse: ...
106
    def label_detection(self, image, *, max_results=None, retry=None, timeout=None, metadata=(), **kwargs) -> AnnotateImageResponse: ...
107
    def text_detection(self, image, *, max_results=None, retry=None, timeout=None, metadata=(), **kwargs) -> AnnotateImageResponse: ...
108
    def document_text_detection(self, image, *, max_results=None, retry=None, timeout=None, metadata=(), **kwargs) -> AnnotateImageResponse: ...
109
    def safe_search_detection(self, image, *, max_results=None, retry=None, timeout=None, metadata=(), **kwargs) -> AnnotateImageResponse: ...
110
    def image_properties(self, image, *, max_results=None, retry=None, timeout=None, metadata=(), **kwargs) -> AnnotateImageResponse: ...
111
    def crop_hints(self, image, *, max_results=None, retry=None, timeout=None, metadata=(), **kwargs) -> AnnotateImageResponse: ...
112
    def web_detection(self, image, *, max_results=None, retry=None, timeout=None, metadata=(), **kwargs) -> AnnotateImageResponse: ...
113
    def product_search(self, image, *, max_results=None, retry=None, timeout=None, metadata=(), **kwargs) -> AnnotateImageResponse: ...
114
    def object_localization(self, image, *, max_results=None, retry=None, timeout=None, metadata=(), **kwargs) -> AnnotateImageResponse: ...
115
```
116

117
[Image Analysis](./image-annotation.md)
118

119
### Product Search and Catalog Management
120

121
Functionality for managing product catalogs and performing product-based image searches. Includes creation and management of products, product sets, and reference images with comprehensive CRUD operations and batch import capabilities.
122

123
```python { .api }
124
class ProductSearchClient:
125
    def create_product_set(self, parent, product_set, product_set_id=None, *, retry=None, timeout=None, metadata=()) -> ProductSet: ...
126
    def list_product_sets(self, parent, *, page_size=None, page_token=None, retry=None, timeout=None, metadata=()) -> ListProductSetsResponse: ...
127
    def get_product_set(self, name, *, retry=None, timeout=None, metadata=()) -> ProductSet: ...
128
    def update_product_set(self, product_set, *, update_mask=None, retry=None, timeout=None, metadata=()) -> ProductSet: ...
129
    def delete_product_set(self, name, *, retry=None, timeout=None, metadata=()) -> None: ...
130
    
131
    def create_product(self, parent, product, product_id=None, *, retry=None, timeout=None, metadata=()) -> Product: ...
132
    def list_products(self, parent, *, page_size=None, page_token=None, retry=None, timeout=None, metadata=()) -> ListProductsResponse: ...
133
    def get_product(self, name, *, retry=None, timeout=None, metadata=()) -> Product: ...
134
    def update_product(self, product, *, update_mask=None, retry=None, timeout=None, metadata=()) -> Product: ...
135
    def delete_product(self, name, *, retry=None, timeout=None, metadata=()) -> None: ...
136
    
137
    def create_reference_image(self, parent, reference_image, reference_image_id=None, *, retry=None, timeout=None, metadata=()) -> ReferenceImage: ...
138
    def list_reference_images(self, parent, *, page_size=None, page_token=None, retry=None, timeout=None, metadata=()) -> ListReferenceImagesResponse: ...
139
    def get_reference_image(self, name, *, retry=None, timeout=None, metadata=()) -> ReferenceImage: ...
140
    def delete_reference_image(self, name, *, retry=None, timeout=None, metadata=()) -> None: ...
141
    
142
    def add_product_to_product_set(self, name, product, *, retry=None, timeout=None, metadata=()) -> None: ...
143
    def remove_product_from_product_set(self, name, product, *, retry=None, timeout=None, metadata=()) -> None: ...
144
    def list_products_in_product_set(self, name, *, page_size=None, page_token=None, retry=None, timeout=None, metadata=()) -> ListProductsInProductSetResponse: ...
145
    def import_product_sets(self, parent, input_config, *, retry=None, timeout=None, metadata=()) -> Operation: ...
146
    def purge_products(self, parent, *, product_set_purge_config=None, delete_orphan_products=None, force=None, retry=None, timeout=None, metadata=()) -> Operation: ...
147
```
148

149
[Product Search](./product-search.md)
150

151
### Data Types and Response Objects
152

153
Comprehensive type system including request/response objects, annotation results, geometry types, configuration parameters, and enums. Provides strong typing for all API interactions with detailed structured data for analysis results.
154

155
```python { .api }
156
# Core annotation types
157
class AnnotateImageRequest: ...
158
class AnnotateImageResponse: ...
159
class BatchAnnotateImagesRequest: ...
160
class BatchAnnotateImagesResponse: ...
161

162
# Detection result types  
163
class FaceAnnotation: ...
164
class EntityAnnotation: ...
165
class LocalizedObjectAnnotation: ...
166
class TextAnnotation: ...
167
class SafeSearchAnnotation: ...
168
class ImageProperties: ...
169
class WebDetection: ...
170

171
# Geometry and positioning
172
class BoundingPoly: ...
173
class Vertex: ...
174
class NormalizedVertex: ...
175
class Position: ...
176

177
# Configuration and parameters
178
class Feature: ...
179
class ImageContext: ...
180
class Likelihood: ...
181
```
182

183
[Types and Data](./types-and-data.md)