Metrik-Export-API

Extrahieren Sie aufbereitete, report-fertige Zeitreihendaten aus Ihren Anlagen mit einem einzigen Aufruf — über einen Park, viele Parks oder ganze Portfolios hinweg. Das Exportsystem ist um Vorlagen herum aufgebaut, die festlegen, welche Metriken in welcher Reihenfolge exportiert werden. So sind die Zahlen, die Sie in einem generierten Bericht sehen, dieselben Zahlen, die Sie über die API abrufen.

Der kanonische CSV-Download ist GET /v1/export/metrics/template/{template_uid}. Eine JSON-Variante sowie ein separater Roh-Zeitreihen-Export decken In-App-Diagramme und hochauflösende Leistungskurven ab; alle drei werden nachfolgend beschrieben.

In Mirox öffnen

Erstellen und führen Sie einen Export interaktiv unter Datenexport ▸ Builder aus, oder verwalten Sie Ihre Vorlagen unter Datenexport ▸ Vorlagen. Dieselben Vorlagen und Metriken, die hier beschrieben werden, treiben sowohl den In-App-Builder als auch die API an.

Metriktypen verstehen

Die Mirox-Plattform arbeitet mit zwei unterschiedlichen Metriktypen, die verschiedene Zwecke erfüllen:

Erfassung von Rohmetriken

Rohmetriken sind das Fundament der Daten-Infrastruktur der Plattform. Diese Metriken sind:

Direkt von der Hardware erfasst: Abgegriffen von Wechselrichtern, Sensoren und Data-Loggern
Unverändert in der Zeitreihendatenbank gespeichert: Bewahrt die ursprüngliche Granularität und Struktur
Für Echtzeit-Monitoring optimiert: Ermöglicht Live-Dashboards und sofortige Abfragen
Mehrdimensional: Verwendet Labels, um Daten nach Komponente, Standort oder Typ aufzuteilen
Kumulative Zähler: Speichert häufig Gesamtenergiewerte, die im Zeitverlauf ansteigen
Hochfrequent: Können alle paar Sekunden oder Minuten erfasst werden

Rohmetriken sind für den Systembetrieb unverzichtbar, aber nicht für einen benutzerfreundlichen Datenexport optimiert. Sie erfordern Transformation, Aggregation und Interpretation, um zu aussagekräftigen Geschäftsmetriken zu werden.

Ausführliche Informationen zur Erfassung von Rohmetriken finden Sie unter Architektur der Metrikerfassung.

Export-Metriken

Export-Metriken sind aufbereitete, benutzerfreundliche Metriken, die speziell für Datenexport und Berichtswesen konzipiert sind:

Vorab aggregiert: Standardmäßig auf Tagesbasis berechnet
Bereinigt und validiert: Datenqualitätsprüfungen angewendet
Benutzerfreundliche Benennung: Klare, beschreibende Bezeichner
Konsistente Einheiten: Über alle Metriken hinweg standardisiert
Analysebereit: Keine zusätzliche Transformation erforderlich
Geschäftsorientiert: Fokussiert auf KPIs und Reporting-Bedarf

Export-Metriken werden durch metric_id-Zeichenketten identifiziert (z. B. energy_grid_daily, availability_technical) und bilden das Fundament des Exportsystems.

Tips

Wenn Sie die Metrik-Export-API verwenden, arbeiten Sie immer mit Export-Metriken. Die Erfassung von Rohmetriken wird von der Plattform automatisch in diese exportfertigen Formate umgewandelt.

Wichtige Funktionen

Vorlagenbasierte Exporte: Definieren Sie wiederverwendbare Metrikkonfigurationen
Multi-Park-Unterstützung: Exportieren Sie aggregierte Daten aus mehreren Parks oder Portfolios in einer einzigen Anfrage
Mehrere Exportformate: CSV mit konfigurierbaren Trennzeichen für internationale Kompatibilität, plus eine JSON-Variante für In-App-Diagramme
Flexible Zeiträume: Export nach Jahr, Quartal, Monat, Woche oder einem einzelnen Tag
Aggregationsoptionen: Tägliche, wöchentliche, monatliche, quartalsweise oder jährliche Aggregation
Internationale Unterstützung: Anpassbare Datumsformate und Dezimaltrennzeichen
Eigene Metriken: Definieren Sie Ihre eigenen Metriken mit MiroxQL-Formeln

Den richtigen Export wählen

Die Plattform bietet drei unterschiedliche Exportwege. Wählen Sie den, der zu Ihrem Ziel passt:

Export	Endpunkt	Ausgabe	Am besten geeignet für
Vorlagen-CSV	`GET /v1/export/metrics/template/{template_uid}`	CSV-Download	Berichte, Tabellenkalkulationen, Abrechnung — vordefinierte, aggregierte, formelbewusste Spalten über einen oder viele Parks
Vorlagen-JSON	`POST /v1/export/metrics/query`	JSON	Diagramme und Vorschauen innerhalb Ihrer eigenen Anwendung — dieselbe Aggregations-Engine, gibt Zeilen mit datierten Werten zurück
Roh-Zeitreihen	`POST /v1/export/raw/query`	JSON	Hochauflösende Leistungskurven mit der von Ihnen gewählten Schrittweite (5m, 15m, 1h, 1d) — beliebige Rohabfragen, nicht aggregiert

Die Vorlagen-CSV-Route ist der kanonische Metrik-Export und der Schwerpunkt dieser Anleitung. Für programmatischen, formelgesteuerten Zugriff auf Ihre Daten siehe MiroxQL-Abfragesprache — die unterstützte Methode, um Rohzahlen abzufragen und in eigene Metriken zu formen.

Multi-Park in einem Aufruf

Die Vorlagen-CSV- und JSON-Exporte akzeptieren kommagetrennte park- und portfolio-Query-Parameter, sodass Sie eine portfolioweite Aggregation in einer einzigen Anfrage abrufen können. Werden beide angegeben, werden die Parks jedes Portfolios mit den explizit aufgeführten Parks vereinigt.

Vorlagensystem

Was sind Export-Vorlagen?

Export-Vorlagen sind vordefinierte oder eigene Konfigurationen, die Folgendes festlegen:

Welche Metriken in den Export aufgenommen werden
Die Reihenfolge der Metriken in der Ausgabe
Metadaten zu jeder Metrik (Name, Einheit, Kategorie, Beschreibung)

Vorlagen ermöglichen konsistente, wiederholbare Exporte und können organisationsweit geteilt werden. Um Vorlagen ohne jeglichen Code zu erstellen, zu bearbeiten oder zu teilen, öffnen Sie Datenexport ▸ Vorlagen in Mirox.

Vordefinierte Systemvorlage

Die Plattform stellt eine umfassende Standardvorlage bereit, die alle wesentlichen Metriken für das Monitoring und Berichtswesen von Solarparks enthält.

Vorlage „Report Technical v1" (UID: ABCD12340001):

Diese umfassende Vorlage wird sowohl für die PDF-Berichtserstellung als auch für CSV-Exporte verwendet. Sie umfasst:

Zeitreihenmetriken:

Energy Production (kWh) - energy_grid_daily
Energy Radiation Total (kWh) - energy_radiation_daily
GTI Sensor (kWh/m²) - gti_sensor_daily
GTI Weather (kWh/m²) - gti_weather_daily
Sunhours (h) - sunhours_daily
Availability Inverter (%) - availability_inverter
Availability Energy (%) - availability_energy
Availability Data (%) - availability_data
Availability Sensor (%) - availability_sensor
Energy Shutdown by Grid (kWh) - energy_shutdown_grid_daily
Energy Shutdown by External (kWh) - energy_shutdown_external_daily

Berichtskonfigurationsmetriken:

Energy Report (kWh) - energy_report
GTI Report Incident (kWh/m²) - gti_report
GTI Report Effective (kWh/m²) - gti_report_eff
PR Report Target (%) - pr_report

Berechnete Metriken (mit MiroxQL):

Einstrahlungsanalyse (Ist-Wert, Wetternutzung, Sensor-Wetter-Differenz)
Produktionsziele (wetterbasiert, sensorbasiert, Ist-Wert, korrigiert)
Performance Ratios (Wetter, Sensor, Ist-Wert, korrigiert)
Spezifischer Ertrag (Wh/W)
Verlustanalyse (nicht kompensierbare Verluste)

Konsistente Daten über Berichte und Exporte hinweg

Diese Vorlage wird sowohl für die PDF-Berichtserstellung als auch für API-Exporte verwendet und stellt sicher, dass intern generierte Berichte und vom Benutzer exportierte Daten exakt dieselben Metriken und Berechnungen enthalten. Diese Konsistenz ist ein Kernmerkmal der Plattform und ermöglicht zuverlässige Datenvalidierung und -vergleiche.

Informationen zu eigenen berechneten Metriken finden Sie unter MiroxQL-Abfragesprache.

Verfügbare Export-Metriken

Alle Metriken werden auf Tagesbasis berechnet und können zu wöchentlichen, monatlichen, quartalsweisen oder jährlichen Intervallen aggregiert werden. Jede Metrik enthält eine vereinfachte Formel, die zeigt, wie der Wert aus Rohmetriken abgeleitet wird.

Energieproduktionsmetriken

Metrik-ID	Name	Einheit	Beschreibung	Formel
`energy_grid_daily`	Energy Production	kWh	Täglich ins Netz eingespeiste Energie	`sum(delta(grid_energy_total))` pro Komponente
`energy_ac_daily`	AC Production	kWh	Tägliche AC-Energieproduktion	`sum(delta(ac_energy_total))` pro Komponente
`energy_inverter_daily`	Inverter Production	kWh	Tägliche Energieproduktion der Wechselrichter	`sum(delta(inverter_ac_energy_total))` pro Wechselrichter
`energy_radiation_daily`	Energy Radiation Total	kWh	Tägliche Gesamtenergiestrahlung	`sum(delta(radiation_energy_total))` pro Komponente

Abschaltungs-/Verlustmetriken

Metrik-ID	Name	Einheit	Beschreibung	Formel
`energy_shutdown_grid_daily`	Energy Shutdown by Grid	kWh	Täglicher Energieverlust durch Netzbeschränkungen	`sum(delta(energy_loss_total))` wobei type='grid', pro Komponente
`energy_shutdown_external_daily`	Energy Shutdown by External	kWh	Täglicher Energieverlust durch externe Steuerung	`sum(delta(energy_loss_total))` wobei type='external', pro Komponente

Einstrahlungsmetriken

Global-Tilted-Irradiance (GTI)-Metriken sind vergleichbar und messen die Sonneneinstrahlung auf der geneigten Ebene der Solarmodule.

Metrik-ID	Name	Einheit	Beschreibung	Formel
`gti_sensor_daily`	GTI Sensor	kWh/m²	Tägliche globale Einstrahlung auf die geneigte Ebene aus Sensoren	`avg(delta(irradiation_total))` wobei position='module-level' oder Fallback
`gti_weather_daily`	GTI Weather	kWh/m²	Tägliche globale Einstrahlung auf die geneigte Ebene aus Wettervorhersage	`sum(weather_gti) / 4`, Abtastung: 15-Minuten-Intervalle
`gti_report`	GTI Report	kWh/m²	GTI-Zielwert aus der Park-Konfiguration	Wert aus der Park-Konfiguration

Wettermetriken

Metrik-ID	Name	Einheit	Beschreibung	Formel
`solar_radiation_daily`	Solar Radiation	Wh	Durchschnittliche tägliche Sonneneinstrahlung	`avg(solar_radiation)` über 24h
`sunhours_daily`	Sunhours	h	Tägliche Sonnenstunden	`count(weather_gti > 0) / 4`, Abtastung: 15min

Umweltmetriken

Metrik-ID	Name	Einheit	Beschreibung	Formel
`temperature_ambient_avg`	Ambient Temperature	°C	Durchschnittliche tägliche Umgebungstemperatur	`avg(ambient_temperature)` über 24h
`temperature_module_avg`	Module Temperature	°C	Durchschnittliche tägliche Modultemperatur	`avg(module_temperature)` über 24h
`wind_speed_avg`	Wind Speed	m/s	Durchschnittliche tägliche Windgeschwindigkeit	`avg(wind_speed)` über 24h
`humidity_avg`	Humidity	%	Durchschnittliche tägliche Luftfeuchtigkeit	`avg(humidity)` über 24h

Verfügbarkeitsmetriken

Metrik-ID	Name	Einheit	Beschreibung	Formel
`availability_inverter`	Availability Inverter	%	Wechselrichter-Verfügbarkeit basierend auf Leistungsabgabe und GTI-Bedingungen	`avg(1 - count(inverter_power ≤ 0 AND weather_gti > 100))`, Abtastung: 15min
`availability_technical`	Availability Technical	%	Technische Verfügbarkeit des Systems	`avg(sum(scraper_health == 1) / count(scraper_health))` pro Quelle, Abtastung: 15min
`availability_data`	Availability Data	%	Datenverfügbarkeit von der Anlage	`1 - avg(count(grid_energy_total))` bei Abwesenheit, Abtastung: 15min
`availability_sensor`	Availability Sensor	%	Sensor-Verfügbarkeit	`1 - avg(count(solar_radiation))` bei Abwesenheit, Abtastung: 15min
`availability_energy`	Availability Energy	%	Energiebasierte Verfügbarkeitsnäherung	`1 - (sum(energy_loss_total) / (sum(grid_energy_total) + sum(energy_loss_total)))`

Technische Verfügbarkeit ändert sich im Zeitverlauf

Der Geltungsbereich der Metrik availability_technical erweitert sich, wenn neue Plattformfunktionen hinzugefügt werden. Dies kann dazu führen, dass der Wert beim Einspielen neuer Funktionen sinkt, selbst wenn bestehende Systeme normal funktionieren. Für stabile historische Vergleiche verwenden Sie spezifische Metriken wie availability_inverter, availability_data oder availability_sensor.

Batteriemetriken

Batterie-Aggregationen arbeiten auf der Box-Ebene der BESS-Hierarchie — der kanonischen „Gesamt-BESS"-Sicht, die durch das BATTERY-Enum definiert ist. Die vollständige Komponentenhierarchie (environment / box / storage / module / cell) finden Sie auf der Seite Metrikerfassung.

Metrik-ID	Name	Einheit	Beschreibung	Formel
`battery_energy_in_daily`	Battery Energy Charged	kWh	Täglich in die Batterie geladene DC-Energie	`sum(delta(battery_box_energy_dc_in_total))` pro Box
`battery_energy_out_daily`	Battery Energy Discharged	kWh	Täglich aus der Batterie entladene DC-Energie	`sum(delta(battery_box_energy_dc_out_total))` pro Box
`battery_soc_avg`	Battery State of Charge	%	Durchschnittlicher täglicher Ladezustand auf Box-Ebene	`avg(battery_box_soc)` über 24h
`battery_soh_avg`	Battery State of Health	%	Durchschnittlicher täglicher Gesundheitszustand auf Box-Ebene	`avg(battery_box_soh)` über 24h
`battery_energy_charged_avg`	Battery Stored Energy	kWh	Durchschnittliche täglich aktuell gespeicherte Energie	`avg(sum(battery_box_energy_charged))` über 24h
`temperature_battery_avg`	Battery Temperature	°C	Durchschnittliche tägliche Batterietemperatur auf Box-Ebene	`avg(battery_box_temperature)` über 24h

Berichtsmetriken

Metrik-ID	Name	Einheit	Beschreibung	Formel
`energy_report`	Energy Report	kWh	Energie-Zielwert aus der Park-Konfiguration	`Wert aus der Park-Konfiguration`

Zeitraum und Aggregation

Den Zeitraum auswählen

Wählen Sie mit diesen Selektoren aus, welchen Ausschnitt der Historie Sie exportieren möchten:

Jahr: ein vollständiges Kalenderjahr
Quartal: ein Quartal eines bestimmten Jahres
Monat: ein einzelner Kalendermonat
Woche: eine einzelne Kalenderwoche
Tag: ein einzelner Tag (erfordert, dass ein Monat gesetzt ist)

Aggregationsauflösung

Innerhalb des ausgewählten Zeitraums werden die Tageswerte auf die von Ihnen gewählte Auflösung zusammengefasst. Energie- und stundenbasierte Metriken werden summiert; alle anderen Metriken werden gemittelt.

Tägliche Aggregation

Rohe Tageswerte aus dem Zeitreihenspeicher der Plattform
Höchste verfügbare Granularität
Am besten für detaillierte Analyse und Fehlersuche
Dateigröße: Groß

Wöchentliche Aggregation

Daten aggregiert nach ISO-Woche (Montag bis Sonntag)
Enthält Wochennummer- und Kalenderwochen-Spalten
Eine full_week-Option erweitert teilweise erste und letzte Wochen zu vollständigen ISO-Wochen
Geeignet für Trendanalyse
Dateigröße: Mittel

Monatliche Aggregation

Daten aggregiert nach Kalendermonat
Enthält die Spalte „Days in Month" zur Normalisierung
Am besten für Berichtswesen und langfristige Trends
Dateigröße: Klein

Quartalsweise und jährliche Aggregation

Daten zusammengefasst auf Kalenderquartale oder volle Jahre
Am besten für Management-Zusammenfassungen und Jahresvergleiche
Dateigröße: Am kleinsten

Internationale Formatunterstützung

CSV-Trennzeichen

Die API unterstützt mehrere CSV-Trennzeichen für regionale Kompatibilität:

Komma (,): Standard in den USA/UK
Semikolon (;): Standard in Deutschland und vielen europäischen Ländern
Tabulator (\t): Universell, gut für den Excel-Import
Pipe (|): Alternative für Sonderfälle

Dezimaltrennzeichen

Punkt (.): Standard in den USA/UK (z. B. 1234.56)
Komma (,): Standard in Deutschland und vielen europäischen Ländern (z. B. 1234,56)

Gefahr

Das CSV-Trennzeichen und das Dezimaltrennzeichen müssen unterschiedlich sein, um Parsing-Probleme zu vermeiden.

Datumsformate

Eigene Datums-/Zeitformate können mit der Python-strftime-Syntax angegeben werden:

Gängige Formate:

%Y-%m-%d: ISO-Format (2025-03-15)
%d/%m/%Y: europäisches Format (15/03/2025)
%m/%d/%Y: US-Format (03/15/2025)
%d.%m.%Y: deutsches Format (15.03.2025)
%Y-%m: nur Monat (2025-03)
%Y-W%W: ISO-Wochenformat (2025-W11)

CSV-Ausgabeformat

Die exportierten CSV-Dateien enthalten Kopfzeilen mit Metriknamen und Einheiten. Die Struktur variiert je nach Aggregationsintervall:

Monatlicher Export

Enthält eine Spalte „Days in Month" zur Normalisierung.

Wöchentlicher Export

Enthält sowohl eine Spalte „Date" (ISO-Wochenformat) als auch „Calendar Week" (Wochennummer).

Täglicher Export

Eine Zeile pro Tag mit dem Datum im angegebenen Format.

Anwendungsfälle

Eigenes Berichtswesen

Erstellen Sie spezialisierte Export-Vorlagen für:

Monatliche Leistungsberichte
Quartalsweise Stakeholder-Updates
Jährliche Compliance-Berichterstattung
Eigenes KPI-Tracking

Drittanbieter-Integration

Exportieren Sie Daten zur Integration mit:

Energiemanagementsystemen
Business-Intelligence-Plattformen
Software zur CO₂-Bilanzierung
Portfolio-Management-Tools

Datenanalyse

Speisen Sie die exportierten Zahlen in Ihre eigene Analytik ein:

Performance-Benchmarking
Saisonale Trendanalyse
Einspeisung in Business-Intelligence- und Reporting-Pipelines

Authentifizierung und Berechtigungen

Alle Export-Endpunkte erfordern eine authentifizierte Sitzung. Sie können sie aus einer Browser-Sitzung heraus oder mit einem API-Token ansteuern, das die Berechtigungsgruppe reporting trägt.

Was Sie benötigen:

Vorlagenverwaltung: Rechte zum Lesen, Erstellen, Ändern oder Löschen von Export-Vorlagen innerhalb Ihrer Organisation. Systemvorlagen sind für alle schreibgeschützt.
Metrik-Export: Lesezugriff zum Exportieren von Berichten.
Park-Zugriff: Sie erhalten immer nur Daten für die Parks und Portfolios, die Sie sehen dürfen. Angeforderte Parks, auf die Sie keinen Zugriff haben, werden stillschweigend herausgefiltert — und bleibt keiner zugänglich, wird die Anfrage abgelehnt.

Bewährte Praktiken

Geeignete Vorlagen wählen: Verwenden Sie nach Möglichkeit vordefinierte Vorlagen, erstellen Sie eigene für spezifische Bedürfnisse
Korrekte Aggregation wählen: Verwenden Sie monatlich für Berichte, täglich für detaillierte Analyse
Passende Trennzeichen festlegen: Stimmen Sie sie auf Ihre lokalen Excel-/CSV-Einstellungen ab
Multi-Park-Exporte: Nutzen Sie die Multi-Park-Fähigkeiten für Portfolio-weite Analysen
Wiederverwendbarkeit von Vorlagen: Erstellen Sie organisationsweite Vorlagen für konsistentes Berichtswesen
MiroxQL verwenden: Definieren Sie eigene berechnete Metriken für fortgeschrittene Analysen

Praktisches Beispiel

Ein vollständiges Implementierungsbeispiel zur Erstellung eigener Berichte mit der Metrik-Export-API finden Sie im Beispiel zum Berichtsgenerator. Dieses Beispiel zeigt, wie Sie Daten aus der API abrufen, verarbeiten und eigene Berichte mit Visualisierungen erstellen.

Fehlerbehandlung

Häufige Fehlerantworten:

404 Not Found: Vorlage, Park oder Portfolio existiert nicht
403 Forbidden: Unzureichende Berechtigungen oder keine zugänglichen Parks
422 Validation Error: Ungültige Parameter (z. B. ungültige Metrik-IDs)
400 Bad Request: Ungültige Parameterkombinationen (z. B. identisches CSV- und Dezimaltrennzeichen)
409 Conflict: Vorlagenname existiert bereits in der Organisation