DateTime.AddZone
DateTimeAdds timezone offset information to a datetime value, returning a datetimezone.
Syntax
DateTime.AddZone(dateTime as datetime, timezoneHours as number, optional timezoneMinutes as nullable number) as datetimezoneParameters
| Name | Type | Required | Description |
|---|---|---|---|
dateTime | datetime | Yes | The datetime value to which the timezone offset will be added. |
timezoneHours | number | Yes | The hour component of the UTC offset (e.g., -5 for EST, 1 for CET). |
timezoneMinutes | number | No | The minutes component of the UTC offset. Defaults to 0. Use 30 for offsets like UTC+5:30. |
Return Value
datetimezone — A datetimezone value with the specified UTC offset applied to the input datetime.
Remarks
DateTime.AddZone annotates a datetime value with a UTC offset, producing a datetimezone. The time value itself is not adjusted — it is simply tagged with the given offset. This is distinct from DateTimeZone.SwitchZone, which converts a datetimezone to a different offset while preserving the underlying instant in time. Use DateTime.AddZone only when the datetime value already represents the correct local time for the target timezone and you simply need to add the offset annotation.
Use the optional timezoneMinutes parameter for non-whole-hour offsets such as UTC+5:30 (India Standard Time), UTC+9:30 (Australian Central Standard Time), or UTC+5:45 (Nepal Time). For offsets that are purely whole hours, omit timezoneMinutes or pass 0.
A common pattern is combining DateTime.AddZone with DateTimeZone.SwitchZone to normalize timestamps from multiple sources to a single reference timezone. First tag each value with its source timezone using DateTime.AddZone, then convert all values to UTC or your target timezone with DateTimeZone.SwitchZone.
Examples
Example 1: Tag datetime values with Eastern Standard Time offset
Table.AddColumn(
Table.SelectColumns(
Table.FirstN(OrderLog, 4),
{"LogID", "Timestamp"}
),
"TimestampEST",
each DateTime.AddZone([Timestamp], -5),
type datetimezone
)LogID | Timestamp | TimestampEST | |
|---|---|---|---|
| 1 | L001 | 1/15/2024 9:30:00 AM | 1/15/2024 2:30:00 PM |
| 2 | L002 | 1/16/2024 2:15:00 PM | 1/16/2024 7:15:00 PM |
| 3 | L003 | 1/18/2024 11:00:00 AM | 1/18/2024 4:00:00 PM |
| 4 | L004 | 1/20/2024 8:45:00 AM | 1/20/2024 1:45:00 PM |
Example 2: Apply a half-hour offset (UTC+5:30 for India)
#table(
type table [LocalTime = datetime, IST = datetimezone],
{{#datetime(2024, 3, 15, 12, 0, 0), DateTime.AddZone(#datetime(2024, 3, 15, 12, 0, 0), 5, 30)}}
)LocalTime | IST | |
|---|---|---|
| 1 | 3/15/2024 12:00:00 PM | 3/15/2024 6:30:00 AM |
Example 3: Tag and then convert to UTC
let
LocalTime = #datetime(2024, 3, 15, 9, 0, 0),
WithZone = DateTime.AddZone(LocalTime, -5),
AsUTC = DateTimeZone.SwitchZone(WithZone, 0)
in
#table(
type table [LocalEST = datetimezone, UTC = datetimezone],
{{WithZone, AsUTC}}
)LocalEST | UTC | |
|---|---|---|
| 1 | 3/15/2024 2:00:00 PM | 3/15/2024 2:00:00 PM |