FAQ & Feldreferenz

Optionale Felder, die nicht im Request enthalten sind, werden von der API vollständig ignoriert – ohne Fehlermeldung. Die Berechnung des MFI läuft trotzdem durch, basiert dann aber ausschließlich auf den vorhandenen Daten.

Intern vermerkt die API, welche Felder fehlten: Sie erscheinen im Antwortfeld missing_fields als Array. Das ist keine Fehleranzeige, sondern lediglich eine Transparenzinformation – du weißt dadurch genau, womit die API gerechnet hat.

Konkrete Folge: Jeder Check, der auf ein fehlendes Feld angewiesen ist, wird übersprungen. Der Temperatur-Check und der Regen-Check laufen immer, weil ihre Felder Pflicht sind. Der Bodentemperatur-Check (soiltemp) läuft nur, wenn soil_temperature geliefert wurde. Der Luftfeuchtigkeits-Check (humidity) nur, wenn humidity vorliegt. Gleiches gilt für den Wind-Check und wind_speed.

Übersprungene Checks fließen nicht in die Score-Berechnung ein – sie beeinflussen den index_score weder positiv noch negativ. Der Score wird also nicht schlechter, weil ein Check fehlt, aber er wird durch den fehlenden Check auch nicht abgesichert.

Ungültige Werte bei optionalen Feldern werden ebenfalls stillschweigend ignoriert – genauso als wäre das Feld gar nicht übermittelt worden. Das gilt in zwei Fällen:

• Nicht-numerischer Wert: Wenn ein Feld einen String wie "abc" enthält, wird es verworfen.
• Außerhalb des Gültigkeitsbereichs: Liegt ein Wert außerhalb der definierten Grenzen (z. B. humidity: 110 bei einem Bereich von 0–100), wird er ebenfalls verworfen.

Das verworfene Feld erscheint dann in missing_fields, obwohl es technisch übermittelt wurde. Aus Sicht der API-Logik gilt es als „nicht vorhanden".

Anders bei Pflichtfeldern (temperature und precipitation_rate): Fehlen oder ungültige Werte dort führen sofort zu einem HTTP 422-Fehler.

Je mehr relevante Felder übermittelt werden, desto fundierter ist die Bewertung. Das spiegelt sich direkt im Feld data_quality wider, das drei Stufen kennt: full, partial und minimal.

Ein konkretes Beispiel: Wer nur temperature und precipitation_rate übergibt, erhält ein gültiges Ergebnis – aber ohne Boden-, Feuchtigkeits- oder Windanalyse. Der Score basiert dann auf zwei von fünf möglichen Checks. Der Gesamtstatus (main_status) kann dadurch tendenziell optimistischer wirken, weil problematische Faktoren wie nasser Boden oder Böen gar nicht bewertet wurden.

Das Ergebnis ist in jedem Fall korrekt auf Basis der gelieferten Daten – es ist jedoch nicht dasselbe wie ein Ergebnis mit vollständigen Eingaben. data_quality und missing_fields helfen dabei, diesen Unterschied transparent nachzuvollziehen.

Standardmäßig bestimmt die API die Jahreszeit automatisch aus dem aktuellen Monat des Servers (season_source: "auto"). Für Tests lässt sich die Jahreszeit gezielt erzwingen, um das Verhalten der saisonabhängigen Schwellenwerte und Gewichtungen zu prüfen, ohne auf den passenden Kalendermonat warten zu müssen.

Dazu werden zwei Steuerfelder gemeinsam im Request mitgesendet:

• debug – muss auf true stehen. Ohne aktiven Debug-Modus wird eine übermittelte Jahreszeit ignoriert.
• season – die gewünschte Jahreszeit: spring, summer, autumn oder winter.

Greift der Override, enthält die Antwort season_source: "manual" und das Feld season trägt die erzwungene Jahreszeit. Es handelt sich um eine reine Test-/Debug-Funktion; im Produktivbetrieb sollten beide Felder nicht gesendet werden.

{
  "temperature":        4.0,
  "precipitation_rate": 0.0,
  "debug":              true,
  "season":             "winter"
}

Die Antwort enthält dann "season": "winter" und "season_source": "manual" – unabhängig vom realen Kalendermonat.

Die Version der intern verwendeten MFI-Berechnungslogik – zum Beispiel "1.0". Dieser Wert wird aus den API-Einstellungen gelesen und ist nicht identisch mit der API-Versionsnummer (z. B. v1 im URL-Pfad).

Die mfi_version wird immer dann erhöht, wenn sich die Berechnungslogik, Schwellwerte oder Gewichtungen grundlegend ändern – zum Beispiel wenn neue Checks hinzugefügt oder bestehende Algorithmen überarbeitet werden. Damit können Nutzer nachvollziehen, ob sich ein unterschiedliches Ergebnis aus geänderten Eingabedaten oder aus einer aktualisierten Logik ergibt.

Die Jahreszeit, die der API-Server zum Berechnungszeitpunkt als aktiv erkennt. Die Zuordnung basiert ausschließlich auf dem aktuellen Monat des Servers – unabhängig vom Standort des Nutzers oder der übermittelten Wetterdaten:

Die Jahreszeit beeinflusst maßgeblich, wie streng oder nachsichtig einzelne Checks bewertet werden. Die Schwellenwerte für Temperatur, Boden, Wind und Feuchtigkeit sind je Jahreszeit hinterlegt. Zusätzlich steuert die Jahreszeit im Minimum-Modell, wie stark der schlechteste Check gewichtet wird: In Herbst und Winter fällt dieses Gewicht höher aus, weil der Boden träger abtrocknet und ein limitierender Faktor länger bestimmend bleibt. Dadurch werden ungünstige Bedingungen in der Vegetationsruhe insgesamt kritischer bewertet.

Gibt an, woher die für die Berechnung verwendete Jahreszeit stammt:

• auto – automatisch aus dem aktuellen Monat des Servers bestimmt. Das ist der Normalfall.
• manual – im Request erzwungen (siehe Abschnitt zur Saison-Simulation). Nur im Debug-/Testkontext möglich.

Im Produktivbetrieb steht hier praktisch immer auto.

Der zusammengesetzte Gesamt-Indexwert, der die Mähbarkeit als einzelne Zahl ausdrückt. Je höher der Wert, desto besser die Bedingungen. Berechnet wird er nach dem Minimum-Modell (Liebigsches Minimumprinzip):

Gesamt = w · min(Check-Indexwerte) + (1 − w) · gewichtetes Mittel

• Minimum-Anteil: Der niedrigste Check-Indexwert (der limitierende Faktor) geht mit dem Gewicht w ein. So kann ein einzelner kritischer Faktor das Gesamtergebnis dominieren.
• Gewichtetes Mittel: Alle ausgeführten Checks fließen anteilig nach ihrer Mährelevanz ein (Regen und Luftfeuchte am stärksten, Wind am schwächsten).

Das Gewicht w ist saisonal: in Herbst und Winter höher, sodass der schlechteste Faktor stärker durchschlägt. Nur tatsächlich ausgeführte Checks zählen; übersprungene Checks verändern den Wert weder positiv noch negativ. Welcher Check limitierend war, steht in score_basis.limiting_check.

Der Gesamtstatus – im Kern aus dem index_score abgeleitet:

Zusätzlich gelten Durchgriffsregeln, die den reinen Score-Wert überstimmen können:

• Hat irgendein ausgeführter Check den Status BLOCK, ist der Gesamtstatus zwingend BLOCK – unabhängig vom rechnerischen Index.
• Hat der Regen- oder Luftfeuchte-Check den Status WARNING, ist der Gesamtstatus mindestens WARNING.

Gibt an, wie vollständig die übermittelten Eingabedaten im Verhältnis zu allen möglichen Feldern waren. Grundlage ist das Verhältnis gültig übermittelter Felder zur Gesamtzahl von 17 Eingabefeldern – jedes Feld zählt einzeln, auch die Niederschlagsfenster rain_1h, rain_12h und rain_24h.

minimal bedeutet nicht, dass das Ergebnis falsch ist – aber die API hat mit sehr wenigen Datenpunkten gearbeitet und relevante Faktoren möglicherweise nicht berücksichtigt.

Macht transparent, auf welcher Datenbasis der index_score berechnet wurde:

• checks_used – Anzahl der tatsächlich eingeflossenen Checks.
• checks_total – Anzahl der insgesamt möglichen Checks (in der Regel 5).
• limiting_check – der limitierende, also schlechteste Check. Er bestimmt im Minimum-Modell den Minimum-Anteil des Gesamt-Indexwerts.

Liegt checks_used unter checks_total, wurden Checks mangels Daten übersprungen – der Wert ist trotzdem auf Basis der vorhandenen Checks korrekt.

Ein Array aller Eingabefelder, die im Request enthalten waren, gültige numerische Werte hatten und im definierten Gültigkeitsbereich lagen. Nur diese Felder haben tatsächlich in die Berechnung Einfluss genommen.

Beispiel: Wurde humidity: 150 übermittelt (außerhalb des Bereichs 0–100), erscheint humidity nicht in available_fields, sondern in missing_fields. Das ermöglicht es, Eingabefehler auf Clientseite zu erkennen und zu debuggen.

Das Gegenstück zu available_fields: Alle bekannten Felder, die entweder nicht übermittelt wurden, nicht-numerische Werte hatten oder außerhalb des Gültigkeitsbereichs lagen.

missing_fields enthält keine Fehleraussage über den Request – es ist eine Checkliste für die Vollständigkeit. Aus dieser Liste lässt sich direkt ableiten, welche Felder ergänzt werden könnten, um die data_quality zu verbessern und mehr Checks zu aktivieren.

Ein Diagnoseobjekt, das zusammenfasst, was während der Berechnung übersprungen oder nur teilweise ausgeführt wurde. Es enthält immer zwei Schlüssel:

• skipped_checksObject – Checks, die vollständig übersprungen wurden, weil ein benötigtes Feld fehlte. Key = Check-Name, Value = englischer Grund.
• partial_checksObject – Checks, bei denen einzelne Sub-Analysen nicht durchgeführt werden konnten, weil optionale Felder fehlten.

Optional: calculation_error – erscheint nur bei einem internen Berechnungsfehler.

"protocol": {
  "skipped_checks": {
    "soiltemp": "soil_temperature not provided",
    "wind":     "wind_speed not provided"
  },
  "partial_checks": {
    "humidity": {
      "dew_point_analysis": "dew_point not provided – dew point analysis skipped"
    }
  }
}

Erscheint, sobald mindestens eines der Niederschlagsfenster rain_1h, rain_12h oder rain_24h übermittelt wurde. Das Feld macht transparent, aus welchen Fenstern der Regen-Check seine Bewertung gebildet hat – je mehr Fenster, desto feiner die Auswertung.

• windows_used – die tatsächlich genutzten Niederschlagsfenster
• cumulative_source – das breiteste Fenster, das die kumulierte Bodenlast liefert
• not_provided – nicht übermittelte Fenster
• note – englischsprachiger Hinweis zur Auswertung

Wurde keines der drei Fenster übergeben, entfällt das Feld.

Der Zeitstempel, zu dem die Berechnung auf dem Server abgeschlossen wurde – im Format 2025-06-15 14:32:10. Es handelt sich um die Serverzeit. Kann für Logging, Caching oder zur Nachvollziehbarkeit von Ergebnissen verwendet werden.

Bei normaler API-Latenz liegt zwischen Request-Eingang und calculated_at typischerweise weniger als eine Sekunde.