> ## 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.

# Market data from Cloover

> The network operators' Bilanzierungsdaten and profiles, forwarded via Drive, and the SLS rolled out from them

For profiled customers the network operator does not send the BKV a sum
time series it could use before settlement: the BK-SZR (Kategorie A) of
the SLS arrives at the earliest on the 12th Werktag after the month. What
the supplier receives earlier is enough to compute it: per market location
the annual consumption forecast and the load profile, and per network
operator the profile values. For profiled customers the rolled-out profile
*is* the forecast and the Ist.

Cloover's MaKo system receives those messages as supplier and forwards
them, converted to BO4E JSON (one file per message), to a shared Drive
folder. An Apps Script posts every new file to the bridge.

## What is forwarded

| Message | Content | Used for |
| - | - | - |
| UTILMD **55126** / 55672 | Bilanzierungsdaten per consuming / producing market location: Zeitreihentyp, load profile, procedure (synthetic/analytic), JVP, Bilanzkreis, Bilanzierungsgebiet, *Verwendung der Daten ab/bis* | which customers are in the SLS, and their scaling |
| UTILMD **55073** | the operator's profile definitions: normalization (1,000,000 kWh/a, 1,000,000 kW, 300 kWh/K), procedure, TLP parameters | how a profile is scaled |
| MSCONS **13010** | a normalized profile, quarter-hourly, per day | the SLS values (daily, D+1, for analytic operators) |
| MSCONS **13011** | a Profilschar: a family of day curves valid from a month | temperature-dependent customers (TLS) |

## The roll-out

Per Bilanzierungsgebiet and quarter hour:

```
SLS = Σ over its SLS market locations   13010 value × 0.25 × JVP / 1,000,000
```

The 13010 values are average power for a profile normalized to
1,000,000 kWh/a, so `× 0.25` is the quarter hour's energy. The JVP comes
from the 55126; of several 55126 for one market location, the latest
message valid on the day wins.

* **No 55073 for the profile**: 1,000,000 kWh/a is assumed and said so in
  the result.
* **Normalized otherwise** (1,000,000 kW, 300 kWh/K): not scaled by the
  JVP - counted under `nicht_skalierbar`.
* **No 13010 for the day**: the market location is counted under
  `fehlende_profile`, never rolled out as 0.
* **A day curve that adds up to 1,000** (× 0.25): flagged - that is the
  shape of a temperature-dependent day curve, not an annual profile.

Temperature-dependent customers (TLS) need, in addition, the day's
temperature at the measuring point the 55126 names. In a 13011 the curve
at position *n* adds up to *n* kWh per day for 1 kWh/K: the position is the
temperature difference in Kelvin. The bridge stores them; rolling out TLS
waits for the temperature data.

## Endpoints

All under the report scope - the read-only report key is enough.

| Call | Purpose |
| - | - |
| `POST /v1/process/marktdaten/import` | one file: `{"dokument": <the JSON>, "datei": "...", "drive_id": "..."}`. Idempotent per message (business key); answers `neu: false` for a repeat. Unknown Prüfidentifikatoren are stored and answered `art: unbekannt`. |
| `GET /v1/process/marktdaten/abdeckung` | per Bilanzierungsgebiet with customers or 55126 data: market locations per Zeitreihentyp against the Kundenhochlauf, from when the 55126 applies, profiles with the days held, Profilscharen, definitions, and hints for everything the roll-out still lacks |
| `GET /v1/process/marktdaten/sls?tag=YYYY-MM-DD` | the rolled-out SLS of a day, per Bilanzierungsgebiet and in total, kWh per quarter hour |
| `GET /v1/process/marktdaten/dateien` | the latest imports |

The files hold market location IDs. They stay on the audit share
(`marktdaten/`, ledgers `marktdaten_*`); every response, event and the
Slack log carry counts only. The per-file event `marktdaten_importiert` is
kept out of the Slack log; `marktdaten_unbekannt` (warning) is not.

## Setting up the Drive script

`scripts/drive_marktdaten.gs`, run with an account that can read the
folder:

1. [script.google.com](https://script.google.com) → new project, paste the
   file; `CONFIG.FOLDER_ID` is the Drive folder.
2. Project settings → Script properties: `REPORT_API_KEY` = the bridge's
   report key.
3. Run `marktdatenSenden` once and grant Drive and external-request
   access.
4. Triggers → `marktdatenSenden`, time-driven, every hour.

The script sends every `.json` file (subfolders included) changed since
the newest one it delivered, oldest first, at most 150 per run - a large
first load spreads over a few runs. A failed call stops the run; the next
one retries. `allesNeuSenden` starts over; the bridge ignores what it has.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.