Server‑side vs Client‑side DST offset resolution for ambiguous times in Google Calendar API

Answer to the core question

Google Calendar stores the event instant as UTC and keeps the supplied timeZone ID, but it does not expose which of the two possible offsets was chosen when the local time falls into a daylight‑saving fallback. Therefore:

• Server‑side flag: The API itself does not provide an explicit offset flag. If you need deterministic behavior across clients, you should store the chosen offset in a custom extension field (e.g., extendedProperties.customOffset) when creating the event.
• Client‑side resolution: Convert the UTC instant back to the original time zone using the same tzdata version that the server used. If you have stored the offset explicitly, use that value instead of relying on the client’s database.
• All‑day events: They are represented by a date string with no time component. The API treats them as whole days in the event’s time zone and they are not affected by DST transitions. No special handling is required.

Why an explicit offset matters

When the server’s tzdata is newer than a client’s, converting the same UTC instant can produce a different offset, shifting the local time by an hour. Storing the offset guarantees that every client, regardless of its tzdata version, displays the intended local time.

Practical steps for a safe workflow

1. Create the event:

   POST https://www.googleapis.com/calendar/v3/calendars/primary/events
   {
     "summary": "Fall back test",
     "start": {"dateTime": "2026-11-05T01:30:00", "timeZone": "America/New_York"},
     "end":   {"dateTime": "2026-11-05T02:30:00", "timeZone": "America/New_York"},
     "extendedProperties": {
       "private": {"customOffset": "-05:00"}
     }
   }
   

   The customOffset field records the offset that the server applied (here the earlier offset, UTC‑5).
2. Retrieve the event:

   GET https://www.googleapis.com/calendar/v3/calendars/primary/events/{eventId}
   

   The response includes start.dateTime (UTC) and the timeZone ID. If you stored customOffset, read it from extendedProperties.private.customOffset.
3. Convert back to local time on the client:
   • Use the same tzdata version as the server (e.g., the latest tzdata from the IANA database). In JavaScript:

     const utc = new Date(event.start.dateTime);
     const tz = event.start.timeZone;
     const local = utc.toLocaleString('en-US', { timeZone: tz });
     

   • If customOffset is present, override the conversion:

     const offsetMs = parseOffset(event.extendedProperties.private.customOffset) * 60 * 1000;
     const localMs = utc.getTime() + offsetMs;
     const localDate = new Date(localMs);
     

4. Verify consistency:
   • Print both the server‑reported UTC and the client‑computed local time.
   • Confirm that the offset matches the stored customOffset.

All‑day events – no DST drift

Because all‑day events use only a date field, Google Calendar treats them as spanning midnight UTC of the specified date. The timeZone ID is applied only for display purposes, so DST transitions do not alter the event’s span.

When to store the offset

• If you must support clients that may run older tzdata (e.g., legacy mobile apps), store the offset explicitly.
• If all clients run the same tzdata version as the server and you are confident it will stay current, you can omit the custom field and rely on the server’s choice.

Ask for missing diagnostic detail

If you cannot guarantee that all clients use the same tzdata version as the server, please confirm:

• Do you control the tzdata version on client devices, or do you need to support older releases?

Answering this will determine whether the custom offset field is necessary.