0
# Common Data Types
1

2
Standard data types shared across Google APIs for representing time, money, geographic coordinates, and other common concepts. These types provide consistent representation and behavior across different services.
3

4
## Temporal Types
5

6
### Date
7

8
Calendar date representation (year, month, day).
9

10
```java { .api }
11
class Date {
12
  int getYear();
13
  int getMonth();  // 1-12
14
  int getDay();    // 1-31
15
  
16
  static Date.Builder newBuilder();
17
  Date.Builder toBuilder();
18
  static Date parseFrom(byte[] data);
19
}
20

21
interface DateOrBuilder {
22
  int getYear();
23
  int getMonth();
24
  int getDay();
25
}
26
```
27

28
### DateTime
29

30
Date and time with timezone information.
31

32
```java { .api }
33
class DateTime {
34
  int getYear();
35
  int getMonth();
36
  int getDay();
37
  int getHours();
38
  int getMinutes();
39
  int getSeconds();
40
  int getNanos();
41
  TimeZone getTimeZone();
42
  Duration getUtcOffset();
43
  
44
  static DateTime.Builder newBuilder();
45
}
46
```
47

48
### TimeOfDay
49

50
Time within a day (hour, minute, second, nanos).
51

52
```java { .api }
53
class TimeOfDay {
54
  int getHours();    // 0-23
55
  int getMinutes();  // 0-59
56
  int getSeconds();  // 0-59
57
  int getNanos();    // 0-999,999,999
58
  
59
  static TimeOfDay.Builder newBuilder();
60
}
61
```
62

63
### TimeZone
64

65
IANA timezone representation.
66

67
```java { .api }
68
class TimeZone {
69
  String getId();      // e.g., "America/New_York"
70
  String getVersion();
71
  
72
  static TimeZone.Builder newBuilder();
73
}
74
```
75

76
### Interval
77

78
Time interval with start and end times.
79

80
```java { .api }
81
class Interval {
82
  Timestamp getStartTime();
83
  Timestamp getEndTime();
84
  
85
  static Interval.Builder newBuilder();
86
}
87
```
88

89
## Monetary Types
90

91
### Money
92

93
Monetary amount with currency code.
94

95
```java { .api }
96
class Money {
97
  String getCurrencyCode();  // ISO 4217 currency code
98
  long getUnits();          // Whole units of currency
99
  int getNanos();           // Number of nano units (10^-9)
100
  
101
  static Money.Builder newBuilder();
102
  Money.Builder toBuilder();
103
}
104

105
interface MoneyOrBuilder {
106
  String getCurrencyCode();
107
  long getUnits();
108
  int getNanos();
109
}
110
```
111

112
### Decimal
113

114
Arbitrary precision decimal number.
115

116
```java { .api }
117
class Decimal {
118
  String getValue();  // String representation of decimal
119
  
120
  static Decimal.Builder newBuilder();
121
}
122
```
123

124
### Fraction
125

126
Mathematical fraction with numerator and denominator.
127

128
```java { .api }
129
class Fraction {
130
  long getNumerator();
131
  long getDenominator();
132
  
133
  static Fraction.Builder newBuilder();
134
}
135
```
136

137
## Geographic Types
138

139
### LatLng
140

141
Latitude/longitude coordinate pair.
142

143
```java { .api }
144
class LatLng {
145
  double getLatitude();   // -90.0 to +90.0
146
  double getLongitude();  // -180.0 to +180.0
147
  
148
  static LatLng.Builder newBuilder();
149
}
150
```
151

152
### PostalAddress
153

154
Structured postal address.
155

156
```java { .api }
157
class PostalAddress {
158
  int getRevision();
159
  String getRegionCode();
160
  String getLanguageCode();
161
  String getPostalCode();
162
  String getSortingCode();
163
  String getAdministrativeArea();
164
  String getLocality();
165
  String getSublocality();
166
  repeated String getAddressLinesList();
167
  repeated String getRecipientsList();
168
  String getOrganization();
169
  
170
  static PostalAddress.Builder newBuilder();
171
}
172
```
173

174
## Visual and UI Types
175

176
### Color
177

178
Color representation supporting multiple formats.
179

180
```java { .api }
181
class Color {
182
  float getRed();     // 0.0 to 1.0
183
  float getGreen();   // 0.0 to 1.0
184
  float getBlue();    // 0.0 to 1.0
185
  FloatValue getAlpha();  // Optional alpha channel
186
  
187
  static Color.Builder newBuilder();
188
}
189
```
190

191
### LocalizedText
192

193
Text with language code for internationalization.
194

195
```java { .api }
196
class LocalizedText {
197
  String getText();
198
  String getLanguageCode();  // BCP-47 language tag
199
  
200
  static LocalizedText.Builder newBuilder();
201
}
202
```
203

204
## Utility Types
205

206
### Expr
207

208
Expression for conditions and transformations using CEL (Common Expression Language).
209

210
```java { .api }
211
class Expr {
212
  String getExpression();  // CEL expression
213
  String getTitle();
214
  String getDescription();
215
  String getLocation();
216
  
217
  static Expr.Builder newBuilder();
218
}
219
```
220

221
### PhoneNumber
222

223
International phone number representation.
224

225
```java { .api }
226
class PhoneNumber {
227
  string getE164Number();      // E.164 format (e.g., "+15551234567")
228
  ShortCode getShortCode();
229
  string getExtension();
230
  
231
  static PhoneNumber.Builder newBuilder();
232
}
233

234
class PhoneNumber.ShortCode {
235
  string getRegionCode();
236
  string getNumber();
237
  
238
  static ShortCode.Builder newBuilder();
239
}
240
```
241

242
### Quaternion
243

244
3D rotation representation using quaternions.
245

246
```java { .api }
247
class Quaternion {
248
  double getX();
249
  double getY();
250
  double getZ();
251
  double getW();
252
  
253
  static Quaternion.Builder newBuilder();
254
}
255
```
256

257
## Calendar and Date Enums
258

259
### DayOfWeek
260

261
Days of the week enumeration.
262

263
```java { .api }
264
enum DayOfWeek {
265
  DAY_OF_WEEK_UNSPECIFIED(0),
266
  MONDAY(1),
267
  TUESDAY(2),
268
  WEDNESDAY(3),
269
  THURSDAY(4),
270
  FRIDAY(5),
271
  SATURDAY(6),
272
  SUNDAY(7);
273
  
274
  int getNumber();
275
  static DayOfWeek forNumber(int value);
276
}
277
```
278

279
### Month
280

281
Calendar months enumeration.
282

283
```java { .api }
284
enum Month {
285
  MONTH_UNSPECIFIED(0),
286
  JANUARY(1),
287
  FEBRUARY(2),
288
  MARCH(3),
289
  APRIL(4),
290
  MAY(5),
291
  JUNE(6),
292
  JULY(7),
293
  AUGUST(8),
294
  SEPTEMBER(9),
295
  OCTOBER(10),
296
  NOVEMBER(11),
297
  DECEMBER(12);
298
  
299
  int getNumber();
300
  static Month forNumber(int value);
301
}
302
```
303

304
### CalendarPeriod
305

306
Calendar period types for recurring events.
307

308
```java { .api }
309
enum CalendarPeriod {
310
  CALENDAR_PERIOD_UNSPECIFIED(0),
311
  DAY(1),
312
  WEEK(2),
313
  FORTNIGHT(3),
314
  MONTH(4),
315
  QUARTER(5),
316
  HALF(6),
317
  YEAR(7);
318
  
319
  int getNumber();
320
  static CalendarPeriod forNumber(int value);
321
}
322
```
323

324
## Usage Examples
325

326
### Working with Money
327

328
```java
329
import com.google.type.Money;
330

331
// Create $29.99 USD
332
Money price = Money.newBuilder()
333
    .setCurrencyCode("USD")
334
    .setUnits(29)
335
    .setNanos(990000000)  // 0.99 * 10^9
336
    .build();
337

338
// Create €15.50 EUR
339
Money euroPrice = Money.newBuilder()
340
    .setCurrencyCode("EUR")
341
    .setUnits(15)
342
    .setNanos(500000000)  // 0.50 * 10^9
343
    .build();
344

345
// Convert to decimal representation
346
double priceAsDouble = price.getUnits() + (price.getNanos() / 1_000_000_000.0);
347
System.out.println("Price: " + price.getCurrencyCode() + " " + priceAsDouble);
348
```
349

350
### Working with Dates and Times
351

352
```java
353
import com.google.type.Date;
354
import com.google.type.TimeOfDay;
355
import com.google.type.DateTime;
356

357
// Create a date
358
Date birthday = Date.newBuilder()
359
    .setYear(1990)
360
    .setMonth(6)   // June
361
    .setDay(15)
362
    .build();
363

364
// Create a time
365
TimeOfDay meetingTime = TimeOfDay.newBuilder()
366
    .setHours(14)    // 2 PM
367
    .setMinutes(30)
368
    .setSeconds(0)
369
    .build();
370

371
// Create date and time together
372
DateTime appointment = DateTime.newBuilder()
373
    .setYear(2024)
374
    .setMonth(3)
375
    .setDay(15)
376
    .setHours(10)
377
    .setMinutes(30)
378
    .build();
379
```
380

381
### Working with Geographic Coordinates
382

383
```java
384
import com.google.type.LatLng;
385
import com.google.type.PostalAddress;
386

387
// Google headquarters coordinates
388
LatLng googleHQ = LatLng.newBuilder()
389
    .setLatitude(37.4220656)
390
    .setLongitude(-122.0840897)
391
    .build();
392

393
// Create postal address
394
PostalAddress address = PostalAddress.newBuilder()
395
    .setRegionCode("US")
396
    .setPostalCode("94043")
397
    .setAdministrativeArea("CA")
398
    .setLocality("Mountain View")
399
    .addAddressLines("1600 Amphitheatre Parkway")
400
    .addRecipients("Google LLC")
401
    .build();
402
```
403

404
### Working with Colors
405

406
```java
407
import com.google.type.Color;
408
import com.google.protobuf.FloatValue;
409

410
// Create red color
411
Color red = Color.newBuilder()
412
    .setRed(1.0f)
413
    .setGreen(0.0f)
414
    .setBlue(0.0f)
415
    .build();
416

417
// Create semi-transparent blue
418
Color transparentBlue = Color.newBuilder()
419
    .setRed(0.0f)
420
    .setGreen(0.0f)
421
    .setBlue(1.0f)
422
    .setAlpha(FloatValue.of(0.5f))  // 50% transparency
423
    .build();
424
```
425

426
### Working with Expressions
427

428
```java
429
import com.google.type.Expr;
430

431
// Create a CEL expression for access control
432
Expr accessCondition = Expr.newBuilder()
433
    .setExpression("request.auth.claims.email.endsWith('@company.com')")
434
    .setTitle("Company Email Required")
435
    .setDescription("Only users with company email addresses can access this resource")
436
    .build();
437

438
// Create a validation expression
439
Expr ageValidation = Expr.newBuilder()
440
    .setExpression("request.age >= 18 && request.age <= 120")
441
    .setTitle("Valid Age Range")
442
    .setDescription("Age must be between 18 and 120")
443
    .build();
444
```
445

446
### Phone Number Handling
447

448
```java
449
import com.google.type.PhoneNumber;
450

451
// Create E.164 format phone number
452
PhoneNumber phoneNumber = PhoneNumber.newBuilder()
453
    .setE164Number("+15551234567")
454
    .build();
455

456
// Create short code
457
PhoneNumber.ShortCode shortCode = PhoneNumber.ShortCode.newBuilder()
458
    .setRegionCode("US")
459
    .setNumber("12345")
460
    .build();
461

462
PhoneNumber shortPhoneNumber = PhoneNumber.newBuilder()
463
    .setShortCode(shortCode)
464
    .build();
465
```
466

467
## Validation and Constraints
468

469
### Money Validation
470

471
```java
472
public boolean isValidMoney(Money money) {
473
    if (money.getCurrencyCode().isEmpty() || money.getCurrencyCode().length() != 3) {
474
        return false; // Invalid currency code
475
    }
476
    
477
    if (money.getNanos() < 0 || money.getNanos() >= 1_000_000_000) {
478
        return false; // Invalid nanos value
479
    }
480
    
481
    if (money.getUnits() < 0 && money.getNanos() > 0) {
482
        return false; // Sign mismatch
483
    }
484
    
485
    return true;
486
}
487
```
488

489
### Date Validation
490

491
```java
492
public boolean isValidDate(Date date) {
493
    if (date.getYear() < 1 || date.getMonth() < 1 || date.getMonth() > 12) {
494
        return false;
495
    }
496
    
497
    if (date.getDay() < 1 || date.getDay() > 31) {
498
        return false;
499
    }
500
    
501
    // Additional validation for days per month would go here
502
    return true;
503
}
504
```
505

506
### Coordinate Validation
507

508
```java
509
public boolean isValidLatLng(LatLng latLng) {
510
    double lat = latLng.getLatitude();
511
    double lng = latLng.getLongitude();
512
    
513
    return lat >= -90.0 && lat <= 90.0 && lng >= -180.0 && lng <= 180.0;
514
}
515
```
516

517
## Conversion Utilities
518

519
### Money to String
520

521
```java
522
public String formatMoney(Money money) {
523
    double amount = money.getUnits() + (money.getNanos() / 1_000_000_000.0);
524
    return String.format("%s %.2f", money.getCurrencyCode(), amount);
525
}
526

527
public Money parseMoney(String currencyCode, double amount) {
528
    long units = (long) amount;
529
    int nanos = (int) ((amount - units) * 1_000_000_000);
530
    
531
    return Money.newBuilder()
532
        .setCurrencyCode(currencyCode)
533
        .setUnits(units)
534
        .setNanos(nanos)
535
        .build();
536
}
537
```
538

539
### Date Conversion
540

541
```java
542
import java.time.LocalDate;
543

544
public LocalDate toLocalDate(Date date) {
545
    return LocalDate.of(date.getYear(), date.getMonth(), date.getDay());
546
}
547

548
public Date fromLocalDate(LocalDate localDate) {
549
    return Date.newBuilder()
550
        .setYear(localDate.getYear())
551
        .setMonth(localDate.getMonthValue())
552
        .setDay(localDate.getDayOfMonth())
553
        .build();
554
}
555
```