Time series data

Time series Data Views are designed to return data grouped and aggregated based on a specified time interval. The data is always returned as a JSON array, with each object representing a single data point within that interval and grouped by the configured fields.

For a DataView storing sales information with the following structure:

Key concepts

• Data Shape: The overall structure of the data returned, determined by the View configuration. In this case the Data View is configured with a Time Series data shape.
• Interval Field: A designated field in the underlying Data Pool that determines the time interval over which data is aggregated.
• Aggregation: The function used to accumulate the values of individual records (eg. sum, average, etc).

Sales data example

Let's examine a specific example of a Time Series Data View for sales information. This view is configured to return sales data aggregated by hour.

Given this configuration, a request for data at an hour interval might return a JSON structure like this:

{
  "data": [
    {
      "event": "20250101T10:00:00Z",
      "saleAmount": 59374,
      "saleType": "online"
    },
    {
      "event": "20250101T10:00:00Z",
      "saleAmount": 1881,
      "saleType": "in-store"
    },
    {
      "event": "20250101T11:00:00Z",
      "saleAmount": 0,
      "saleType": "online"
    },
    {
      "event": "20250101T11:00:00Z",
      "saleAmount": 12818,
      "saleType": "in-store"
    },
      {
      "event": "20250101T12:00:00Z",
      "saleAmount": 19191,
      "saleType": "online"
    },
    {
      "event": "20250101T12:00:00Z",
      "saleAmount": 9181,
      "saleType": "in-store"
    },
    ...
  ]
}

Explanation of the Output:

• event: This field contains a timestamp representing the beginning of the hour (e.g., "20250101T10:00:00Z"). This is the interval field that defines the time granularity of the data.
• saleAmount: The sum of sales for that hour, categorized by saleType.
• saleType: The distinct type of sale (e.g., "online", "in-store") associated with the data point.

Notice that the event timestamp is repeated for each hour. This is because the view is aggregating data within that hourly interval. This ensures that all available records within the specified time interval are included in the returned data.

Handling Missing Data

The dataset is ensured to be complete. If there are no records for a given interval or grouping within the interval the record will be filled in with the appropriate interval time and base line values. In this example a saleAmount of zero would be used.

The event interval

The Data View configuration includes a default interval for data retrieval. This interval can be overridden on a per-request basis by specifying an interval field within the request payload. Supported intervals are

The following intervals are allowed:

Example request

{
  "interval": "day"
}

Time window

Egress Endpoints, by default, deliver data based on a time range centered around the current timestamp. Specifically, data is returned starting at the current time and extending backward for 100 intervals.

However, a time window can be explicitly specified during the request. This allows you to control the temporal scope of the data returned.

Example request

{
  "start": "20250101T05:00:00Z",
  "end": "20250201T05:00:00Z"
}