# Migration from V1

The V2 API changes the core principle: instead of configuring every request via URL parameters,
you create **sites** and query them through their `site_id`.

:::note
The V1 API remains unchanged and still available. You do **not** have to migrate immediately —
this guide helps you switch when you want to take advantage of V2. The V1 API is expected to be
shut down on **2026-12-31**.
:::

## The new core principle

|                               | V1                                   | V2                                  |
|-------------------------------|--------------------------------------|-------------------------------------|
| Configuration                 | Per request in the URL               | Stored once as a site               |
| Query                         | `/v1/forecast?latitude=…&slope=…`    | `/v2/forecast/{site_id}`            |
| Strings                       | One or two strings via parameters    | Multiple `strings` per site         |
| Elevation/timezone/terrain    | Computed per request as needed       | Determined & stored automatically   |

For use cases without persistent sites (e.g. one-off calculations) there are the
[inline endpoints](/en/v2/enterprise/inline), which come closest to the old URL logic.

## Endpoint mapping

| V1                       | V2                                                               |
|--------------------------|------------------------------------------------------------------|
| `GET /v1/forecast?…`     | `GET /v2/forecast/{site_id}` or `POST /v2/forecast/inline`       |
| `GET /v1/history?…`      | `GET /v2/historical/{site_id}` or `POST /v2/historical/inline`   |
| `GET /v1/recent?…`       | Included in `GET /v2/historical/{site_id}`                       |
| (no site management)     | `POST/GET/PATCH/DELETE /v2/sites`                                |

In V2, **`/recent` and `/history` are merged into a single endpoint**.

## Field names & response format

V2 uses clear field names and local timestamps throughout.

| V1                     | V2                                                       |
|------------------------|----------------------------------------------------------|
| `dtm` (UTC)            | `timestamp` (local ISO-8601 time, see `timezone`)        |
| `spec_watts` (W/kWp)   | dropped — V2 returns `pv_power` directly in W            |
| `pv_watts`             | `pv_power` (W)                                           |
| `GHI` / `DHI` / `BNI`  | `ghi` / `dhi` / `bni`                                    |
| `temp`, `weather_code` | `temp`, `weather_code` (named unchanged)                |

Key differences:

- **Timestamps are local**, not UTC. The IANA timezone is in the `timezone` field.
- **`gti` / `gti_shaded` are per string** and live in the `strings` block (tilted irradiance
  depends on the orientation) — see [Forecasts](/en/v2/api/forecast).
- `spec_power` / `spec_watts` is **no longer returned**; use `pv_power`.

## `required_data` → `include` groups

Instead of a free column list (`required_data=pv_watts,temp`), in V2 you select
**field groups** via the repeatable `include` parameter:

```bash title="V1"
GET /v1/forecast?required_data=pv_watts,temp,GHI
```

```bash title="V2"
GET /v2/forecast/{site_id}?include=weather&include=irradiance
```

Available groups: `default`, `weather`, `irradiance`, `clearsky`, `strings`, `variability`,
`all`. Details under [Forecasts](/en/v2/api/forecast).

## Migration steps

1. **Keep using your API key** — the same key works for V1 and V2.
2. **Create a site** for each existing parameter combination (`POST /v2/sites`).
3. Switch queries to `GET /v2/forecast/{site_id}` or `GET /v2/historical/{site_id}`.
4. Account for the **new field names** and **local timestamps** in your code.
5. Replace `required_data` with the matching `include` groups.

You'll find the complete endpoint and field reference in the [API Reference](/api).

## Migrating integrations

If you use an integration such as Solectrus, EVCC or ioBroker, you have to wait for an update of
the respective integration before you can switch to V2. We'll track the development progress
[here](/en/v2/integrations/index).