0
# Google Shopping Type
1
2
Google Shopping Type API client library providing protobuf-generated classes for common shopping-related data types and structures. This package serves as a foundational dependency for other Google Shopping services with key features:
3
4
- **Standardized type definitions** for shopping data structures
5
- **Type safety** through protobuf-generated classes
6
- **Consistency** across Google Shopping services
7
- **High-precision monetary and weight values** using micros precision
8
- **Comprehensive enum definitions** for channels, destinations, and reporting contexts
9
10
## Package Information
11
12
- **Package Name**: google-shopping-type
13
- **Package Type**: pypi
14
- **Language**: Python
15
- **Installation**: `pip install google-shopping-type`
16
- **Version**: 1.0.0
17
18
## Core Imports
19
20
```python
21
from google.shopping.type import (
22
Channel,
23
CustomAttribute,
24
Destination,
25
Price,
26
ReportingContext,
27
Weight
28
)
29
```
30
31
Alternative import pattern:
32
33
```python
34
from google.shopping.type.types import (
35
Channel,
36
CustomAttribute,
37
Destination,
38
Price,
39
ReportingContext,
40
Weight
41
)
42
```
43
44
Version information:
45
46
```python
47
from google.shopping.type import __version__
48
```
49
50
## Basic Usage
51
52
```python
53
from google.shopping.type import Price, Weight, Channel
54
55
# Create a price object
56
price = Price()
57
price.amount_micros = 1500000 # $1.50 in micros
58
price.currency_code = "USD"
59
60
# Create a weight object
61
weight = Weight()
62
weight.amount_micros = 1000000 # 1kg in micros
63
weight.unit = Weight.WeightUnit.KILOGRAM
64
65
# Create a channel enum
66
channel_online = Channel.ChannelEnum.ONLINE
67
channel_local = Channel.ChannelEnum.LOCAL
68
69
print(f"Price: {price.amount_micros} micros {price.currency_code}")
70
print(f"Weight: {weight.amount_micros} micros, unit: {weight.unit}")
71
print(f"Channels: {channel_online}, {channel_local}")
72
```
73
74
## Architecture
75
76
This package follows Google's protobuf-based API design patterns using the proto-plus library. All classes are protobuf message classes that provide type-safe representations of shopping-related data structures:
77
78
- **Message Classes**: Each class extends `proto.Message` providing serialization and validation
79
- **Enum Types**: Nested enum classes define valid values for categorical fields
80
- **Field Definitions**: Fields use proto field descriptors with proper typing and optional handling
81
- **Micros Precision**: Monetary and weight values use micros (1/1,000,000) for precision
82
83
## Capabilities
84
85
### Price Representation
86
87
Represents monetary values with micros precision and currency codes following ISO 4217 standards.
88
89
```python { .api }
90
class Price(proto.Message):
91
"""
92
The price represented as a number and currency.
93
94
Attributes:
95
amount_micros (int, optional): Price in micros (1 million micros = 1 currency unit)
96
currency_code (str, optional): Three-letter ISO 4217 currency code
97
"""
98
amount_micros: int = proto.Field(proto.INT64, number=1, optional=True)
99
currency_code: str = proto.Field(proto.STRING, number=2, optional=True)
100
```
101
102
### Weight Representation
103
104
Represents weight values with micros precision and standard units (kg/lb).
105
106
```python { .api }
107
class Weight(proto.Message):
108
"""
109
The weight represented as the value in string and the unit.
110
111
Attributes:
112
amount_micros (int, optional): Weight in micros (1 million micros = 1 unit)
113
Can be set to -1 for infinity
114
unit (WeightUnit): Required weight unit (kg or lb)
115
"""
116
class WeightUnit(proto.Enum):
117
"""Weight unit enumeration."""
118
WEIGHT_UNIT_UNSPECIFIED = 0
119
POUND = 1
120
KILOGRAM = 2
121
122
amount_micros: int = proto.Field(proto.INT64, number=1, optional=True)
123
unit: WeightUnit = proto.Field(proto.ENUM, number=2, enum=WeightUnit)
124
```
125
126
### Custom Attributes
127
128
Represents custom attributes with hierarchical structure support for nested attributes.
129
130
```python { .api }
131
class CustomAttribute(proto.Message):
132
"""
133
Custom attributes with name/value pairs or nested groups.
134
Exactly one of value or group_values must not be empty.
135
136
Attributes:
137
name (str, optional): The name of the attribute
138
value (str, optional): The value (mutually exclusive with group_values)
139
group_values (MutableSequence[CustomAttribute]): Nested attributes
140
"""
141
name: str = proto.Field(proto.STRING, number=1, optional=True)
142
value: str = proto.Field(proto.STRING, number=2, optional=True)
143
group_values: MutableSequence["CustomAttribute"] = proto.RepeatedField(
144
proto.MESSAGE, number=3, message="CustomAttribute"
145
)
146
```
147
148
### Product Destinations
149
150
Defines available destinations where products can be displayed across Google's merchant ecosystem.
151
152
```python { .api }
153
class Destination(proto.Message):
154
"""
155
Destinations available for a product.
156
Used in Merchant Center to control where products are displayed.
157
"""
158
class DestinationEnum(proto.Enum):
159
"""Destination values."""
160
DESTINATION_ENUM_UNSPECIFIED = 0
161
SHOPPING_ADS = 1
162
DISPLAY_ADS = 2
163
LOCAL_INVENTORY_ADS = 3
164
FREE_LISTINGS = 4
165
FREE_LOCAL_LISTINGS = 5
166
YOUTUBE_SHOPPING = 6
167
```
168
169
### Reporting Contexts
170
171
Defines reporting contexts for account and product issues across various Google surfaces and formats.
172
173
```python { .api }
174
class ReportingContext(proto.Message):
175
"""
176
Reporting contexts that account and product issues apply to.
177
Groups surfaces and formats for product results on Google.
178
"""
179
class ReportingContextEnum(proto.Enum):
180
"""Reporting context values."""
181
REPORTING_CONTEXT_ENUM_UNSPECIFIED = 0
182
SHOPPING_ADS = 1
183
DISCOVERY_ADS = 2 # Deprecated: Use DEMAND_GEN_ADS instead
184
DEMAND_GEN_ADS = 13
185
DEMAND_GEN_ADS_DISCOVER_SURFACE = 14
186
VIDEO_ADS = 3
187
DISPLAY_ADS = 4
188
LOCAL_INVENTORY_ADS = 5
189
VEHICLE_INVENTORY_ADS = 6
190
FREE_LISTINGS = 7
191
FREE_LOCAL_LISTINGS = 8
192
FREE_LOCAL_VEHICLE_LISTINGS = 9
193
YOUTUBE_SHOPPING = 10
194
CLOUD_RETAIL = 11
195
LOCAL_CLOUD_RETAIL = 12
196
```
197
198
### Channel Types
199
200
Distinguishes between online and local products in the merchant ecosystem.
201
202
```python { .api }
203
class Channel(proto.Message):
204
"""
205
Channel of a product, used to distinguish between online and local products.
206
"""
207
class ChannelEnum(proto.Enum):
208
"""Channel values."""
209
CHANNEL_ENUM_UNSPECIFIED = 0
210
ONLINE = 1
211
LOCAL = 2
212
```
213
214
## Types
215
216
All message classes extend `proto.Message` and provide the following common functionality:
217
218
```python { .api }
219
# Common proto.Message methods available on all classes
220
def __init__(self, mapping=None, **kwargs): ...
221
def __contains__(self, key): ...
222
def __getattr__(self, key): ...
223
def __setattr__(self, key, value): ...
224
def to_dict(self, **kwargs): ...
225
def to_json(self, **kwargs): ...
226
```
227
228
### Type Imports
229
230
```python { .api }
231
from typing import MutableMapping, MutableSequence
232
import proto
233
```
234
235
## Error Handling
236
237
This package uses proto-plus validation which will raise `ValueError` exceptions for:
238
- Invalid enum values
239
- Required fields that are not set
240
- Type mismatches in field assignments
241
242
The protobuf classes handle serialization errors and will raise appropriate exceptions during message parsing or field validation.
243
244
## Dependencies
245
246
- **google-api-core[grpc]** >= 1.34.1, <3.0.0: Core Google API functionality
247
- **google-auth** >= 2.14.1, <3.0.0: Authentication for Google APIs
248
- **proto-plus** >= 1.22.3, <2.0.0: Enhanced protobuf support for Python
249
- **protobuf** >=3.20.2,<7.0.0: Protocol buffer runtime