EnergyKit

Query electricity cleanliness and cost forecasts and report device load telemetry using EnergyKit to help users shift power consumption to cleaner or cheaper grid periods. Targets Swift 6.3 / iOS 26+.

Beta-sensitive: Core EnergyKit APIs require iOS/iPadOS 26.0+. iOS/iPadOS 27+ APIs (ElectricalLoadDevice, Home app LoadEvents integration) are beta-sensitive.

Contents

• Capabilities and Entitlements
• Core Architecture
• Action and Rating Semantics
• Route by Task
• Common Mistakes
• Review Checklist
• References

Capabilities and Entitlements

All EnergyKit use requires the com.apple.developer.energykit entitlement. Enable the EnergyKit capability on your app target.

Handle EnergyKitError.permissionDenied when authorization is missing and EnergyKitError.unsupportedRegion outside supported grid territories (contiguous US).

Core Architecture

1. Electricity Guidance: Time-weighted forecast stream telling apps when electricity is cleaner and less expensive.
   • Use .shift for schedulable workloads (EV charging, battery storage).
   • Use .reduce for curtailment workloads (HVAC thermostat setbacks).
2. Load Events: Telemetry submitted by managed devices confirming actual consumption timing. Submissions must match the venue where guidance was received.
3. Energy Venues: Physical locations (EnergyVenue) registered in the user's Apple Home environment.

Action and Rating Semantics

• Guidance ratings range from 0.0 (dirtiest/costliest) to 1.0 (cleanest/cheapest).
• The guidance stream emits continuous intervals. Always observe updates because grid forecasts change dynamically with weather and demand spikes.
• Submit load events promptly after consumption completes so historical insights reflect accurate savings.

Route by Task

• For guidance query streams, SwiftUI chart bindings, and venue discovery, read Observing Electricity Guidance.
• For submitting EV charger (ElectricVehicleLoadEvent) and HVAC (ElectricHVACLoadEvent) telemetry, read Submitting Load Events.
• For historical consumption records, cost breakdowns, and tariff analysis with ElectricityInsightService, read Electricity Insights.
• For Home app integration on iOS 27+ and device metadata, read Home App Integration.

Common Mistakes

• Missing com.apple.developer.energykit entitlement, causing silent failures or .permissionDenied.
• Assuming global coverage without handling EnergyKitError.unsupportedRegion.
• Submitting load events with mismatched device or venue identifiers.
• Failing to observe guidance updates dynamically, leaving stale charging schedules in place.
• Using iOS 27 ElectricalLoadDevice without availability checks on iOS 26 deployment targets.

Review Checklist

• com.apple.developer.energykit entitlement enabled on app target
• Regional availability handled gracefully (EnergyKitError.unsupportedRegion)
• Query action matches device behavior (.shift for EV/batteries, .reduce for HVAC)
• Load events submitted promptly with accurate start/end timestamps and watt-hours
• Guidance values normalized and mapped to user-facing cleaner/cheaper indicators
• iOS 27+ LoadEvents capability gated behind appropriate availability checks

References

• EnergyKit implementation recipes and load event telemetry
• EnergyKit documentation
• ElectricityGuidance
• EnergyVenue