Releasing Nectar v2.2

v2.2 of the Nectar Utility Data API has been released! This release will allow all customers to access better time of use and demand data.

What's New in v2.2

Time-of-Use Breakdown

Usage data entries now include a timeOfUseBreakdown array with time of use data:

{
  "usage": 150.75,
  "usageUnits": "kWh",
  "timeOfUseBreakdown": [
    {
      "timeOfUse": "PEAK",
      "usage": 50.25,
      "usageUnits": "kWh",
      "description": "On-Peak Usage",
      "startDate": null,
      "endDate": null
    },
    {
      "timeOfUse": "OFF_PEAK",
      "usage": 100.5,
      "usageUnits": "kWh",
      "description": "Off-Peak Usage",
      "startDate": null,
      "endDate": null
    }
  ]
}

These fields replace the old timeOfUse field and appear across all v2.2 usage data and document endpoints. This declutters usage data for electricity bills and improves consistency.

How we extract TOU data: Each usage entry represents a single physical meter-period with the total aggregate usage. TOU components (peak, off-peak, shoulder, etc.) are captured as a breakdown of that total rather than as separate entries.

Dedicated Demand Meter Data

v2.2 introduces a dedicated demandMeters block on document responses with detailed demand data:

{
  "usageData": [ ... ],
  "demandMeters": [
    {
      "startDate": "2025-01-15",
      "endDate": "2025-01-31",
      "isEstimated": false,
      "demandUsage": 45.0,
      "demandUsageUnits": "kW",
      "description": "On Peak Demand",
      "demandType": "PEAK",
      "usageDataIds": ["uuid-1"]
    }
  ]
}

Each demand meter entry includes:

• demandUsage / demandUsageUnits: The demand reading and its unit (kW, MW, kVA, or kVAR).
• demandType: A optional category label such as UCAP, TRANSMISSION, or CONTRACT.
• description: An optional caption as it appears on the bill (e.g., "Winter On Peak Demand").
• usageDataIds: Links each demand reading to related consumption entries in the usageData array.

How we extract demand data: We capture demand data from meter tables, descriptions, and summary sections on the bill. Demand values that appear only within charge line items are not extracted as demand meters. Demand data can be linked back to related consumption entries via usageDataIds.

Note on v2 and v2.1

TOU Expansion on Document Detail Endpoints

To ease the transition while customers migrate to v2.2, the get document detail endpoints in v2 and v2.1 have been updated with TOU expansion. When a usage entry has a timeOfUseBreakdown whose components sum to the total usage, the response will expand each TOU component into its own usage data entry.

Important: These expanded entries are virtual — they do not exist as standalone records in the database. Other endpoints (e.g., list usage data, get usage data by ID) will not return them, and you cannot perform individual operations on them. They are only present in document detail responses.

We recommend adopting v2.2 for a consistent experience — TOU data is always returned via the timeOfUseBreakdown array with no virtual entries, and all endpoints behave uniformly.

Migration Notes

• v2 and v2.1: Fully backward compatible. Document detail endpoints may return additional expanded TOU entries in the usageData array. These are virtual and not addressable by ID on other endpoints.
• v2.2 is almost equivalent to v2. If you do not use time-of-use or demand data, adopting v2.2 should not require any major changes.
• timeOfUseBreakdown returns an empty array [] when no time-of-use data is available on a bill.
• demandMeters returns an empty array [] when no demand data is present.