0
# Product Search and Catalog Management
1
2
Comprehensive functionality for managing product catalogs and performing product-based image searches with Google Cloud Vision API. The ProductSearchClient provides complete CRUD operations for products, product sets, and reference images, along with batch import capabilities and advanced search functionality.
3
4
## ProductSearchClient
5
6
Specialized client for product catalog management and product-based image search operations.
7
8
### Client Initialization
9
10
```python { .api }
11
class ProductSearchClient:
12
def __init__(self, *, credentials=None, transport=None, client_options=None, client_info=None):
13
"""Initialize the ProductSearchClient.
14
15
Args:
16
credentials: The authorization credentials to attach to requests
17
transport: The transport to use for API calls
18
client_options: Custom options for the client
19
client_info: The client info used to send a user-agent string
20
"""
21
```
22
23
### Basic Usage
24
25
```python
26
from google.cloud.vision import ProductSearchClient, Product, ProductSet, ReferenceImage
27
28
# Initialize client
29
client = ProductSearchClient()
30
location_path = f"projects/{project_id}/locations/{location_id}"
31
32
# Create a product set
33
product_set = ProductSet(display_name="Clothing", description="Fashion items")
34
response = client.create_product_set(
35
parent=location_path,
36
product_set=product_set,
37
product_set_id="clothing_set_1"
38
)
39
40
# Create a product
41
product = Product(
42
display_name="Blue Jeans",
43
description="Classic blue denim jeans",
44
product_category="apparel"
45
)
46
product_response = client.create_product(
47
parent=location_path,
48
product=product,
49
product_id="blue_jeans_1"
50
)
51
52
# Add product to product set
53
client.add_product_to_product_set(
54
name=response.name,
55
product=product_response.name
56
)
57
```
58
59
## Capabilities
60
61
### Product Set Management
62
63
Operations for creating and managing collections of related products.
64
65
```python { .api }
66
def create_product_set(self, parent, product_set, product_set_id=None, *, retry=None, timeout=None, metadata=()) -> ProductSet:
67
"""Create a new ProductSet.
68
69
Args:
70
parent: Project and location path (projects/{project}/locations/{location})
71
product_set: ProductSet object with display_name and optional description
72
product_set_id: User-defined ID for the product set
73
retry: Retry configuration for the request
74
timeout: Timeout for the request in seconds
75
metadata: Additional metadata to send with the request
76
77
Returns:
78
ProductSet: The created product set with assigned name
79
"""
80
81
def list_product_sets(self, parent, *, page_size=None, page_token=None, retry=None, timeout=None, metadata=()) -> ListProductSetsResponse:
82
"""List ProductSets in a location.
83
84
Args:
85
parent: Project and location path
86
page_size: Maximum number of results per page
87
page_token: Token for pagination
88
retry: Retry configuration for the request
89
timeout: Timeout for the request in seconds
90
metadata: Additional metadata to send with the request
91
92
Returns:
93
ListProductSetsResponse: Paginated list of product sets
94
"""
95
96
def get_product_set(self, name, *, retry=None, timeout=None, metadata=()) -> ProductSet:
97
"""Get information about a ProductSet.
98
99
Args:
100
name: Full resource name of the product set
101
retry: Retry configuration for the request
102
timeout: Timeout for the request in seconds
103
metadata: Additional metadata to send with the request
104
105
Returns:
106
ProductSet: The requested product set
107
"""
108
109
def update_product_set(self, product_set, *, update_mask=None, retry=None, timeout=None, metadata=()) -> ProductSet:
110
"""Update a ProductSet.
111
112
Args:
113
product_set: ProductSet object with updates
114
update_mask: FieldMask indicating which fields to update
115
retry: Retry configuration for the request
116
timeout: Timeout for the request in seconds
117
metadata: Additional metadata to send with the request
118
119
Returns:
120
ProductSet: The updated product set
121
"""
122
123
def delete_product_set(self, name, *, retry=None, timeout=None, metadata=()) -> None:
124
"""Delete a ProductSet.
125
126
Args:
127
name: Full resource name of the product set
128
retry: Retry configuration for the request
129
timeout: Timeout for the request in seconds
130
metadata: Additional metadata to send with the request
131
132
Returns:
133
None
134
"""
135
```
136
137
### Product Management
138
139
Operations for managing individual products within the catalog.
140
141
```python { .api }
142
def create_product(self, parent, product, product_id=None, *, retry=None, timeout=None, metadata=()) -> Product:
143
"""Create a new Product.
144
145
Args:
146
parent: Project and location path
147
product: Product object with display_name, description, product_category
148
product_id: User-defined ID for the product
149
retry: Retry configuration for the request
150
timeout: Timeout for the request in seconds
151
metadata: Additional metadata to send with the request
152
153
Returns:
154
Product: The created product with assigned name
155
"""
156
157
def list_products(self, parent, *, page_size=None, page_token=None, retry=None, timeout=None, metadata=()) -> ListProductsResponse:
158
"""List Products in a location.
159
160
Args:
161
parent: Project and location path
162
page_size: Maximum number of results per page
163
page_token: Token for pagination
164
retry: Retry configuration for the request
165
timeout: Timeout for the request in seconds
166
metadata: Additional metadata to send with the request
167
168
Returns:
169
ListProductsResponse: Paginated list of products
170
"""
171
172
def get_product(self, name, *, retry=None, timeout=None, metadata=()) -> Product:
173
"""Get information about a Product.
174
175
Args:
176
name: Full resource name of the product
177
retry: Retry configuration for the request
178
timeout: Timeout for the request in seconds
179
metadata: Additional metadata to send with the request
180
181
Returns:
182
Product: The requested product
183
"""
184
185
def update_product(self, product, *, update_mask=None, retry=None, timeout=None, metadata=()) -> Product:
186
"""Update a Product.
187
188
Args:
189
product: Product object with updates
190
update_mask: FieldMask indicating which fields to update
191
retry: Retry configuration for the request
192
timeout: Timeout for the request in seconds
193
metadata: Additional metadata to send with the request
194
195
Returns:
196
Product: The updated product
197
"""
198
199
def delete_product(self, name, *, retry=None, timeout=None, metadata=()) -> None:
200
"""Delete a Product.
201
202
Args:
203
name: Full resource name of the product
204
retry: Retry configuration for the request
205
timeout: Timeout for the request in seconds
206
metadata: Additional metadata to send with the request
207
208
Returns:
209
None
210
"""
211
```
212
213
### Reference Image Management
214
215
Operations for managing reference images associated with products.
216
217
```python { .api }
218
def create_reference_image(self, parent, reference_image, reference_image_id=None, *, retry=None, timeout=None, metadata=()) -> ReferenceImage:
219
"""Create a new ReferenceImage for a Product.
220
221
Args:
222
parent: Product path (projects/{project}/locations/{location}/products/{product})
223
reference_image: ReferenceImage object with URI
224
reference_image_id: User-defined ID for the reference image
225
retry: Retry configuration for the request
226
timeout: Timeout for the request in seconds
227
metadata: Additional metadata to send with the request
228
229
Returns:
230
ReferenceImage: The created reference image
231
"""
232
233
def list_reference_images(self, parent, *, page_size=None, page_token=None, retry=None, timeout=None, metadata=()) -> ListReferenceImagesResponse:
234
"""List ReferenceImages for a Product.
235
236
Args:
237
parent: Product path
238
page_size: Maximum number of results per page
239
page_token: Token for pagination
240
retry: Retry configuration for the request
241
timeout: Timeout for the request in seconds
242
metadata: Additional metadata to send with the request
243
244
Returns:
245
ListReferenceImagesResponse: Paginated list of reference images
246
"""
247
248
def get_reference_image(self, name, *, retry=None, timeout=None, metadata=()) -> ReferenceImage:
249
"""Get information about a ReferenceImage.
250
251
Args:
252
name: Full resource name of the reference image
253
retry: Retry configuration for the request
254
timeout: Timeout for the request in seconds
255
metadata: Additional metadata to send with the request
256
257
Returns:
258
ReferenceImage: The requested reference image
259
"""
260
261
def delete_reference_image(self, name, *, retry=None, timeout=None, metadata=()) -> None:
262
"""Delete a ReferenceImage.
263
264
Args:
265
name: Full resource name of the reference image
266
retry: Retry configuration for the request
267
timeout: Timeout for the request in seconds
268
metadata: Additional metadata to send with the request
269
270
Returns:
271
None
272
"""
273
```
274
275
### Product Set Association Management
276
277
Operations for managing relationships between products and product sets.
278
279
```python { .api }
280
def add_product_to_product_set(self, name, product, *, retry=None, timeout=None, metadata=()) -> None:
281
"""Add a Product to a ProductSet.
282
283
Args:
284
name: ProductSet resource name
285
product: Product resource name to add
286
retry: Retry configuration for the request
287
timeout: Timeout for the request in seconds
288
metadata: Additional metadata to send with the request
289
290
Returns:
291
None
292
"""
293
294
def remove_product_from_product_set(self, name, product, *, retry=None, timeout=None, metadata=()) -> None:
295
"""Remove a Product from a ProductSet.
296
297
Args:
298
name: ProductSet resource name
299
product: Product resource name to remove
300
retry: Retry configuration for the request
301
timeout: Timeout for the request in seconds
302
metadata: Additional metadata to send with the request
303
304
Returns:
305
None
306
"""
307
308
def list_products_in_product_set(self, name, *, page_size=None, page_token=None, retry=None, timeout=None, metadata=()) -> ListProductsInProductSetResponse:
309
"""List Products in a ProductSet.
310
311
Args:
312
name: ProductSet resource name
313
page_size: Maximum number of results per page
314
page_token: Token for pagination
315
retry: Retry configuration for the request
316
timeout: Timeout for the request in seconds
317
metadata: Additional metadata to send with the request
318
319
Returns:
320
ListProductsInProductSetResponse: Paginated list of products in the set
321
"""
322
```
323
324
### Batch Operations
325
326
Operations for bulk import and management of product catalogs.
327
328
```python { .api }
329
def import_product_sets(self, parent, input_config, *, retry=None, timeout=None, metadata=()) -> Operation:
330
"""Import ProductSets from a CSV file.
331
332
Args:
333
parent: Project and location path
334
input_config: ImportProductSetsInputConfig with CSV source details
335
retry: Retry configuration for the request
336
timeout: Timeout for the request in seconds
337
metadata: Additional metadata to send with the request
338
339
Returns:
340
Operation: Long-running operation for the import job
341
"""
342
343
def purge_products(self, parent, *, product_set_purge_config=None, delete_orphan_products=None, force=None, retry=None, timeout=None, metadata=()) -> Operation:
344
"""Delete products and their reference images.
345
346
Args:
347
parent: Project and location path
348
product_set_purge_config: Configuration for purging products in a set
349
delete_orphan_products: Whether to delete orphaned products
350
force: Whether to force deletion
351
retry: Retry configuration for the request
352
timeout: Timeout for the request in seconds
353
metadata: Additional metadata to send with the request
354
355
Returns:
356
Operation: Long-running operation for the purge job
357
"""
358
```
359
360
## Usage Examples
361
362
### Setting Up a Product Catalog
363
364
```python
365
from google.cloud.vision import ProductSearchClient, Product, ProductSet, ReferenceImage
366
367
client = ProductSearchClient()
368
project_id = "your-project-id"
369
location_id = "us-west1"
370
location_path = f"projects/{project_id}/locations/{location_id}"
371
372
# Create product set for clothing items
373
product_set = ProductSet(
374
display_name="Fashion Catalog",
375
description="Collection of clothing and accessories"
376
)
377
378
created_set = client.create_product_set(
379
parent=location_path,
380
product_set=product_set,
381
product_set_id="fashion_catalog_v1"
382
)
383
384
print(f"Created product set: {created_set.name}")
385
386
# Create products
387
products = [
388
{
389
"id": "shirt_001",
390
"display_name": "Blue Cotton Shirt",
391
"description": "Classic blue cotton button-down shirt",
392
"category": "apparel"
393
},
394
{
395
"id": "jeans_001",
396
"display_name": "Dark Wash Jeans",
397
"description": "Slim fit dark wash denim jeans",
398
"category": "apparel"
399
}
400
]
401
402
created_products = []
403
for prod_info in products:
404
product = Product(
405
display_name=prod_info["display_name"],
406
description=prod_info["description"],
407
product_category=prod_info["category"]
408
)
409
410
created_product = client.create_product(
411
parent=location_path,
412
product=product,
413
product_id=prod_info["id"]
414
)
415
created_products.append(created_product)
416
417
# Add to product set
418
client.add_product_to_product_set(
419
name=created_set.name,
420
product=created_product.name
421
)
422
423
print(f"Created product: {created_product.display_name}")
424
```
425
426
### Adding Reference Images
427
428
```python
429
# Add reference images for each product
430
reference_images = [
431
{
432
"product_name": created_products[0].name,
433
"image_uri": "gs://your-bucket/shirt_front.jpg",
434
"ref_id": "shirt_001_front"
435
},
436
{
437
"product_name": created_products[0].name,
438
"image_uri": "gs://your-bucket/shirt_back.jpg",
439
"ref_id": "shirt_001_back"
440
},
441
{
442
"product_name": created_products[1].name,
443
"image_uri": "gs://your-bucket/jeans_front.jpg",
444
"ref_id": "jeans_001_front"
445
}
446
]
447
448
for ref_info in reference_images:
449
reference_image = ReferenceImage(uri=ref_info["image_uri"])
450
451
created_ref = client.create_reference_image(
452
parent=ref_info["product_name"],
453
reference_image=reference_image,
454
reference_image_id=ref_info["ref_id"]
455
)
456
457
print(f"Added reference image: {created_ref.name}")
458
```
459
460
### Performing Product Search
461
462
```python
463
from google.cloud.vision import ImageAnnotatorClient, Image, ImageContext, ProductSearchParams
464
465
# Use ImageAnnotatorClient for product search
466
image_client = ImageAnnotatorClient()
467
468
# Configure product search parameters
469
product_search_params = ProductSearchParams(
470
product_set=created_set.name,
471
product_categories=["apparel"]
472
)
473
474
image_context = ImageContext(product_search_params=product_search_params)
475
476
# Search for products in an image
477
image = Image(source={'image_uri': 'gs://your-bucket/query_image.jpg'})
478
479
response = image_client.product_search(
480
image=image,
481
image_context=image_context,
482
max_results=10
483
)
484
485
# Process search results
486
if response.product_search_results:
487
results = response.product_search_results
488
print(f"Found {len(results.results)} matching products")
489
490
for result in results.results:
491
product = result.product
492
print(f"Product: {product.display_name}")
493
print(f"Score: {result.score}")
494
print(f"Image: {result.image}")
495
```
496
497
### Catalog Management
498
499
```python
500
# List all product sets
501
response = client.list_product_sets(parent=location_path)
502
for product_set in response.product_sets:
503
print(f"Product Set: {product_set.display_name}")
504
505
# List products in each set
506
products_response = client.list_products_in_product_set(
507
name=product_set.name
508
)
509
510
for product in products_response.products:
511
print(f" Product: {product.display_name}")
512
513
# List reference images for each product
514
images_response = client.list_reference_images(
515
parent=product.name
516
)
517
518
for ref_image in images_response.reference_images:
519
print(f" Reference: {ref_image.uri}")
520
```
521
522
### Bulk Import from CSV
523
524
```python
525
from google.cloud.vision import ImportProductSetsInputConfig, ImportProductSetsGcsSource
526
527
# Import products from CSV file
528
gcs_source = ImportProductSetsGcsSource(
529
csv_file_uri="gs://your-bucket/products.csv"
530
)
531
532
input_config = ImportProductSetsInputConfig(gcs_source=gcs_source)
533
534
operation = client.import_product_sets(
535
parent=location_path,
536
input_config=input_config
537
)
538
539
print(f"Import operation: {operation.name}")
540
541
# Wait for operation to complete
542
result = operation.result()
543
print(f"Import completed: {result}")
544
```
545
546
### Cleanup Operations
547
548
```python
549
# Remove product from product set
550
client.remove_product_from_product_set(
551
name=created_set.name,
552
product=created_products[0].name
553
)
554
555
# Delete reference images
556
for product in created_products:
557
ref_images = client.list_reference_images(parent=product.name)
558
for ref_image in ref_images.reference_images:
559
client.delete_reference_image(name=ref_image.name)
560
561
# Delete products
562
for product in created_products:
563
client.delete_product(name=product.name)
564
565
# Delete product set
566
client.delete_product_set(name=created_set.name)
567
568
print("Cleanup completed")
569
```
570
571
## ProductSearchAsyncClient
572
573
Asynchronous version of the ProductSearchClient for non-blocking operations.
574
575
```python { .api }
576
class ProductSearchAsyncClient:
577
async def create_product_set(self, parent, product_set, product_set_id=None, *, retry=None, timeout=None, metadata=()) -> ProductSet: ...
578
async def list_product_sets(self, parent, *, page_size=None, page_token=None, retry=None, timeout=None, metadata=()) -> ListProductSetsResponse: ...
579
async def get_product_set(self, name, *, retry=None, timeout=None, metadata=()) -> ProductSet: ...
580
async def update_product_set(self, product_set, *, update_mask=None, retry=None, timeout=None, metadata=()) -> ProductSet: ...
581
async def delete_product_set(self, name, *, retry=None, timeout=None, metadata=()) -> None: ...
582
583
async def create_product(self, parent, product, product_id=None, *, retry=None, timeout=None, metadata=()) -> Product: ...
584
async def list_products(self, parent, *, page_size=None, page_token=None, retry=None, timeout=None, metadata=()) -> ListProductsResponse: ...
585
async def get_product(self, name, *, retry=None, timeout=None, metadata=()) -> Product: ...
586
async def update_product(self, product, *, update_mask=None, retry=None, timeout=None, metadata=()) -> Product: ...
587
async def delete_product(self, name, *, retry=None, timeout=None, metadata=()) -> None: ...
588
589
async def create_reference_image(self, parent, reference_image, reference_image_id=None, *, retry=None, timeout=None, metadata=()) -> ReferenceImage: ...
590
async def list_reference_images(self, parent, *, page_size=None, page_token=None, retry=None, timeout=None, metadata=()) -> ListReferenceImagesResponse: ...
591
async def get_reference_image(self, name, *, retry=None, timeout=None, metadata=()) -> ReferenceImage: ...
592
async def delete_reference_image(self, name, *, retry=None, timeout=None, metadata=()) -> None: ...
593
594
async def add_product_to_product_set(self, name, product, *, retry=None, timeout=None, metadata=()) -> None: ...
595
async def remove_product_from_product_set(self, name, product, *, retry=None, timeout=None, metadata=()) -> None: ...
596
async def list_products_in_product_set(self, name, *, page_size=None, page_token=None, retry=None, timeout=None, metadata=()) -> ListProductsInProductSetResponse: ...
597
async def import_product_sets(self, parent, input_config, *, retry=None, timeout=None, metadata=()) -> Operation: ...
598
async def purge_products(self, parent, *, product_set_purge_config=None, delete_orphan_products=None, force=None, retry=None, timeout=None, metadata=()) -> Operation: ...
599
```
600
601
### Async Usage
602
603
```python
604
import asyncio
605
from google.cloud.vision import ProductSearchAsyncClient, Product
606
607
async def manage_products_async():
608
client = ProductSearchAsyncClient()
609
location_path = "projects/your-project/locations/us-west1"
610
611
# Create product asynchronously
612
product = Product(
613
display_name="Async Product",
614
description="Created asynchronously",
615
product_category="apparel"
616
)
617
618
created_product = await client.create_product(
619
parent=location_path,
620
product=product,
621
product_id="async_product_1"
622
)
623
624
print(f"Created product: {created_product.name}")
625
626
# List products asynchronously
627
response = await client.list_products(parent=location_path)
628
for product in response.products:
629
print(f"Product: {product.display_name}")
630
631
# Run async function
632
asyncio.run(manage_products_async())
633
```