Metrics

Texture provides several metrics that allow you to analyze and understand energy data from your devices. This guide explains the available metrics, their data structures, and how to query them using our API.

Overview

Metrics are time-series data that represent different aspects of energy usage, production, storage, and environmental impact. Each metric is organized into time buckets, allowing you to analyze data over specific time periods.

All metric endpoints follow a similar request/response pattern:

Request: Specify device IDs, time range, and aggregation interval
Response: Receive time-bucketed data for the requested metric

Available Metrics

Texture currently offers the following metrics:

Metric	Description	Applicable Devices
Energy Consumption	Energy consumed or used to charge a battery	Battery devices
Energy Production	Energy produced or discharged from a battery	Battery devices
Energy Storage	Average energy stored in a battery	Battery devices
Energy Emissions	CO2 emissions associated with energy usage	Battery and Inverter devices
Energy Generation	Energy generated by solar inverters	Inverter devices

Let's explore each metric in detail.

Energy Consumption

Energy Consumption measures the amount of energy consumed or used to charge a battery in watt-hours (Wh). This metric only applies to battery devices.

Data Characteristics

Unit: Watt-hours (Wh)
Time Domain: Data may be sparse, as values are only present when the battery is charging
Aggregation: Each time bucket contains the total energy consumed during that period

API Reference

GET /v1/metrics/consumption

For detailed request parameters and response format, see the Energy Consumption API documentation.

Example Usage

const response = await fetch('https://api.texturehq.com/v1/metrics/consumption?filterDeviceId[]=device123&filterRangeAfter=2025-04-10T00:00:00Z&filterRangeBefore=2025-04-10T23:59:59Z&windowSize=HOUR', {
  headers: {
    'texture-api-key': 'YOUR_API_KEY'
  }
});

const data = await response.json();

Energy Production

Energy Production measures the amount of energy produced or discharged from a battery in watt-hours (Wh). This metric only applies to battery devices.

Data Characteristics

Unit: Watt-hours (Wh)
Time Domain: Data may be sparse, as values are only present when the battery is discharging
Aggregation: Each time bucket contains the total energy produced during that period

API Reference

GET /v1/metrics/production

For detailed request parameters and response format, see the Energy Production API documentation.

Example Usage

const response = await fetch('https://api.texturehq.com/v1/metrics/production?filterDeviceId[]=device123&filterRangeAfter=2025-04-10T00:00:00Z&filterRangeBefore=2025-04-10T23:59:59Z&windowSize=HOUR', {
  headers: {
    'texture-api-key': 'YOUR_API_KEY'
  }
});

const data = await response.json();

Energy Storage

Energy Storage measures the average amount of energy stored in a battery in watt-hours (Wh) during a specific time period. This metric only applies to battery devices.

Data Characteristics

Unit: Watt-hours (Wh)
Aggregation: Each time bucket contains the average energy stored during that period
Continuity: This metric typically provides continuous data as long as the battery is operational

API Reference

GET /v1/metrics/storage

For detailed request parameters and response format, see the Energy Storage API documentation.

Example Usage

const response = await fetch('https://api.texturehq.com/v1/metrics/storage?filterDeviceId[]=device123&filterRangeAfter=2025-04-10T00:00:00Z&filterRangeBefore=2025-04-10T23:59:59Z&windowSize=HOUR', {
  headers: {
    'texture-api-key': 'YOUR_API_KEY'
  }
});

const data = await response.json();

Energy Emissions

Energy Emissions measures the total pounds of CO2 emitted during a specific time period. This metric applies specifically to battery and inverter devices.

Data Characteristics

Unit: Pounds of CO2
Aggregation: Each time bucket contains the total emissions during that period
Applicability: This metric applies to both battery and inverter devices

API Reference

GET /v1/metrics/emissions

For detailed request parameters and response format, see the Energy Emissions API documentation.

Example Usage

const response = await fetch('https://api.texturehq.com/v1/metrics/emissions?filterDeviceId[]=device123&filterRangeAfter=2025-04-10T00:00:00Z&filterRangeBefore=2025-04-10T23:59:59Z&windowSize=HOUR', {
  headers: {
    'texture-api-key': 'YOUR_API_KEY'
  }
});

const data = await response.json();

Energy Generation

Energy Generation measures the amount of energy generated or produced by solar inverters in watt-hours (Wh). This metric only applies to inverter devices.

Data Characteristics

Unit: Watt-hours (Wh)
Time Domain: Data may be sparse, as values are only present during daylight hours when solar generation is active
Aggregation: Each time bucket contains the total energy generated during that period

API Reference

GET /v1/metrics/generation

For detailed request parameters and response format, see the Energy Generation API documentation.

Example Usage

const response = await fetch('https://api.texturehq.com/v1/metrics/generation?filterDeviceId[]=device123&filterRangeAfter=2025-04-10T00:00:00Z&filterRangeBefore=2025-04-10T23:59:59Z&windowSize=HOUR', {
  headers: {
    'texture-api-key': 'YOUR_API_KEY'
  }
});

const data = await response.json();

Common Request Parameters

All metric endpoints accept the following common parameters:

Parameter	Type	Description	Required
`filterDeviceId`	array[string]	Device IDs to fetch metrics for	Yes*
`filterRangeAfter`	string or null	Time range start point which to fetch metrics	No
`filterRangeBefore`	string or null	Time range end which to fetch metrics. If not set, defaults to now	No
`filterRangeRelative`	string	The time range relative to the current time. Defaults to '1d' if range, after, and before are all not set	No
`filterSiteId`	array[string]	Site IDs to fetch metrics for if grouped by site	Yes*
`groupBy`	string	Facet to group the metrics by (e.g. site). Allowed value: SITE	No
`windowSize`	string	Size of the window to fetch metrics for. Allowed values: FIFTEEN_MINUTES, HOUR, DAY, WEEK, MONTH, YEAR. Default is 15 minutes.	No

* Either filterDeviceId or filterSiteId must be provided, and either filterRangeAfter or filterRangeRelative must be provided.

Response Format

All metric endpoints return data in a consistent format:

{
  "data": [
    {
      "ts": "2025-04-10T00:00:00.000Z",
      "v": 1234.56,
      "deviceId": "device123",
      "siteId": null,
      "customerId": null
    },
    // Additional time buckets...
  ],
  "meta": {
    "label": "energyConsumedWhr",
    "series": [
      "device123"
    ],
    "sparse": false,
    "unit": "WATT_HOURS",
    "displayUnit": "whr",
    "domainMeta": {
      "label": "time",
      "sparse": false,
      "rate": {
        "unit": "HOUR",
        "displayUnit": "h",
        "scaleFactor": 1
      }
    }
  }
}

Time Window Options

The windowSize parameter determines the granularity of the time buckets in the response. The available options are:

Value	Description
`FIFTEEN_MINUTES`	15-minute intervals
`HOUR`	Hourly intervals
`DAY`	Daily intervals
`WEEK`	Weekly intervals
`MONTH`	Monthly intervals
`YEAR`	Yearly intervals

Relative Time Ranges

You can use the filterRangeRelative parameter to specify a time range relative to the current time. For example:

1h: Last 1 hour
12h: Last 12 hours
1d: Last 1 day (default if no time range is specified)
7d: Last 7 days
30d: Last 30 days
90d: Last 90 days
1y: Last 1 year

Data Aggregation and Grouping

When requesting metrics with different window sizes, the data is aggregated as follows:

Sum Aggregation: Consumption, Production, Emissions, Generation
Average Aggregation: Storage

For example, when requesting hourly data for a day, you'll receive 24 data points, each containing the appropriate aggregation for that hour.

Grouping by Site

You can group metrics by site using the groupBy=SITE parameter along with filterSiteId to specify which sites you want data for. This is useful when you want to analyze metrics across multiple devices belonging to the same site.

Best Practices

Use the appropriate window size: For high-resolution analysis, use smaller window sizes (e.g., FIFTEEN_MINUTES or HOUR). For trend analysis, use larger window sizes (e.g., DAY, WEEK, or MONTH).
Choose between absolute and relative time ranges: Use filterRangeAfter and filterRangeBefore for precise time periods. Use filterRangeRelative for rolling time windows relative to now.
Optimize for sparse data: Some metrics like Consumption and Production may have sparse data in time periods when the battery is not active. Your application should handle these gaps appropriately.
Group by site when appropriate: When analyzing trends across multiple devices at the same site, use the groupBy=SITE parameter instead of making multiple device requests.
Cache responses when possible: To improve application performance, consider caching responses for frequently accessed time ranges that don't change often (like historical data).

Overview​

Available Metrics​

Energy Consumption​

Data Characteristics​

API Reference​

Example Usage​

Energy Production​

Data Characteristics​

API Reference​

Example Usage​

Energy Storage​

Data Characteristics​

API Reference​

Example Usage​

Energy Emissions​

Data Characteristics​

API Reference​

Example Usage​

Energy Generation​

Data Characteristics​

API Reference​

Example Usage​

Common Request Parameters​

Response Format​

Time Window Options​

Relative Time Ranges​

Data Aggregation and Grouping​

Grouping by Site​

Best Practices​

Overview

Available Metrics

Energy Consumption

Data Characteristics

API Reference

Example Usage

Energy Production

Data Characteristics

API Reference

Example Usage

Energy Storage

Data Characteristics

API Reference

Example Usage

Energy Emissions

Data Characteristics

API Reference

Example Usage

Energy Generation

Data Characteristics

API Reference

Example Usage

Common Request Parameters

Response Format

Time Window Options

Relative Time Ranges

Data Aggregation and Grouping

Grouping by Site

Best Practices