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