/energykit

name: energykit
description: "Query grid electricity forecasts and submit load events using EnergyKit to help users optimize home electricity usage. Use when building smart home apps, EV charger controls, HVAC scheduling, or energy management dashboards that guide users to use power during cleaner or cheaper grid periods."

EnergyKit

Use grid cleanliness and cost guidance to shift or reduce managed-device load. For managed-device insights, submit the device's real load events promptly.

> **Beta-sensitive.** Core EnergyKit ships in iOS/iPadOS 26. The iOS/iPadOS 27 > `ElectricalLoadDevice` and Home-facing LoadEvents experience are beta; re-check > current Apple documentation before relying on those APIs.

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

Entitlements and Version Split

| Runtime | Load-event device API | Capabilities | |---|---|---| | iOS/iPadOS 26.x | `deviceID:` compatibility initializer | EnergyKit | | iOS/iPadOS 27+ beta | `ElectricalLoadDevice` with the `device:` initializer | EnergyKit; add EnergyKit LoadEvents for Home app integration |

All EnergyKit use requires `com.apple.developer.energykit`; enable the EnergyKit capability on the app target. On iOS/iPadOS 27+, add the EnergyKit LoadEvents capability (`com.apple.developer.energykit.loadevents-experience`) only when the app needs device names, energy context, activity logs, historical charts, or trend notifications in the Home app. That Home experience requires both capabilities. Missing permission can surface as `EnergyKitError.permissionDenied`.

Import

import EnergyKit

**Platform availability:** Core EnergyKit APIs are iOS/iPadOS 26.0+. Some insight breakdown APIs, including grid cleanliness categories, are 26.1+ and need availability guards. Apple currently documents electricity guidance only for the contiguous United States; handle `EnergyKitError.unsupportedRegion`.

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 | | `ElectricalLoadDevice` | iOS/iPadOS 27+ beta device identity for load events | | `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.

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.

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

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