Energykit

by dpearson26998d90fd121a26No license1.1K starsListed Oct 8, 2026Updated Oct 8, 2026Repository updated 2 months ago

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.

Instructions only

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.

Setup
Core Concepts
Querying Electricity Guidance
Working with Guidance Values
Energy Venues
Submitting Load Events
Electricity Insights
Common Mistakes
Review Checklist
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

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:

Electricity Guidance -- time-weighted forecasts telling apps when electricity is cleaner and, when rate data is available, less expensive
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

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)    }}

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 chargefunc bestChargingWindow(    in values: [ElectricityGuidance.Value]) -> ElectricityGuidance.Value? {    values.min(by: { $0.rating < $1.rating })}
// Find all "good" windows below a thresholdfunc goodWindows(    in values: [ElectricityGuidance.Value],    threshold: Double = 0.3) -> [ElectricityGuidance.Value] {    values.filter { $0.rating <= threshold }}

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 chargefunc bestChargingWindow(    in values: [ElectricityGuidance.Value]) -> ElectricityGuidance.Value? {    values.min(by: { $0.rating < $1.rating })}
// Find all "good" windows below a thresholdfunc goodWindows(    in values: [ElectricityGuidance.Value],    threshold: Double = 0.3) -> [ElectricityGuidance.Value] {    values.filter { $0.rating <= threshold }}

Displaying Guidance in SwiftUI

swift

import SwiftUIimport 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())    }}

import SwiftUIimport 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 represents a physical location registered for energy management.

swift

// List all venuesfunc listVenues() async throws -> [EnergyVenue] {    try await EnergyVenue.venues()}
// Get a specific venue by IDfunc getVenue(id: UUID) async throws -> EnergyVenue {    try await EnergyVenue.venue(for: id)}
// Get a venue matching a HomeKit homefunc getVenueForHome(homeID: UUID) async throws -> EnergyVenue {    try await EnergyVenue.venue(matchingHomeUniqueIdentifier: homeID)}

// List all venuesfunc listVenues() async throws -> [EnergyVenue] {    try await EnergyVenue.venues()}
// Get a specific venue by IDfunc getVenue(id: UUID) async throws -> EnergyVenue {    try await EnergyVenue.venue(for: id)}
// Get a venue matching a HomeKit homefunc getVenueForHome(homeID: UUID) async throws -> EnergyVenue {    try await EnergyVenue.venue(matchingHomeUniqueIdentifier: homeID)}

Venue Properties

swift

let venue = try await EnergyVenue.venue(for: venueID)print("Venue ID: \(venue.id)")print("Venue name: \(venue.name)")

let venue = try await EnergyVenue.venue(for: venueID)print("Venue ID: \(venue.id)")print("Venue name: \(venue.name)")

Submitting Load Events

Report device consumption data back to the system. This helps the system generate electricity insights. The same EnergyKit-capable device/app that requested electricity guidance must submit the corresponding load events, using the guidance token returned by EnergyKit. Do not invent a token.

EV Charger Load Events

swift

func submitEVBeginEvent(    at venue: EnergyVenue,    guidanceToken: UUID,    deviceID: String,    deviceName: String) async throws {    let session = ElectricVehicleLoadEvent.Session(        id: UUID(),        state: .begin,        guidanceState: ElectricVehicleLoadEvent.Session.GuidanceState(            wasFollowingGuidance: true,            guidanceToken: guidanceToken        )    )
    let measurement = ElectricVehicleLoadEvent.ElectricalMeasurement(        stateOfCharge: 45,        direction: .imported,        power: Measurement(value: 0, unit: .kilowatts),        energy: Measurement(value: 0, unit: .kilowattHours)    )
    let event: ElectricVehicleLoadEvent    if #available(iOS 27.0, iPadOS 27.0, *) {        let device = ElectricalLoadDevice(            id: deviceID,            name: deviceName,            type: .electricVehicle        )        event = ElectricVehicleLoadEvent(            timestamp: Date(), measurement: measurement,            session: session, device: device        )    } else {        // iOS/iPadOS 26 compatibility; deprecated in the iOS 27 SDK.        event = ElectricVehicleLoadEvent(            timestamp: Date(), measurement: measurement,            session: session, deviceID: deviceID        )    }
    try await venue.submitEvents([event])}

func submitEVBeginEvent(    at venue: EnergyVenue,    guidanceToken: UUID,    deviceID: String,    deviceName: String) async throws {    let session = ElectricVehicleLoadEvent.Session(        id: UUID(),        state: .begin,        guidanceState: ElectricVehicleLoadEvent.Session.GuidanceState(            wasFollowingGuidance: true,            guidanceToken: guidanceToken        )    )
    let measurement = ElectricVehicleLoadEvent.ElectricalMeasurement(        stateOfCharge: 45,        direction: .imported,        power: Measurement(value: 0, unit: .kilowatts),        energy: Measurement(value: 0, unit: .kilowattHours)    )
    let event: ElectricVehicleLoadEvent    if #available(iOS 27.0, iPadOS 27.0, *) {        let device = ElectricalLoadDevice(            id: deviceID,            name: deviceName,            type: .electricVehicle        )        event = ElectricVehicleLoadEvent(            timestamp: Date(), measurement: measurement,            session: session, device: device        )    } else {        // iOS/iPadOS 26 compatibility; deprecated in the iOS 27 SDK.        event = ElectricVehicleLoadEvent(            timestamp: Date(), measurement: measurement,            session: session, deviceID: deviceID        )    }
    try await venue.submitEvents([event])}

HVAC Load Events

swift

func submitHVACEvent(    at venue: EnergyVenue,    guidanceToken: UUID,    stage: Int,    deviceID: String,    deviceName: String) async throws {    let session = ElectricHVACLoadEvent.Session(        id: UUID(),        state: .active,        guidanceState: ElectricHVACLoadEvent.Session.GuidanceState(            wasFollowingGuidance: true,            guidanceToken: guidanceToken        )    )
    let measurement = ElectricHVACLoadEvent.ElectricalMeasurement(stage: stage)
    let event: ElectricHVACLoadEvent    if #available(iOS 27.0, iPadOS 27.0, *) {        let device = ElectricalLoadDevice(            id: deviceID,            name: deviceName,            type: .hvac        )        event = ElectricHVACLoadEvent(            timestamp: Date(), measurement: measurement,            session: session, device: device        )    } else {        // iOS/iPadOS 26 compatibility; deprecated in the iOS 27 SDK.        event = ElectricHVACLoadEvent(            timestamp: Date(), measurement: measurement,            session: session, deviceID: deviceID        )    }
    try await venue.submitEvents([event])}

func submitHVACEvent(    at venue: EnergyVenue,    guidanceToken: UUID,    stage: Int,    deviceID: String,    deviceName: String) async throws {    let session = ElectricHVACLoadEvent.Session(        id: UUID(),        state: .active,        guidanceState: ElectricHVACLoadEvent.Session.GuidanceState(            wasFollowingGuidance: true,            guidanceToken: guidanceToken        )    )
    let measurement = ElectricHVACLoadEvent.ElectricalMeasurement(stage: stage)
    let event: ElectricHVACLoadEvent    if #available(iOS 27.0, iPadOS 27.0, *) {        let device = ElectricalLoadDevice(            id: deviceID,            name: deviceName,            type: .hvac        )        event = ElectricHVACLoadEvent(            timestamp: Date(), measurement: measurement,            session: session, device: device        )    } else {        // iOS/iPadOS 26 compatibility; deprecated in the iOS 27 SDK.        event = ElectricHVACLoadEvent(            timestamp: Date(), measurement: measurement,            session: session, deviceID: deviceID        )    }
    try await venue.submitEvents([event])}

Session States

Preserve .begin → .active → .end and submit events promptly rather than holding long batches. For EV charging, submit .begin with zero power and energy, .active about every 15 minutes plus significant changes, and .end with zero power and cumulative energy. Retain unacknowledged events and retry EnergyKitError.rateLimitExceeded with bounded backoff. Load the EV session manager [blocked] or HVAC session manager [blocked] for device-specific lifecycle handling.

Only promise Home app device names, energy context, activity logs, charts, and trend notifications on iOS/iPadOS 27+ when both the base EnergyKit and EnergyKit LoadEvents capabilities are present.

Electricity Insights

Query historical energy and runtime data for devices using ElectricityInsightService. An empty ElectricityInsightQuery.Options option set returns totals only; it does not populate cleanliness or tariff breakdowns. Request .cleanliness and/or .tariff only when the UI needs those breakdowns. Do not substitute MetricKit app power metrics for EnergyKit insights; EnergyKit insights depend on EnergyKit load events submitted for the managed device.

Choose insight granularity from the requested range. For a seven-day view, query .hourly; use .daily only when the query covers at least a calendar month.

swift

func queryEnergyInsights(deviceID: String, venueID: UUID) async throws {    let sevenDaysAgo = Calendar.current.date(        byAdding: .day,        value: -7,        to: Date()    )!
    let query = ElectricityInsightQuery(        options: [.cleanliness, .tariff],        range: DateInterval(            start: sevenDaysAgo,            end: Date()        ),        granularity: .hourly,        flowDirection: .imported    )
    let service = ElectricityInsightService.shared    let stream = try await service.energyInsights(        forDeviceID: deviceID, using: query, atVenue: venueID    )
    for await record in stream {        if let total = record.totalEnergy { print("Total: \(total)") }
        if #available(iOS 26.1, iPadOS 26.1, *),           let cleaner = record.dataByGridCleanliness?.cleaner {            print("Cleaner: \(cleaner)")        }    }}

func queryEnergyInsights(deviceID: String, venueID: UUID) async throws {    let sevenDaysAgo = Calendar.current.date(        byAdding: .day,        value: -7,        to: Date()    )!
    let query = ElectricityInsightQuery(        options: [.cleanliness, .tariff],        range: DateInterval(            start: sevenDaysAgo,            end: Date()        ),        granularity: .hourly,        flowDirection: .imported    )
    let service = ElectricityInsightService.shared    let stream = try await service.energyInsights(        forDeviceID: deviceID, using: query, atVenue: venueID    )
    for await record in stream {        if let total = record.totalEnergy { print("Total: \(total)") }
        if #available(iOS 26.1, iPadOS 26.1, *),           let cleaner = record.dataByGridCleanliness?.cleaner {            print("Cleaner: \(cleaner)")        }    }}

Use runtimeInsights(forDeviceID:using:atVenue:) for runtime data instead of energy. Granularity options: .hourly, .daily, .weekly, .monthly, .yearly. Choose a range that matches Apple's minimum aggregation windows: hourly for at least a calendar week, daily for at least a calendar month, weekly for at least six months, and monthly or yearly for at least a calendar year. See references/energykit-patterns.md [blocked] for full insight examples.

Common Mistakes

Mistake	Fix
Querying before capability setup	Verify the EnergyKit entitlement and handle `.permissionDenied`.
Assuming every region has guidance	Apple currently documents guidance only in the contiguous US; handle unsupported-region and unavailable venue/guidance states.
Fabricating or discarding the guidance token	Persist the real token on the requesting device and submit that token with its load events.
Sending isolated or delayed load samples	Preserve `.begin → .active → .end`, submit promptly, and retain events until submission succeeds.
Using `deviceID:` as the current default	Use iOS/iPadOS 27+ `ElectricalLoadDevice` and `device:`; keep `deviceID:` only for the 26.x runtime branch.
Using a hardcoded venue ID	Discover venues with `EnergyVenue.venues()` and select the intended venue.

Review Checklist

Base EnergyKit capability is present; iOS/iPadOS 27+ Home integration also has EnergyKit LoadEvents
Region, permission, venue discovery, unavailable guidance, and service errors are handled
Real guidance tokens stay with the requesting device/app and its submitted load events
iOS/iPadOS 27+ uses ElectricalLoadDevice/device:; deviceID: is isolated to 26.x compatibility
.begin → .active → .end events follow device cadence, submit promptly, survive failure, and retry rate limits with bounded backoff
Ratings/actions are interpreted correctly; insight options, availability, granularity, and minimum ranges match the UI
MetricKit telemetry is not substituted for EnergyKit load events or insights

References

Extended workflows for app architecture, EV/HVAC session cadence, dashboard presentation, insights, errors, and venue discovery: references/energykit-patterns.md [blocked]
EnergyKit framework
ElectricityGuidance
ElectricityGuidance.Service
ElectricityGuidance.Query
ElectricityGuidance.Value
EnergyVenue
ElectricalLoadDevice
ElectricVehicleLoadEvent
ElectricHVACLoadEvent
ElectricityInsightService
ElectricityInsightRecord
ElectricityInsightQuery
EnergyKitError
EnergyKit entitlement
EnergyKit LoadEvents entitlement
Providing charging history for electric vehicles
Optimizing home electricity usage

Source and attribution

Source:dpearson2699/swift-ios-skillsinskills/energykitat commit8d90fd1

License: No license

Content belongs to its original authors. SourceWeft indexes it from a public repository.

Report or request removal

More from dpearson2699/swift-ios-skills

Widgetkit

dpearson2699

Guides implementing, reviewing, and improving WidgetKit widgets and controls for iOS, iPadOS, watchOS, and CarPlay.

Software Development1.1Kupdated 2 months ago

Weatherkit

dpearson2699

Guides iOS developers in fetching WeatherKit forecasts, alerts, and attribution using WeatherService.

Software Development1.1Kupdated 2 months ago

Vision Framework

dpearson2699

Implement computer vision features including text recognition (OCR), face detection, barcode scanning, image segmentation, object tracking, and document scanning in iOS apps. Covers both the modern Swift-native Vision API (iOS 18+) and legacy VNRequest patterns, VisionKit DataScannerViewController for live camera scanning, and CoreMLRequest/VNCoreMLRequest for custom model inference. Use when adding OCR, barcode scanning, face detection, or custom Core ML model inference with Vision.

Awaiting classification1.1Kupdated 2 months ago

Tipkit

dpearson2699

Implement and review Apple TipKit feature-discovery UI for iOS 17+ apps. Use when adding or auditing in-app tips, contextual help, coach marks, Tip, TipView, popoverTip, rules, events, actions, display frequency, testing overrides, reusable tip identifiers, or iOS 18+ TipGroup and CloudKit tip sync; avoid for generic SwiftUI navigation or layout outside tip presentation.

Awaiting classification1.1Kupdated 2 months ago

Tabletopkit

dpearson2699

Guides building multiplayer spatial board games on visionOS with Apple's TabletopKit and RealityKit.

Software Development1.1Kupdated 2 months ago

Swiftui Webkit

dpearson2699

Guides embedding and controlling web content in SwiftUI apps with WebKit for SwiftUI on iOS 26 and later.

Software Development1.1Kupdated 2 months ago

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)

State	When to Use
`.begin`	Device starts consuming electricity
`.active`	Device is actively consuming (periodic updates)
`.end`	Device stops consuming electricity

Energykit

EnergyKit

Contents

Setup

Entitlements and Version Split

Import

Core Concepts

Key Types

Suggested Actions

Querying Electricity Guidance

Working with Guidance Values

Displaying Guidance in SwiftUI

Energy Venues

Venue Properties

Submitting Load Events

EV Charger Load Events

HVAC Load Events

Session States

Electricity Insights

Common Mistakes

Review Checklist

References

Source and attribution

More from dpearson2699/swift-ios-skills

Widgetkit

Weatherkit

Vision Framework

Tipkit

Tabletopkit

Swiftui Webkit