ArcGIS Maps SDK for JavaScript version 4.8 (JavaScript Maps SDK) introduced three new date-focused field types—date only, time only, and timestamp offset—to represent different levels of information when working with date and time values. The values stored in these fields adhere to ISO8601-compliant formats.
These new field types are supported on FeatureLayer and MapImageLayers, with plans to extend their support to other layers in future releases. The timestamp offset field type efficiently stores both date and time along with the corresponding time zone offset in the following format: YYYY-MM-DDTHH:MM:SS.sss+/-UTC offset.
Before the introduction of these fields, date and time values were stored as epoch values in the date field type. Epoch values represent a point in time as the number of seconds that have passed since January 1st, 1970, at 00:00:00 (the Unix epoch). For example, October 19, 2021, at midnight in UTC is represented as an epoch value as 1634630400. However, epoch values do not store time zone information, so all values stored in date fields are in the same time zone. This behavior makes it challenging to perform time-based analysis spanning multiple time zones.
This is where timestamp offset fields prove to be invaluable. They are particularly useful for mapping events that occur across various time zones. Practical applications for timestamp offset values are diverse and include data such as flight departures and arrivals, crime statistics, or whenever it is advantageous to persist the local time of an event in the data.
The Timestamp Offset in Action
This article explores the power of timestamp offset field values for visualization and analysis and demonstrates the advantages of using the new timestamp offset field.
This sample application visualizes all 2021 fatal car accidents across time zones in the United States. The data is color coded by the time of day, that is, morning, afternoon, evening, and night. This data was obtained from the Fatality Analysis Reporting System (FARS) provided by the National Highway Traffic Safety Administration. View the source code for this application.
Visualizing Accidents by Time of Day
Let’s examine how the unique value renderer is created for the accidents layer. It uses an ArcGIS Arcade expression to extract the local time—specifically the hour—that each car accident occurred.
The process of obtaining the local time from a timestamp offset field is relatively simple, as demonstrated in Listing 1 which uses an Arcade expression containing the hour function to extract the hour an incident occurred. For example, data captured at 8:00 am in Hawaii and data captured at 8:00 am in New York would both be classified as morning because both were captured in the morning relative to their time zones. Had these incidents been stored in a traditional date field, each location’s time zone would have to be inferred. For national or global datasets, this can be difficult or impossible.
Depicting the Distribution of Accidents on Charts
The charts displayed on the right side of the application offer a breakdown of the total number of accidents based on time of day, weekdays, and months. In the weekday chart, you can explore accident data by hours for the selected day of the week, while the monthly chart provides a breakdown of accidents by days within the chosen month. An analysis of accidents by hours on weekdays highlights the noticeable increase in accidents during late-night and early morning hours, particularly on weekends.
These charts are generated by querying the dataset to obtain accident counts. The query involves extracting information about the hour, day, and month from the timestamp offset field available in the service. For example, the total accidents by time of day chart data is efficiently prepared using timestamp offset values. This approach enables seamless time-based analysis across multiple time zones. For example, data captured at 8:00 am in Hawaii with data captured at 8:00 am in New York can be compared because both were recorded in the morning relative to their respective time zones.
While it may have been possible to generate this information using a traditional date field, it would have required additional information, such as the state, to determine the localized time offset and ultimately the local time of each accident. This is complicated by the fact that some dates honor Daylight Saving Time while others do not. The code in Listing 2 demonstrates how the data for the total accidents by time of day chart is prepared. It involves querying the accident data, extracting the hours from the timestamp offset field values, and obtaining the total count of accidents grouped by the hours.
Aggregation Based on Timestamp Offset Field
In the example in Listing 2, a unique value renderer is assigned to the accidents layer to show what time of day accidents occurred. The visualization can be changed by aggregating the accidents based on time of the accident.
The application demonstrates how accident data can be presented as clustered pie charts. This demonstrates the benefit of using timestamp offset with data that spans multiple time zones. Chart size corresponds to the overall number of fatal car incidents and the size of each slice illustrates when during the day or night the accidents occurred.
The size of each pie can be varied based on data with any other field value or Arcade expression using visual variables. The total accidents by time of day chart automatically updates as the user zooms or pans the map. The chart updates dynamically by reprocessing in-memory data without requesting additional content from the server. This technique is called client-side query. View the app.
Summary
If you are working with temporal data spanning multiple time zones, then timestamp offset may be advantageous for certain time-based queries and answering specific questions.
For example, what time of day has the most accidents across the US? This would require trans-time zone comparison. Storing event instances in timestamp offset fields allows for easy inter-time zone comparison and analysis. For another example, what are the best operating hours for a new coffee stop in Los Angeles? Analysis of national store transactions could provide the answer.
If a coffee chain wanted to know which store sold the most on Christmas day, aggregating data irrespective of time zone would show higher-level trends but would unfairly base statistics in a specific time zone. Instead, temporal aggregation uses the local time zone of each store and data aggregated by local hour, day, week, and month. This shows the advantage of timestamp offset over traditional storage as epoch values in the date field type.
Resources
“Time Is on Your Side with New Field Types in ArcGIS Online”
“8 ways to style point clusters on the web”
“Turbo charge your web apps with client-side queries” .
About the author
