0
# Common Data Types
1
2
Fundamental data types for temporal, geographic, financial, and contact information used across Google APIs. These types provide standardized representations for common concepts, ensuring consistency across the Google API ecosystem.
3
4
## Capabilities
5
6
### Financial Types
7
8
Monetary amounts and currency representation with precise decimal handling.
9
10
```python { .api }
11
from google.type.money_pb2 import Money
12
from google.type.decimal_pb2 import Decimal
13
from google.type.fraction_pb2 import Fraction
14
15
class Money(message.Message):
16
"""Monetary amount with currency code."""
17
currency_code: str # ISO 4217 currency code (e.g., "USD", "EUR")
18
units: int # Whole currency units
19
nanos: int # Fractional units (nano-units, 10^-9)
20
21
class Decimal(message.Message):
22
"""Arbitrary precision decimal number."""
23
value: str # Decimal value as string
24
25
class Fraction(message.Message):
26
"""Fraction representation."""
27
numerator: int # Fraction numerator
28
denominator: int # Fraction denominator
29
```
30
31
### Temporal Types
32
33
Date, time, and calendar representations for various temporal concepts.
34
35
```python { .api }
36
from google.type.date_pb2 import Date
37
from google.type.datetime_pb2 import DateTime
38
from google.type.timeofday_pb2 import TimeOfDay
39
from google.type.interval_pb2 import Interval
40
from google.type.dayofweek_pb2 import DayOfWeek
41
from google.type.month_pb2 import Month
42
from google.type.calendar_period_pb2 import CalendarPeriod
43
44
class Date(message.Message):
45
"""Calendar date (year, month, day)."""
46
year: int # Year (e.g., 2023)
47
month: int # Month (1-12)
48
day: int # Day of month (1-31)
49
50
class DateTime(message.Message):
51
"""Date and time with timezone information."""
52
year: int # Year
53
month: int # Month (1-12)
54
day: int # Day of month (1-31)
55
hours: int # Hours (0-23)
56
minutes: int # Minutes (0-59)
57
seconds: int # Seconds (0-59)
58
nanos: int # Nanoseconds (0-999,999,999)
59
time_offset: DateTime.TimeOffset # Timezone offset
60
61
class TimeOffset(message.Message):
62
"""Timezone offset information."""
63
# Union field (one of):
64
utc_offset: Duration # UTC offset
65
time_zone: TimeZone # Named timezone
66
67
class TimeOfDay(message.Message):
68
"""Time of day (hours, minutes, seconds)."""
69
hours: int # Hours (0-23)
70
minutes: int # Minutes (0-59)
71
seconds: int # Seconds (0-59)
72
nanos: int # Nanoseconds (0-999,999,999)
73
74
class Interval(message.Message):
75
"""Time interval between two timestamps."""
76
start_time: Timestamp # Interval start time
77
end_time: Timestamp # Interval end time
78
79
class DayOfWeek(enum.Enum):
80
"""Day of week enumeration."""
81
DAY_OF_WEEK_UNSPECIFIED = 0
82
MONDAY = 1
83
TUESDAY = 2
84
WEDNESDAY = 3
85
THURSDAY = 4
86
FRIDAY = 5
87
SATURDAY = 6
88
SUNDAY = 7
89
90
class Month(enum.Enum):
91
"""Month enumeration."""
92
MONTH_UNSPECIFIED = 0
93
JANUARY = 1
94
FEBRUARY = 2
95
MARCH = 3
96
APRIL = 4
97
MAY = 5
98
JUNE = 6
99
JULY = 7
100
AUGUST = 8
101
SEPTEMBER = 9
102
OCTOBER = 10
103
NOVEMBER = 11
104
DECEMBER = 12
105
106
class CalendarPeriod(enum.Enum):
107
"""Calendar period enumeration."""
108
CALENDAR_PERIOD_UNSPECIFIED = 0
109
DAY = 1
110
WEEK = 2
111
FORTNIGHT = 3
112
MONTH = 4
113
QUARTER = 5
114
HALF = 6
115
YEAR = 7
116
```
117
118
### Geographic Types
119
120
Location, coordinate, and spatial data representations.
121
122
```python { .api }
123
from google.type.latlng_pb2 import LatLng
124
from google.type.quaternion_pb2 import Quaternion
125
126
class LatLng(message.Message):
127
"""Geographic coordinates (latitude, longitude)."""
128
latitude: float # Latitude in degrees (-90 to +90)
129
longitude: float # Longitude in degrees (-180 to +180)
130
131
class Quaternion(message.Message):
132
"""3D rotation representation using quaternion."""
133
x: float # X component
134
y: float # Y component
135
z: float # Z component
136
w: float # W component (scalar part)
137
```
138
139
### Contact Information Types
140
141
Phone numbers and postal addresses with international support.
142
143
```python { .api }
144
from google.type.phone_number_pb2 import PhoneNumber
145
from google.type.postal_address_pb2 import PostalAddress
146
147
class PhoneNumber(message.Message):
148
"""Phone number representation."""
149
# Union field (one of):
150
e164_number: str # E.164 format (e.g., "+12345678900")
151
short_code: PhoneNumber.ShortCode # Short code for specific region
152
extension: str # Phone extension
153
154
class ShortCode(message.Message):
155
"""Short code representation."""
156
region_code: str # ISO 3166-1 alpha-2 region code
157
number: str # Short code number
158
159
class PostalAddress(message.Message):
160
"""Postal address representation."""
161
revision: int # Address revision number
162
region_code: str # ISO 3166-1 alpha-2 region code
163
language_code: str # BCP-47 language code
164
postal_code: str # Postal/ZIP code
165
sorting_code: str # Sorting code
166
administrative_area: str # State/province/prefecture
167
locality: str # City/town
168
sublocality: str # Sublocality/district/ward
169
address_lines: list[str] # Street address lines
170
recipients: list[str] # Recipients/addressees
171
organization: str # Organization name
172
```
173
174
### Text and Content Types
175
176
Localized text, color, and expression representations.
177
178
```python { .api }
179
from google.type.localized_text_pb2 import LocalizedText
180
from google.type.color_pb2 import Color
181
from google.type.expr_pb2 import Expr
182
183
class LocalizedText(message.Message):
184
"""Localized text content."""
185
text: str # Text content
186
language_code: str # BCP-47 language code
187
188
class Color(message.Message):
189
"""RGBA color representation."""
190
red: float # Red component (0.0-1.0)
191
green: float # Green component (0.0-1.0)
192
blue: float # Blue component (0.0-1.0)
193
alpha: float # Alpha/transparency (0.0-1.0)
194
195
class Expr(message.Message):
196
"""Expression representation (CEL - Common Expression Language)."""
197
expression: str # CEL expression
198
title: str # Expression title
199
description: str # Expression description
200
location: str # Source location information
201
```
202
203
## Usage Examples
204
205
### Working with Money
206
207
```python
208
from google.type.money_pb2 import Money
209
210
# Create a monetary amount ($29.99 USD)
211
price = Money()
212
price.currency_code = "USD"
213
price.units = 29
214
price.nanos = 990000000 # 0.99 * 10^9
215
216
# Create from float (be careful with floating point precision)
217
def money_from_float(currency_code: str, amount: float) -> Money:
218
money = Money()
219
money.currency_code = currency_code
220
money.units = int(amount)
221
money.nanos = int((amount - money.units) * 1_000_000_000)
222
return money
223
224
price = money_from_float("EUR", 42.50) # €42.50
225
```
226
227
### Working with Dates and Times
228
229
```python
230
from google.type.date_pb2 import Date
231
from google.type.datetime_pb2 import DateTime
232
from google.type.timeofday_pb2 import TimeOfDay
233
from google.protobuf.duration_pb2 import Duration
234
235
# Create a specific date
236
date = Date()
237
date.year = 2023
238
date.month = 12
239
date.day = 25
240
241
# Create a datetime with timezone
242
datetime = DateTime()
243
datetime.year = 2023
244
datetime.month = 12
245
datetime.day = 25
246
datetime.hours = 14
247
datetime.minutes = 30
248
datetime.seconds = 0
249
250
# Set UTC offset (-5 hours)
251
datetime.time_offset.utc_offset.seconds = -5 * 3600
252
253
# Create time of day
254
time = TimeOfDay()
255
time.hours = 14
256
time.minutes = 30
257
time.seconds = 45
258
time.nanos = 500000000 # 0.5 seconds
259
```
260
261
### Working with Geographic Coordinates
262
263
```python
264
from google.type.latlng_pb2 import LatLng
265
266
# Create coordinates for a location
267
location = LatLng()
268
location.latitude = 37.7749 # San Francisco latitude
269
location.longitude = -122.4194 # San Francisco longitude
270
271
# Validate coordinate ranges
272
def validate_coordinates(latlng: LatLng) -> bool:
273
return (-90 <= latlng.latitude <= 90 and
274
-180 <= latlng.longitude <= 180)
275
```
276
277
### Working with Phone Numbers
278
279
```python
280
from google.type.phone_number_pb2 import PhoneNumber
281
282
# Create E.164 format phone number
283
phone = PhoneNumber()
284
phone.e164_number = "+12125551234"
285
286
# Create short code
287
short_code_phone = PhoneNumber()
288
short_code_phone.short_code.region_code = "US"
289
short_code_phone.short_code.number = "911"
290
291
# Add extension
292
phone_with_ext = PhoneNumber()
293
phone_with_ext.e164_number = "+12125551234"
294
phone_with_ext.extension = "123"
295
```
296
297
### Working with Postal Addresses
298
299
```python
300
from google.type.postal_address_pb2 import PostalAddress
301
302
# Create a US postal address
303
address = PostalAddress()
304
address.revision = 1
305
address.region_code = "US"
306
address.language_code = "en"
307
address.postal_code = "10001"
308
address.administrative_area = "NY"
309
address.locality = "New York"
310
address.address_lines.extend([
311
"123 Main Street",
312
"Apt 4B"
313
])
314
address.recipients.append("John Doe")
315
address.organization = "Example Corp"
316
```
317
318
### Working with Colors
319
320
```python
321
from google.type.color_pb2 import Color
322
323
# Create RGB colors
324
red = Color()
325
red.red = 1.0
326
red.green = 0.0
327
red.blue = 0.0
328
red.alpha = 1.0 # Fully opaque
329
330
# Create semi-transparent blue
331
blue = Color()
332
blue.red = 0.0
333
blue.green = 0.0
334
blue.blue = 1.0
335
blue.alpha = 0.5 # 50% transparent
336
337
# Convert from hex color
338
def color_from_hex(hex_color: str) -> Color:
339
"""Convert hex color (#RRGGBB or #RRGGBBAA) to Color."""
340
hex_color = hex_color.lstrip('#')
341
342
color = Color()
343
color.red = int(hex_color[0:2], 16) / 255.0
344
color.green = int(hex_color[2:4], 16) / 255.0
345
color.blue = int(hex_color[4:6], 16) / 255.0
346
347
if len(hex_color) == 8: # Include alpha
348
color.alpha = int(hex_color[6:8], 16) / 255.0
349
else:
350
color.alpha = 1.0
351
352
return color
353
354
# Usage: color = color_from_hex("#FF5733")
355
```
356
357
### Working with Expressions
358
359
```python
360
from google.type.expr_pb2 import Expr
361
362
# Create a CEL expression for authorization
363
auth_expr = Expr()
364
auth_expr.expression = "request.auth.claims.sub == resource.owner"
365
auth_expr.title = "Resource Owner Check"
366
auth_expr.description = "Verify that the authenticated user owns the resource"
367
368
# Create a validation expression
369
validation_expr = Expr()
370
validation_expr.expression = "request.amount > 0 && request.amount <= 1000"
371
validation_expr.title = "Amount Validation"
372
validation_expr.description = "Ensure amount is positive and within limits"
373
```
374
375
### Time Interval Operations
376
377
```python
378
from google.type.interval_pb2 import Interval
379
from google.protobuf.timestamp_pb2 import Timestamp
380
import time
381
382
# Create time interval
383
interval = Interval()
384
385
# Set start time (current time)
386
start_time = Timestamp()
387
start_time.GetCurrentTime()
388
interval.start_time.CopyFrom(start_time)
389
390
# Set end time (1 hour later)
391
end_time = Timestamp()
392
end_time.seconds = start_time.seconds + 3600 # Add 1 hour
393
interval.end_time.CopyFrom(end_time)
394
395
# Check if timestamp is within interval
396
def is_in_interval(timestamp: Timestamp, interval: Interval) -> bool:
397
return (interval.start_time.seconds <= timestamp.seconds <=
398
interval.end_time.seconds)
399
```