Timestamp-offset field

This sample demonstrates the use of the queryFeatures() method to retrieve count statistics on accidents data from a FeatureLayer based on timestamp-offset field values, grouping the counts by time of day, days of the week, or months.

Three new date and time fields were added at version 4.28:

Field typeDescriptionExampleUse cases
The date-onlyDate-only fields support date values with no time values.2018-09-01Data that was captured in the granularity of days or attribute values that apply to, or represent, the entire day. Start or end date of a school semester, Aggregating total number of hurricanes based on the year they occur
The time-onlyTime-only fields support time values with no date value.15:35:23Data that repeats daily or content for which only the time component matters. Business or store opening and closing hours. Bus or train schedule.
The timestamp-offsetTimestamp offset fields support a date, time, and time zone offset from the Coordinated Universal Time (UTC) zone.2015-09-24T21:58:00-09:00Time values for which the local time value is important and the dates can cross multiple time zones. Crimes, earthquake, traffic incidents, airline managing departure and arrival schedules worldwide, while also understanding the local time for passengers.

The map displays fatal accidents of 2021 with different colors depending on which time of the day accident happened. The data was downloaded from Fatality Analysis Reporting System.

How it works

When the application starts, the UI features the Total Accidents by Time of Day chart in the upper right corner. Users can easily view daily, weekly, and monthly accident charts by simply clicking on the corresponding buttons. Furthermore, users can enhance their experience by clicking on specific bars within a chart, which in turn filters and displays accidents on the map according to the selected time period. In the case of clicking on a bar within the weekly or monthly chart, an additional chart will appear, offering users a breakdown of daily accident distribution within their chosen time frame.

Three statistical queries to generate chart data when the application loads. For example, the Total accidents by time of day chart data is efficiently prepared using timestamp-offset values, which are stored with their respective UTC offsets. This approach enables us to conduct time-based analysis seamlessly across multiple time zones, as 8 AM remains 8 AM regardless of the geographical location.

Use dark colors for code blocksCopy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
// prepare data for total accidents by time of day chart
let hourData = [], hourLabels = [];

// run stats query to return total number of accidents by time of day
// stats results will be grouped by the time of day
const hourResult = await runQuery("extract(hour from tsodate)");
hourResult.features.forEach((feature) => {
  hourData.push(feature.attributes["count"]);
  hourLabels.push(feature.attributes["EXPR_1"]);
});

// create a bar chart showing total number of accidents by time of day
updateChart("chart-day", hourData, hourLabels);

// this function is called 3 times when the app loads and generates
// count stats for accidents 1. by time of day 2. by day of week and 3. by month
async function runQuery(groupStats) {
  // create a query object that honors the layer settings
  let query = layer.createQuery();
  query.where = "1=1";
  query.outStatistics = [{
    "statisticType": "count",
    "onStatisticField": "*",
    "outStatisticFieldName": "count"
  }];
  query.groupByFieldsForStatistics = [groupStats];
  query.orderByFields = [groupStats];
  let result = await layer.queryFeatures(query);
  return result;
}

A unique value renderer is applied to the layer to symbolize accidents with distinct colors based on the time of day they occurred. The Arcade expression is used to extract hours from the timestamp-offset field and distinct colors are assigned to the feature based on the hour as shown below.

Use dark colors for code blocksCopy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
let renderer = {
  type: "unique-value",
  valueExpression: `
    var d = $feature.TSODate;
    var h = Hour(d);

    When(
      h <= 6, "night",
      h <= 12, "morning",
      h <= 18, "afternoon",
      "evening"
    );
  `,
  uniqueValueInfos: [{
    value: "morning",
    symbol: createSymbol("purple")
  }, {
    value: "afternoon",
    symbol: createSymbol("orange")
  }, {
    value: "evening",
    symbol: createSymbol("blue")
  }, {
    value: "night",
    symbol: createSymbol("black")
  }],
  defaultSymbol: createSymbol("gray"),
};

The timestamp-offset field values are displayed as they are stored in the service, including an abbreviated time zone suffix. This formatting is achieved using the Arcade Text function, as demonstrated below.

Use dark colors for code blocksCopy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
let popupTemplate = {
  title: "Crash information",
  fieldInfos: [
    {
      fieldName: "expression/TSO-from-server",
    }
  ],
  expressionInfos: [{
    // timestamp-offset field will display in the time zone from the server
    // with an abbreviated time zone suffix
    expression: `Text($feature.TSODate, "M/D/Y, h:mm A ZZZZ")`,
    name: "TSO-from-server",
  }],
  content: [{
    type: "fields"
  }]
};

Your browser is no longer supported. Please upgrade your browser for the best experience. See our browser deprecation post for more details.