> ## Documentation Index
> Fetch the complete documentation index at: https://docs.energy.nlead.ch/llms.txt
> Use this file to discover all available pages before exploring further.

# Data Delivery

> What to send: a portfolio forecast, or the data to build one from

There are two ways to feed the bridge. Use whichever matches the data you
have — they can also be combined (send forecasts for the portfolio you do
forecast, and master/metered data for the rest).

## Option A — portfolio forecast

`POST /v1/forecasts`, one call per delivery day.

| Field                   | Meaning                                                                           |
| ----------------------- | --------------------------------------------------------------------------------- |
| `delivery_day`          | The day the energy is delivered (`YYYY-MM-DD`, Europe/Berlin)                     |
| `unit`                  | `MW` (average power per quarter-hour, default) or `MWH` (energy per quarter-hour) |
| `series[].kind`         | `production` or `consumption` — always separate series                            |
| `series[].control_area` | `50Hertz`, `Amprion`, `TenneT` or `TransnetBW`                                    |
| `series[].values`       | One value per quarter-hour, local midnight to midnight                            |
| `series[].malo`         | Market location ID — 11 digits (alternative to `control_area`)                    |

Rules that are enforced:

* **Interval count must match the day**: 96 normally, **92** on the
  spring-forward day, **100** on the fall-back day. A 96-value series for a
  DST day is rejected.
* **No gaps** — a series must cover the whole day.
* **MaLo format** — a market location ID is exactly 11 digits; anything
  else is rejected.
* Multiple series per area and kind are allowed; they are summed.
* A subset of control areas is fine; areas you omit count as zero.

### Tagging by market location instead

If your data is per market location rather than per control area, tag the
series with `malo` and add a `malo_mapping`:

```json theme={null}
{
  "delivery_day": "2026-08-01",
  "series": [
    {"kind": "consumption", "malo": "51238696781", "values": ["…96 values"]}
  ],
  "malo_mapping": { "51238696781": "Amprion" }
}
```

## Option B — master and metered data

When you have no forecast, send what you do have and the bridge builds the
consumption forecast per market location:

| Endpoint                | What to send                                                                                                                                      | How often                                                                                |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
| `PUT /v1/master-data`   | Market-location master data: control area, metering grid area (MGA), metering type, supply period, load-profile code, annual consumption forecast | On change (new customer, move-in/out, updated annual forecast, profile or regime change) |
| `POST /v1/metered-data` | Quarter-hourly metered values per market location and day                                                                                         | As readings arrive                                                                       |
| `POST /v1/profiles`     | The DSO's/MGA's rolled-out day profiles per profile code and day                                                                                  | When the network operator publishes them                                                 |

These correspond to the content of your market communication (UTILMD
master data, MSCONS metered values, network-operator profiles), so they can
be fed directly by your market-communication provider.

### Master data changes over time

A market location is not a static record: the annual consumption forecast
gets revised, a customer switches from a standard load profile to
quarter-hourly metering, the metering grid area changes, supply ends and
may resume later. Master data is therefore stored as **time slices** — each
with a `valid_from` (inclusive) and optional `valid_to` (exclusive) — and
every delivery day is forecast with the data that was valid **on that day**.

Send one slice per change; you do not need to resend the history:

```json theme={null}
{
  "locations": [
    {
      "malo": "51238696781",
      "slices": [
        {
          "valid_from": "2026-09-01",
          "control_area": "Amprion",
          "mga": "MGA-WEST",
          "metering_type": "profiled",
          "profile_code": "H0",
          "annual_consumption_kwh": 4200
        }
      ]
    }
  ]
}
```

The slice wins for its own window: an existing open-ended slice is
truncated at 1 September, everything before it stays as it was. Sending a
bounded slice (`valid_from` + `valid_to`) inserts a correction into the
middle of the history and leaves the surrounding periods intact. Sending
the same slices twice changes nothing.

**Ending and resuming supply.** To end supply, send a slice with
`"active": false` from the end date. To resume later, send a normal active
slice from the new start date — the gap in between is treated as
"not supplied" and those days are excluded from the forecast:

```json theme={null}
{"malo": "51238696781", "slices": [{"valid_from": "2026-10-01", "active": false}]}
```

<Note>
  For a market location with one uninterrupted supply period you can skip
  the slice structure and send the flat form —
  `delivery_start`, `delivery_end` and the attributes directly on the
  location. It is shorthand for a single slice.
</Note>

### How the forecast is derived

| Your customer                          | Method                                                                                       |
| -------------------------------------- | -------------------------------------------------------------------------------------------- |
| Profiled (SLP/TLP)                     | The MGA's rolled-out day profile, scaled to the customer's annual consumption forecast       |
| Quarter-hourly metered, with history   | *Vergleichstagsprognose*: the mean of the most recent comparable days (same day type)        |
| Quarter-hourly metered, no history yet | Profiled method, using the profile code and annual consumption forecast from the master data |

<Warning>
  A market location can only be forecast if its master data is complete:
  profiled locations need a **profile code** and an **annual consumption
  forecast**, and the matching **rolled-out profile day** must have been
  delivered. Locations with missing inputs are reported back and are not
  silently assumed to be zero.
</Warning>

## Units and signs

* Production and consumption are both sent as **positive** values; the
  bridge computes the net position.
* `MW` values are averages over the quarter-hour; `MWH` values are the
  energy in that quarter-hour. Metered data additionally accepts `KWH`.

## Corrections

Re-sending replaces: a new forecast for the same delivery day supersedes
the previous one, updated master data overwrites the previous record, and
re-sent metered days replace the stored day. Everything downstream re-runs
on the new data automatically.