Client‑side versus Server‑side Time‑Zone Handling for Mapbox GL JS Temporal Layers

Question

Goal: Allow map viewers to switch between time zones for temporal data displayed in Mapbox GL JS without sacrificing frame‑rate or introducing date‑offset errors.
Constraint: Performing the conversion client‑side with new Date() gives each user zone flexibility but adds per‑feature CPU work and can produce different historic offsets across browsers because each implements its own IANA database version. Pre‑converting timestamps server‑side (e.g., storing UTC strings in vector tile properties) removes the per‑frame cost but locks the map to a single zone, requiring a full tile rebuild whenever the target zone changes.
Which strategy provides the best trade‑off between dynamic user zone selection and render performance for large feature sets? How can historic offset inconsistencies be minimized when relying on client‑side Date objects?

Tasadduq Burney · Answer

The Optimal Strategy: Numeric UTC with Client-Side Offsets
The best trade-off between dynamic user selection and render performance is to store timestamps as numeric UTC integers (Unix epoch) within vector tile properties and apply a single, global offset variable on the client side. This avoids the need to rebuild tiles on the server while bypassing the CPU overhead of per-feature Date object instantiation during the render loop.

Implementation Logic
Instead of converting every feature's timestamp to a local time zone, treat the time zone selection as a mathematical shift applied to the filter criteria rather than the data itself.

Data Storage: Store timestamps in your vector tiles as integers (milliseconds or seconds since epoch). Avoid ISO 8601 strings, as string parsing in a render loop significantly degrades frame rates.
Filter Calculation: When a user selects a time zone, calculate the current offset for that zone in milliseconds.
Application: Apply the offset to the filter value passed to setFilter(). For example, if the user wants to see data for "12:00 PM EST," calculate the UTC equivalent and filter the numeric properties against that single UTC value.

Minimizing Historic Offset Inconsistencies
Relying on the native Date object is risky for historical data because different browser engines may use different versions of the IANA Time Zone Database. To ensure deterministic behavior across all clients:

Use a Standardized Library: Implement a library like Luxon or date-fns-tz. These libraries provide a consistent way to handle IANA zones and offsets independently of the browser's native Intl implementation.
Avoid Native Date Instantiation: Do not call new Date() inside the map.on('render', ...) loop. Perform all time-zone calculations once per UI change and store the resulting numeric UTC timestamp in a variable.

Verification and Performance
To verify this approach, you can monitor the frame rate (FPS) using the browser's performance profiling tools. Compare the cost of setFilter(['>=', 'timestamp', utcValue]) against a custom filter that invokes new Date() for every feature. The numeric comparison is handled by the Mapbox GL JS engine (often via GPU/WebGL), whereas Date objects force a move back to the main CPU thread.

Diagnostic Detail Needed: Are you utilizing Mapbox's built-in setFilter for visibility, or are you manually iterating through features to update styles/properties via a custom render loop?

Client‑side versus Server‑side Time‑Zone Handling for Mapbox GL JS Temporal Layers

1 answer

The Optimal Strategy: Numeric UTC with Client-Side Offsets

Implementation Logic

Minimizing Historic Offset Inconsistencies

Verification and Performance

Your perspective belongs here.

0 question comments