Skip to content
Tutorials Center
My learning

Topics

Java Reference ยท Date and Time

ZoneId and ZoneOffset

Reference for java.time ZoneId and ZoneOffset: region IDs versus fixed offsets, looking up zone rules, daylight saving transitions and converting between zones.

A time zone tells you how to turn a point on the global timeline into a local date and time. Java models this with two related classes. ZoneId identifies a zone by its region name, such as Europe/Paris or America/New_York, and carries the rules for that region, including every daylight saving change in history. ZoneOffset is a subclass of ZoneId for a fixed difference from UTC, such as +05:30, with no rules and no changes over time.

Use a region ZoneId when you mean "the clock in that place" and a ZoneOffset when you only have a fixed offset, for example from a stored timestamp or a protocol header.

Java
ZoneId paris = ZoneId.of("Europe/Paris");
ZoneOffset plusTwo = ZoneOffset.ofHours(2);

Try it

Java Region zones and offsets

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

Java Daylight saving gaps and overlaps

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

Syntax

Java
static ZoneId of(String zoneId)
static ZoneId systemDefault()
static ZoneOffset of(String offsetId)
static ZoneOffset ofHours(int hours)
static ZoneOffset ofHoursMinutes(int hours, int minutes)
static ZoneOffset ofTotalSeconds(int totalSeconds)
Member Description
ZoneId.of(id) A region ID, "Z", an offset like "+02:00", or a prefixed form like "UTC+2".
ZoneId.systemDefault() The JVM's default zone; depends on the machine, so avoid it in logic that must be reproducible.
ZoneId.getAvailableZoneIds() The set of known region IDs (about 600).
getRules() A ZoneRules object: getOffset(...), getStandardOffset(...), isDaylightSavings(...), getTransitions().
normalized() Collapses a fixed-offset zone to a ZoneOffset.
ZoneOffset.UTC Offset zero.
getTotalSeconds() The offset in seconds (ZoneOffset only).

Throws: ZoneRulesException for an unknown region ID; DateTimeException for a malformed ID or an offset outside -18:00 to +18:00.

Usage notes

  • Always prefer region IDs. A stored +01:00 is wrong for half the year if you meant "Paris time". Keep the region ID and let the rules produce the offset.
  • Three-letter abbreviations are ambiguous. ZoneId.of("EST") and ZoneId.of("PST") throw ZoneRulesException unless you pass the ZoneId.SHORT_IDS map as a second argument; use America/New_York.
  • Gaps and overlaps. When a local time falls in a gap, atZone shifts it forward by the length of the gap; in an overlap it picks the earlier offset. Use withEarlierOffsetAtOverlap() or withLaterOffsetAtOverlap() to choose.
  • Tzdb changes. Governments change rules. The data ships with the JDK, so very old runtimes can have stale rules for future dates.
  • ZoneOffset is a ZoneId. Both can be passed wherever a ZoneId is accepted; an OffsetDateTime takes only a ZoneOffset.
  • ZoneId.of("UTC") is not equal to ZoneOffset.UTC. They behave the same for conversions but are different classes; call normalized() on the ZoneId before comparing (it then equals ZoneOffset.UTC).
  • Immutable and thread-safe. Cache them in constants.