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 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. 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. Displaying Guidance in SwiftUI Energy Venues An EnergyVenue represents a physical location registered for energy management. Venue Properties 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 HVAC Load Events Session States State When to Use .begin Device starts consuming electricity .active Device is actively consuming (periodic updates) .end Device stops consuming electricity 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](references/energykit patterns.md ev charging session manager) or [HVAC session manager](references/energykit patterns.md hvac control manager) 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. 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](references/energykit patterns.md) 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](references/energykit patterns.md) [EnergyKit framework](https://sosumi.ai/documentation/energykit) [ElectricityGuidance](https://sosumi.ai/documentation/energykit/electricityguidance) [ElectricityGuidance.Service](https://sosumi.ai/documentation/energykit/electricityguidance/service) [ElectricityGuidance.Query](https://sosumi.ai/documentation/energykit/electricityguidance/query) [ElectricityGuidance.Value](https://sosumi.ai/documentation/energykit/electricityguidance/value) [EnergyVenue](https://sosumi.ai/documentation/energykit/energyvenue) [ElectricalLoadDevice](https://sosumi.ai/documentation/energykit/electricalloaddevice) [ElectricVehicleLoadEvent](https://sosumi.ai/documentation/energykit/electricvehicleloadevent) [ElectricHVACLoadEvent](https://sosumi.ai/documentation/energykit/electrichvacloadevent) [ElectricityInsightService](https://sosumi.ai/documentation/energykit/electricityinsightservice) [ElectricityInsightRecord](https://sosumi.ai/documentation/energykit/electricityinsightrecord) [ElectricityInsightQuery](https://sosumi.ai/documentation/energykit/electricityinsightquery) [EnergyKitError](https://sosumi.ai/documentation/energykit/energykiterror) [EnergyKit entitlement](https://sosumi.ai/documentation/bundleresources/entitlements/com.apple.developer.energykit) [EnergyKit LoadEvents entitlement](https://sosumi.ai/documentation/bundleresources/entitlements/com.apple.developer.energykit.loadevents experience) [Providing charging history for electric vehicles](https://sosumi.ai/documentation/energykit/providing informative charging history for electric vehicles) [Optimizing home electricity usage](https://sosumi.ai/documentation/energykit/optimizing home electricity usage)