Home Assistant
Ecosmart is built into Home Assistant from version 2026.11. Add it from Settings for a spot price sensor and the forecast, or use the REST sensors below for tomorrow's lowest- and highest-priced half-hours.
Built into Home Assistant since 2026.11Add the Ecosmart integration
Ecosmart ships with Home Assistant from version 2026.11 (the announcement), so there is nothing to download and no YAML to write. You need an Ecosmart electricity account with at least one property switched to us.
- Create an API key in the Ecosmart app at my.ecosmart.co.nz: More → Settings → API keys (under the Advanced heading). A new key revokes the previous one, so anything still using the old key stops working.
- In Home Assistant, go to Settings → Devices & services → Add Integration and search for Ecosmart. Or open it in your Home Assistant in one click.
- Paste the key. Each property (ICP) on your account becomes a device with a Spot price sensor: the wholesale price at your grid exit point in c/kWh including GST, updated about every five minutes.
For the forecast, call the ecosmart.get_forecasts action from a script or automation. Home Assistant’s Ecosmart integration page has the full details, known limitations and troubleshooting.
- Not for the Energy dashboard’s price. The dashboard expects dollars per kWh, so costs would show 100 times too high, and the sensor is the wholesale price only.
- Stale prices go unavailable. If the price is more than about fifteen minutes old, or Home Assistant can’t reach us, the sensor shows unavailable instead of an old number.
- Ran the early test version? Delete the
custom_components/ecosmartfolder and restart, or Home Assistant keeps loading it in place of the built-in integration.
- Still switching to us? Setup says the key has no connection points until your property is live with us. Try again then.
REST sensors
The integration gives you the price now and the forecast as an action. If you want the forecast as a sensor, or tomorrow’s lowest- and highest-priced half-hours, use these REST sensors. They also work on Home Assistant versions before 2026.11, and you can run them beside the integration.
Put the key in secrets.yaml, never in configuration.yaml.
ecos_api_key: "Bearer ecos_live_your_key_here"
The word Bearer is part of the secret. If that secret is missing, Check Configuration fails on !secret ecos_api_key.
There are two placeholders to fill in. Both values come from GET /me.
YOUR_POC, in both resource URLs: yourpoc, the code of your grid exit point (GXP, where the national grid hands power to your local network), for exampleHAY2201. If you leave it, Home Assistant saves the file but the sensors never show a price: the live price answers404UNKNOWN_POC, and the forecast comes back empty with anunavailableReason.*icp_from_GET_me: youricp, in quotes, for example"0000123456ABCDE". If you leave it, Home Assistant refuses to save (found undefined alias 'icp_from_GET_me').
Then either:
- Download home-assistant.yaml, fill in those two placeholders, and drop the file in
config/packages/if you use packages, or - Paste the snippets below into
configuration.yamlin this order — allrest:items together, thentemplate:.
Poll the live price every 5 minutes — faster than that returns the same number and spends your budget. Poll the forecast and tomorrow’s ranking every 30 minutes.
Need a key first? Overview.
Every price in these sensors uses priceCentsPerKwhInclGst, the wholesale price with GST included. For prices before GST, use priceCentsPerKwh in its place in each sensor. The priceDollarsPerMwh attribute is the raw market figure, before GST.
Current price
rest:
- resource: https://api.ecosmart.co.nz/rest/v1/gxps/YOUR_POC/spot
scan_interval: 300
headers:
Authorization: !secret ecos_api_key
sensor:
- name: Spot price
unique_id: ecos_spot_price
value_template: "{{ value_json.priceCentsPerKwhInclGst | round(2) }}"
unit_of_measurement: "c/kWh"
state_class: measurement
availability: "{{ not value_json.isStale }}"
json_attributes:
- observedAt
- ageSeconds
- isStale
- priceDollarsPerMwh
availability uses isStale, so the sensor goes unavailable rather than quietly holding a stale price if the feed stops.
Forecast
A Home Assistant state is capped at 255 characters, so the state is the current half-hour and the rest of the curve lives in an attribute.
- resource: https://api.ecosmart.co.nz/rest/v1/gxps/YOUR_POC/forecast
params:
hours: 24
scan_interval: 1800
headers:
Authorization: !secret ecos_api_key
sensor:
- name: Spot forecast
unique_id: ecos_spot_forecast
value_template: "{{ value_json.points[0].priceCentsPerKwhInclGst | round(2) }}"
unit_of_measurement: "c/kWh"
availability: "{{ value_json.points | length > 0 }}"
json_attributes:
- points
- coveredHours
- publishedAt
- unavailableReason
Tomorrow’s lowest- and highest-priced half-hours
Scattered half-hours on tomorrow’s New Zealand trading date, not a consecutive block. Use this to fill a battery’s time-based schedule; use the template below if you want “the next cheap 90 minutes from now”.
This is another item in the same rest: list as the sensors above.
- resource: https://api.ecosmart.co.nz/rest/v1/windows
params:
icp: *icp_from_GET_me
n: 6
scan_interval: 1800
headers:
Authorization: !secret ecos_api_key
sensor:
- name: Tomorrow cheapest half-hour
unique_id: ecos_windows_cheap_start
value_template: >
{% if value_json.cheap is defined and value_json.cheap | length > 0 %}
{{ value_json.cheap[0]['startsAt'] }}
{% elif value_json.code is defined %}
{{ value_json.code }}
{% else %}
unknown
{% endif %}
json_attributes:
- cheap
- dear
- networkTou
- tradingDate
- indicative
- unavailableReason
- code
- message
Lowest-priced 90 minutes in the next 24 hours
A template over the forecast attribute. The state is the start time of the cheapest three consecutive half-hours.
template:
- sensor:
- name: Cheapest 90 minutes
unique_id: ecos_cheapest_window
state: >
{% set pts = state_attr('sensor.spot_forecast', 'points') or [] %}
{% if pts | length < 3 %}
unknown
{% else %}
{% set ns = namespace(best=None, cost=None) %}
{% for i in range(pts | length - 2) %}
{% set c = (pts[i].priceCentsPerKwhInclGst
+ pts[i+1].priceCentsPerKwhInclGst
+ pts[i+2].priceCentsPerKwhInclGst) / 3 %}
{% if ns.cost is none or c < ns.cost %}
{% set ns.cost = c %}
{% set ns.best = i %}
{% endif %}
{% endfor %}
{{ pts[ns.best].startsAt }}
{% endif %}
- binary_sensor:
- name: Spot is cheap
unique_id: ecos_spot_cheap
# Pick your own threshold — 10 c/kWh incl. GST is only an example.
state: "{{ states('sensor.spot_price') | float(999) < 10 }}"
points[0] is the half-hour in progress. If you want strictly future windows, drop the first point before ranking.
Reload Home Assistant (Developer Tools → YAML → REST entities, or a full restart) after saving.