# Connect pvnode with Home Assistant

This guide shows how to use the pvnode Forecast API in Home Assistant via the
built-in [RESTful Sensor](https://www.home-assistant.io/integrations/rest/) — 
no custom component required.

:::note
An official HACS integration is planned and will be released alongside the 
pvnode V2 API. The setup described here works with the current API today.
:::

## Prerequisites

- A running Home Assistant installation
- A pvnode API key ([create one here](https://pvnode.com/settings/api-keys))
- Access to `configuration.yaml` (File Editor add-on or SSH)

## 1. Store the API key securely

Open `secrets.yaml` in your `config/` directory (create it if it doesn't exist):

```yaml
pvnode_api_key: "Bearer YOUR_API_KEY"
```

## 2. Add a REST sensor in `configuration.yaml`

Paste the following block into your `configuration.yaml` and adjust the 
location and PV configuration to match your system:

```yaml
rest:
  - resource: https://api.pvnode.com/v1/forecast/
    method: GET
    headers:
      Authorization: !secret pvnode_api_key
    params:
      latitude: 48.27564
      longitude: 11.83972
      slope: 30
      orientation: 180
      pv_power_kw: 10
      forecast_days: 2                 # number of forecast days
      required_data: "pv_watts,temp"   # power and temperature returned
    scan_interval: 3600                # update every 60 minutes
    sensor:
      - name: "pvnode Power Now"
        unique_id: pvnode_power_now
        unit_of_measurement: "W"
        device_class: power
        state_class: measurement
        value_template: >
          {% set rounded = now().replace(second=0, microsecond=0, minute=(now().minute // 15) * 15) %}
          {% set target = rounded.astimezone(timezone('UTC')).strftime('%Y-%m-%d %H:%M:%S') %}
          {% set match = value_json.values | selectattr('dtm', 'eq', target) | list %}
          {{ match[0].pv_watts | round(0) if match else 0 }}
        json_attributes:
          - values
          - latitude
          - longitude
          - slope
          - orientation
          - elevation
```

### Parameter overview

| Parameter | Description                                                                                       |
|-----------|---------------------------------------------------------------------------------------------------|
| `latitude` / `longitude` | Location of the PV system                                                                         |
| `slope` | Module tilt in degrees (0 = flat, 90 = vertical)                                                  |
| `orientation` | Azimuth in degrees (0 = North, 90 = East, 180 = South, 270 = West)                                |
| `pv_power_kw` | Installed capacity in kWp                                                                         |
| `forecast_days` | Number of forecast days (0–7)                                                                     |
| `required_data` | Which fields the API should return — see all available fields [here](/docs/en/guides/data-columns) |

A complete overview of all parameters and data fields is available in the 
[Forecast API documentation](/docs/api/v1-endpoints#forecast).

## 3. Reload the configuration

After saving, in Home Assistant: **Developer Tools → YAML → 
Reload all YAML configuration**. On first setup, a full restart is required.

Under **Developer Tools → States**, find the sensor `sensor.pvnode_power_now` — 
the state shows the current power in watts, while the attributes contain the 
full 15-minute forecast.

## 4. Visualize the forecast as a chart

With the [ApexCharts Card](https://github.com/RomRider/apexcharts-card) 
(installable via HACS), you can plot the entire forecast series as a curve:

```yaml
type: custom:apexcharts-card
header:
  show: true
  title: PV Forecast
graph_span: 48h
span:
  start: day
series:
  - entity: sensor.pvnode_power_now
    name: pvnode Forecast
    type: line
    stroke_width: 2
    extend_to: false
    data_generator: |
      return entity.attributes.values.map(point => {
        const utcTime = new Date(point.dtm + 'Z').getTime();
        return [utcTime, point.pv_watts];
      });
```

## Use cases

With the pvnode forecast in Home Assistant you can, for example:

- **Control your wallbox:** Charge your EV when sufficient solar production is expected
- **Schedule heat pumps:** Run hot water preparation during expected surplus periods
- **Optimize batteries:** Fully charge before forecasted poor-weather periods
- **Shift loads:** Start washing machines, dryers, or dishwashers during peak production

## Tips

- **Higher resolution with Nowcasting:** With the Nowcasting add-on, the 
  forecast updates every 10 minutes based on live satellite data. In that 
  case, set `scan_interval: 600`.
- **Multiple arrays:** For east/west roofs or multiple strings, simply add 
  additional REST sensors with different `unique_id` values.