Skip to main content

Time Series Data

Query historical data from device parameters that support time series storage.

info

For parameters outside node config, see Custom Parameter Time Series.

What This Module Does ?​

Query historical values for device parameters that store time series—energy, temperature, sensor readings—with date ranges, pagination, and optional aggregation.

Use this for charts, trend analysis, and reporting. Parameters need "time_series" or "simple_ts" in their properties array.

Not in node config? Use Custom Parameter Time Series.

Expected outcome: Timestamp/value data points (and optional pagination) for the requested range.

Common Workflows​

Fetch last 24 hours​

const { nodes } = await userInstance.getUserNodes();
const nodeConfig = nodes[0].nodeConfig ?? (await nodes[0].getNodeConfig());

const param = nodeConfig.devices[0].params.find(
  (p) => p.properties?.includes("time_series")
);

const response = await param.getRawTSData({
  startTime: Date.now() - 24 * 60 * 60 * 1000,
  endTime: Date.now(),
  resultCount: 100,
});

response.tsData.forEach((point) => {
  console.log(new Date(point.timestamp), point.value);
});

Find time-series parameters​

device.params.forEach((param) => {
  if (param.properties?.includes("time_series") || param.properties?.includes("simple_ts")) {
    console.log(`${param.name} supports time series`);
  }
});

Raw data with pagination​

let tsResponse = await param.getRawTSData({
  startTime: startTimestamp,
  endTime: endTimestamp,
  resultCount: 100,
  timezone: "America/Los_Angeles",
});

while (tsResponse.hasNext) {
  tsResponse = await tsResponse.fetchNext();
}

Aggregated data​

const tsResponse = await param.getTSData({
  startTime: startTimestamp,
  endTime: endTimestamp,
  numIntervals: 24,
  aggregate: "avg",
  aggregationInterval: "hour",
});

Simple query​

const tsResponse = await param.getSimpleTSData({
  startTime: startTimestamp,
  endTime: endTimestamp,
  resultCount: 50,
});

Error Handling​

try {
  if (!param.properties?.includes("time_series")) return;
  await param.getRawTSData(request);
} catch (error) {
  console.error("Time series query failed:", error);
}

Advanced Concepts​

Choosing a query method​

Best Practices​

  1. Check properties before querying
  2. Paginate large ranges
  3. Set timezone for accurate boundaries
  4. Prefer getSimpleTSData() unless you need aggregation

On this page