energykit

# EnergyKit

Provide grid electricity forecasts to help users choose when to use electricity.
EnergyKit identifies times when grid electricity is relatively cleaner and,
when cost information is available, less expensive. Apps use that guidance to
shift or reduce managed device load. Targets Swift 6.3 / iOS 26+.

> **Beta-sensitive.** EnergyKit is new in iOS 26 and may change before GM.
> Re-check current Apple documentation before relying on specific API details.

## Contents

- [Setup](#setup)
- [Core Concepts](#core-concepts)
- [Querying Electricity Guidance](#querying-electricity-guidance)
- [Working with Guidance Values](#working-with-guidance-values)
- [Energy Venues](#energy-venues)
- [Submitting Load Events](#submitting-load-events)
- [Electricity Insights](#electricity-insights)
- [Common Mistakes](#common-mistakes)
- [Review Checklist](#review-checklist)
- [References](#references)

## Setup

### Entitlement

EnergyKit requires the `com.apple.developer.energykit` entitlement. Enable the
EnergyKit capability in Xcode so the entitlement is added to the app target.
Treat this as a top-level setup prerequisite before writing guidance queries,
venue lookup, load-event submission, or insight code. Missing permission can
surface as `EnergyKitError.permissionDenied`.

### Import

```swift
import EnergyKit
```

**Platform availability:** Core EnergyKit APIs are iOS 26.0+ and iPadOS 26.0+.
Some insight breakdown APIs, including grid cleanliness categories, are iOS
26.1+ / iPadOS 26.1+ and need availability guards.

## Core Concepts

EnergyKit provides two main capabilities:

1. **Electricity Guidance** -- time-weighted forecasts telling apps when
   electricity is cleaner and, when rate data is available, less expensive
2. **Load Events** -- telemetry from managed devices (EV chargers, HVAC)
   submitted by the same device/app that requested guidance so EnergyKit can
   generate insights

### Key Types

| Type | Role |
|---|---|
| `ElectricityGuidance` | Forecast data with weighted time intervals |
| `ElectricityGuidance.Service` | Interface for obtaining guidance data |
| `ElectricityGuidance.Query` | Query specifying shift or reduce action |
| `ElectricityGuidance.Value` | A time interval with a rating (0.0-1.0) |
| `EnergyVenue` | A physical location (home) registered for energy management |
| `ElectricVehicleLoadEvent` | Load event for EV charger telemetry |
| `ElectricHVACLoadEvent` | Load event for HVAC system telemetry |
| `ElectricityInsightService` | Service for querying energy/runtime insights |
| `ElectricityInsightRecord` | Historical energy or runtime data, optionally broken down by tariff or 26.1+ grid cleanliness |
| `ElectricityInsightQuery` | Query for historical insight data |

### Suggested Actions

| Action | Use Case |
|---|---|
| `.shift` | Devices that can move consumption to a different time (EV charging) |
| `.reduce` | Devices that can lower consumption without stopping (HVAC setback) |

## Querying Electricity Guidance

Use `ElectricityGuidance.Service` to get a forecast stream for a venue.

```swift
import EnergyKit

func observeGuidance(venueID: UUID) async throws {
    let query = ElectricityGuidance.Query(suggestedAction: .shift)
    let service = ElectricityGuidance.sharedService

    let guidanceStream = service.guidance(using: query, at: venueID)

    for try await guidance in guidanceStream {
        print("Guidance token: \(guidance.guidanceToken)")
        print("Interval: \(guidance.interval)")
        print("Venue: \(guidance.energyVenueID)")

        // Check if rate plan information is available
        if guidance.options.contains(.guidanceIncorporatesRatePlan) {
            print("Rate plan data incorporated")
        }
        if guidance.options.contains(.locationHasRatePlan) {
            print("Location has a rate plan")
        }

        processGuidanceValues(guidance.values)
    }
}
```

## Working with Guidance Values

Each `ElectricityGuidance.Value` contains a time interval and a rating
from 0.0 to 1.0. Lower ratings indicate better times to use electricity.

```swift
func processGuidanceValues(_ values: [ElectricityGuidance.Value]) {
    for value in values {
        let interval = value.interval
        let rating = value.rating  // 0.0 (best) to 1.0 (worst)

        print("From \(interval.start) to \(interval.end): rating \(rating)")
    }
}

// Find the best time to charge
func bestChargingWindow(
    in values: [ElectricityGuidance.Value]
) -> ElectricityGuidance.Value? {
    values.min(by: { $0.rating < $1.rating })
}

// Find all "good" windows below a threshold
func goodWindows(
    in values: [ElectricityGuidance.Value],
    threshold: Double = 0.3
) -> [ElectricityGuidance.Value] {
    values.filter { $0.rating <= threshold }
}
```

### Displaying Guidance in SwiftUI

```swift
import SwiftUI
import EnergyKit

struct GuidanceTimelineView: View {
    let values: [ElectricityGuidance.Value]

    var body: some View {
        List(values, id: \.interval.start) { value in
            HStack {
                VStack(alignment: .leading) {
                    Text(value.interval.start, style: .time)
                    Text(value.interval.end, style: .time)
                        .foregroundStyle(.secondary)
                }
                Spacer()
                RatingIndicator(rating: value.rating)
            }
        }
    }
}

struct RatingIndicator: View {
    let rating: Double

    var color: Color {
        if rating <= 0.3 { return .green }
        if rating <= 0.6 { return .yellow }
        return .red
    }

    var label: String {
        if rating <= 0.3 { return "Good" }
        if rating <= 0.6 { return "Fair" }
        return "Avoid"
    }

    var body: some View {
        Text(label)
            .padding(.horizontal)
            .padding(.vertical)
            .background(color.opacity(0.2))
            .foregroundStyle(color)
            .clipShape(Capsule())
    }
}
```

## Energy Venues

An `EnergyVenue`