Time Series Data

Certain device parameters support time series data retrieval. These parameters can be identified by checking if their properties array contains either "time_series" or "simple_ts". When a device parameter has these properties, it indicates that the parameter is a time series parameter and can access historical data using specialized methods.

Identifying Time Series Parameters

To check if a parameter supports time series data, examine its properties array:

try {
  const response = await userInstance.getUserNodes();
  const node = response.nodes[0];
  const nodeConfig = node.nodeConfig || await node.getNodeConfig();
  
  // Check device parameters for time series support
  nodeConfig.devices.forEach((device) => {
    device.params?.forEach((param) => {
      if (param.properties && (
        param.properties.includes("time_series") || 
        param.properties.includes("simple_ts")
      )) {
        console.log(`Device parameter ${param.name} supports time series data`);
        // This parameter can use getRawTSData, getSimpleTSData, or getTSData
      }
    });
  });
} catch (error) {
  console.error("Error checking time series parameters:", error);
}

Retrieving Time Series Data

Time series parameters support three methods for retrieving historical data:

1. getRawTSData - Retrieves raw time series data without aggregation
2. getSimpleTSData - Retrieves simple time series data with basic pagination
3. getTSData - Retrieves time series data with advanced aggregation options

Example: Using getRawTSData

The getRawTSData method retrieves raw time series data in a paginated format. This method internally uses getTSData with raw aggregation.

try {
  const response = await userInstance.getUserNodes();
  const node = response.nodes[0];
  const nodeConfig = node.nodeConfig || await node.getNodeConfig();
  
  // Find a device parameter with time series support
  const device = nodeConfig.devices[0];
  const timeSeriesParam = device.params.find(
    param => param.properties && (
      param.properties.includes("time_series") || 
      param.properties.includes("simple_ts")
    )
  );
  
  if (timeSeriesParam) {
    const request = {
      startTime: Date.now() - 7 * 24 * 60 * 60 * 1000, // 7 days ago
      endTime: Date.now(),
      resultCount: 100,
      descOrder: false,
      timezone: "America/Los_Angeles"
    };
    
    let tsResponse = await timeSeriesParam.getRawTSData(request);
    console.log("Time series data:", tsResponse.tsData);
    
    // Handle pagination
    while (tsResponse.hasNext) {
      tsResponse = await tsResponse.fetchNext();
      console.log("Next page of data:", tsResponse.tsData);
    }
  }
} catch (error) {
  console.error("Error fetching raw time series data:", error);
}

Example: Using getSimpleTSData

The getSimpleTSData method retrieves simple time series data with basic pagination. This is useful for straightforward time series queries.

try {
  const response = await userInstance.getUserNodes();
  const node = response.nodes[0];
  const nodeConfig = node.nodeConfig || await node.getNodeConfig();
  
  const device = nodeConfig.devices[0];
  const timeSeriesParam = device.params.find(
    param => param.properties && param.properties.includes("simple_ts")
  );
  
  if (timeSeriesParam) {
    const request = {
      startTime: Date.now() - 24 * 60 * 60 * 1000, // 24 hours ago
      endTime: Date.now(),
      resultCount: 50
    };
    
    let tsResponse = await timeSeriesParam.getSimpleTSData(request);
    
    // Process time series data points
    tsResponse.tsData.forEach((dataPoint) => {
      console.log(`Timestamp: ${new Date(dataPoint.timestamp)}, Value: ${dataPoint.value}`);
    });
    
    // Fetch more data if available
    while (tsResponse.hasNext) {
      tsResponse = await tsResponse.fetchNext();
      tsResponse.tsData.forEach((dataPoint) => {
        console.log(`Timestamp: ${new Date(dataPoint.timestamp)}, Value: ${dataPoint.value}`);
      });
    }
  }
} catch (error) {
  console.error("Error fetching simple time series data:", error);
}

Example: Using getTSData with Aggregation

The getTSData method provides advanced aggregation options for time series data analysis.

try {
  const response = await userInstance.getUserNodes();
  const node = response.nodes[0];
  const nodeConfig = node.nodeConfig || await node.getNodeConfig();
  
  const device = nodeConfig.devices[0];
  const timeSeriesParam = device.params.find(
    param => param.properties && param.properties.includes("time_series")
  );
  
  if (timeSeriesParam) {
    const request = {
      startTime: Date.now() - 30 * 24 * 60 * 60 * 1000, // 30 days ago
      endTime: Date.now(),
      aggregate: "avg", // Aggregation method: avg, sum, min, max, count
      aggregationInterval: "day", // Interval: hour, day, week, month
      numIntervals: 30,
      resultCount: 100,
      timezone: "America/Los_Angeles",
      descOrder: false
    };
    
    let tsResponse = await timeSeriesParam.getTSData(request);
    console.log("Aggregated time series data:", tsResponse.tsData);
    
    // Process aggregated data
    tsResponse.tsData.forEach((dataPoint) => {
      const date = new Date(dataPoint.timestamp);
      console.log(`Date: ${date.toLocaleDateString()}, Average Value: ${dataPoint.value}`);
    });
  }
} catch (error) {
  console.error("Error fetching aggregated time series data:", error);
}

Time Series Data Request Interfaces

ESPRawTSDataRequest

Interface for raw time series data request parameters.

Parameter	Type	Description
startTime	number	Start timestamp for the time series data query (Unix timestamp in milliseconds).
endTime	number	End timestamp for the time series data query (Unix timestamp in milliseconds).
resultCount?	number	Number of results to return per page.
descOrder?	boolean	Whether to return results in descending order (newest first).
differential?	boolean	Whether to return differential values.
resetOnNegative?	boolean	Whether to reset on negative values.
timezone?	string	Timezone for the query (e.g., "America/Los_Angeles").

ESPSimpleTSDataRequest

Interface for simple time series data request parameters.

Parameter	Type	Description
startTime*	number	Start timestamp for the time series data query (Unix timestamp in milliseconds).
endTime*	number	End timestamp for the time series data query (Unix timestamp in milliseconds).
resultCount?	number	Number of results to return per page.

ESPTSDataRequest

Interface for time series data request parameters with aggregation options. Extends ESPRawTSDataRequest.

Parameter	Type	Description
startTime?	number	Start timestamp for the time series data query (Unix timestamp in milliseconds).
endTime?	number	End timestamp for the time series data query (Unix timestamp in milliseconds).
resultCount?	number	Number of results to return per page.
aggregate?	ESPAggregationMethod	Aggregation method: "avg", "sum", "min", "max", "count".
aggregationInterval?	ESPAggregationInterval	Aggregation interval: "hour", "day", "week", "month".
numIntervals?	number	Number of intervals for aggregation.
descOrder?	boolean	Whether to return results in descending order.
differential?	boolean	Whether to return differential values.
resetOnNegative?	boolean	Whether to reset on negative values.
timezone?	string	Timezone for the query.
weekStart?	ESPWeekStart	Start day of the week for weekly aggregation.

Time Series Data Response

All time series data methods return an ESPSimpleTSDataResponse object:

Property	Type	Description
tsData	ESPTSData[]	Array of time series data points.
hasNext	boolean	Indicates whether more data is available.
fetchNext?	() => Promise<ESPSimpleTSDataResponse>	Function to fetch the next page of data.

Each ESPTSData object contains:

Property	Type	Description
timestamp	number	Unix timestamp in milliseconds.
value	string | number | boolean	The value at this timestamp.

备注

• Time series data methods are only available on device parameters (ESPRMDeviceParam) that have "time_series" or "simple_ts" in their properties array.
• All time series data methods support pagination through the hasNext and fetchNext() properties.
• Timestamps are in Unix milliseconds format.