← Dokumentation Übersicht

Endpoint: /v1/calculate

Der zentrale Berechnungs-Endpoint der Mähbarkeitsindex (MFI) API. Wetterdaten senden, Gesamt-Indexwert, Gesamt-Status und detaillierte Check-Ergebnisse zurückerhalten.

Übersicht

Endpoint-Details

POST /v1/calculate GET – nur auf Anfrage Auth erforderlich

URL

https://api.maehbarkeitsindex.de/
v1/calculate

Erlaubte Methoden

POST

GET nur auf Anfrage für Testzwecke

Authentifizierung

API-Key (Bearer Token)

Content-Type (POST)

application/json

oder application/x-www-form-urlencoded

Partielle Eingaben erlaubt

Nicht alle Parameter müssen übermittelt werden. Die API berechnet den MFI mit den vorhandenen Daten. Fehlende optionale Felder werden in der Antwort unter missing_fields aufgeführt. Nur temperature und precipitation_rate stellen die Mindestanforderungen da.

Wichtig: GET-Methode

Die GET-Methode steht standardmäßig nicht zur Verfügung. API-Keys sind auf POST beschränkt. GET kann ausschließlich auf ausdrückliche Anfrage für Testzwecke freigeschaltet werden und ist nicht für den Produktionsbetrieb vorgesehen.

Parameter

Eingabeparameter

Alle Parameter sind vom Typ float. Werte außerhalb der angegebenen Gültigkeitsbereiche werden stillschweigend ignoriert – kein Fehler, das Feld gilt als nicht geliefert.

Pflichtfelder

Feld	Einheit	Gültiger Bereich	Beschreibung
temperature	°C	−60 … 60	Aktuelle Lufttemperatur
precipitation_rate	mm/h	0 … 500	Aktuelle Niederschlagsrate.

Optionale Felder – Aktuelle Wetterdaten

Feld	Einheit	Gültiger Bereich	Beschreibung
humidity	%	0 … 100	Relative Luftfeuchtigkeit. Aktiviert den Humidity-Check.
wind_speed	km/h	0 … 300	Windgeschwindigkeit
wind_gusts	km/h	0 … 400	Windböen. Verbessert den Wind-Check.
dew_point	°C	−60 … 60	Taupunkt. Verbessert den Humidity-Check (Taubildungsrisiko-Prüfung).
solar	W/m²	0 … 2000	Aktuelle Sonneneinstrahlung
soil_temperature	°C	−30 … 70	Bodentemperatur. Aktiviert den SoilTemp-Check.
soil_moisture	%	0 … 100	Bodenfeuchtigkeit. Fließt in Tragfähigkeitsbewertung ein.

Optionale Felder – Historische Niederschlagsdaten

Die Übermittlung von Niederschlagsdaten ist optional. Sind die entsprechenden Werte jedoch verfügbar, wird empfohlen, alle unterstützten Niederschlagsfelder an die API zu übergeben. Der Mähbarkeitsindex verwendet diese Daten in verschiedenen Prüfungen und Bewertungsverfahren, wodurch eine präzisere und umfassendere Analyse möglich wird.

Werden nur einzelne Niederschlagsfelder bereitgestellt, nutzt der MFI automatisch die jeweils präziseste verfügbare Angabe für die entsprechenden Berechnungen. Prüfungen, die auf nicht übermittelten Niederschlagswerten basieren, können in diesem Fall jedoch nicht oder nur eingeschränkt durchgeführt werden. Für die bestmögliche Auswertung sowie eine optimale Unterstützung zukünftiger Weiterentwicklungen empfiehlt es sich daher, sofern vorhanden, sämtliche verfügbaren Niederschlagsdaten zu übermitteln.

Feld	Einheit	Gültiger Bereich	Beschreibung
rain_1h	mm	0 … 500	Niederschlag letzte 1 Stunde
rain_12h	mm	0 … 2000	Niederschlag letzte 12 Stunden
rain_24h	mm	0 … 2000	Niederschlag letzte 24 Stunden
rain_14d	mm	0 … 5000	Niederschlagssumme letzte 14 Tage
minutes_since_rain	min	0 … 99999	Minuten seit dem letzten Niederschlagsereignis

Optionale Felder – Historische Temperaturdaten

Historische Mindesttemperaturen verbessern die Frost- und Bodenanalyse im Temperature- & SoilTemp-Check erheblich.

Feld	Einheit	Gültiger Bereich	Beschreibung
min_temp_3h	°C	−60 … 60	Mindesttemperatur letzte 3 Stunden
min_temp_3d	°C	−60 … 60	Mindesttemperatur letzte 3 Tage
min_temp_14d	°C	−60 … 60	Mindesttemperatur letzte 14 Tage

Requests

Request-Beispiele

Minimaler POST-Request (Pflichtfelder)

curl – POST JSON

curl -X POST https://api.maehbarkeitsindex.de/v1/calculate \
  -H "Authorization: Bearer DEIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "temperature": 18.5,
    "precipitation_rate": 0.0
  }'

Erweiterter POST-Request (alle optionalen Felder)

curl – POST JSON mit allen optionalen Feldern

curl -X POST https://api.maehbarkeitsindex.de/v1/calculate \
  -H "Authorization: Bearer DEIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "temperature":        22.5,
    "precipitation_rate": 0.0,
    "humidity":           72.0,
    "wind_speed":         12.0,
    "wind_gusts":         18.0,
    "dew_point":          12.3,
    "solar":              480.0,
    "soil_temperature":   14.0,
    "soil_moisture":      48.0,
    "rain_1h":            0.2,
    "rain_12h":           1.1,
    "rain_24h":           1.8,
    "rain_14d":           22.5,
    "minutes_since_rain": 45,
    "min_temp_3h":        19.5,
    "min_temp_3d":        8.5,
    "min_temp_14d":       4.0
  }'

GET-Request

curl – GET mit URL-Parametern

curl "https://api.maehbarkeitsindex.de/v1/calculate\
?temperature=22.5\
&precipitation_rate=0.0\
&humidity=72.0\
&wind_speed=12.0\
&api_key=DEIN_API_KEY"

Antwort

Antwortstruktur

Bei erfolgreicher Berechnung antwortet die API mit HTTP-Statuscode 200. Das mfi-Objekt enthält alle Berechnungsergebnisse sowie Meta-Informationen zum Verarbeitungsprozess.

Top-Level Felder im mfi-Objekt

Feld	Typ	Beschreibung
mfi_version	string	Verwendete Version der Berechnungslogik
season	string	Erkannte Jahreszeit: `spring \| summer \| autumn \| winter`
season_source	string	Herkunft der verwendeten Jahreszeit: `auto` (automatisch aus dem Server-Monat) oder `manual` (per `season` erzwungen, nur im Debug-/Testkontext). Im Normalbetrieb stets `auto`.
index_score	int	MFI Gesamt-Indexwert 0–100. Je höher, desto besser die Mähbedingungen.
main_status	string	`OK` (≥70) \| `WARNING` (40–69) \| `BLOCK` (<40)
data_quality	string	Datenlage: `full \| partial \| minimal`
score_basis	object	Transparenz zur Datenbasis des Gesamt-Indexwerts: `checks_used` (Anzahl eingeflossener Checks), `checks_total` (Anzahl möglicher Checks) und `limiting_check` (limitierender, schlechtester Check – dominiert im Minimum-Modell den Gesamt-Indexwert).
available_fields	array	Liste der empfangenen und validen Eingabefelder
missing_fields	array	Liste nicht übermittelter oder ungültiger Felder
checks	object	Ergebnisse der einzelnen Bewertungsmodelle (siehe unten)
protocol	object	Diagnoseobjekt zum Berechnungsablauf mit den Schlüsseln `skipped_checks` (vollständig übersprungene Checks) und `partial_checks` (Checks mit ausgelassenen Teilanalysen). Bei einem internen Berechnungsfehler zusätzlich der Schlüssel `calculation_error`.
rain_source_info	object	Nur vorhanden, wenn mindestens eines der Felder `rain_1h`, `rain_12h` oder `rain_24h` übermittelt wurde. Dokumentiert die genutzten Niederschlagsfenster (`windows_used`), das Fenster für die kumulierte Bodenlast (`cumulative_source`) und die nicht übermittelten Fenster (`not_provided`).
calculated_at	string	Zeitstempel der Berechnung (Y-m-d H:i:s)

Checks-Objekt

Das checks-Objekt enthält bis zu fünf Bewertungsmodelle: temperature, soiltemp, rain, wind, humidity. Jeder Check hat diese Felder:

Feld	Typ	Beschreibung
executed	bool	`false`, wenn erforderliche Eingabedaten fehlten und der Check übersprungen wurde
skipped_reason	string\|null	Nur bei `executed: false` enthalten – englischsprachiger Grund, warum der Check übersprungen wurde. Bei ausgeführten Checks ist dieses Feld nicht Teil der Antwort.
status	string\|null	`OK \| WARNING \| BLOCK` – oder `null` wenn übersprungen
score	int\|null	Check-interner Score 0–100
data_confidence	string\|null	Datenbasis des Checks: `high \| medium` (beim Regen-Check zusätzlich `low`), oder `null`, wenn der Check übersprungen wurde.
reasons	array	Deutschsprachige Begründungstexte für den Check-Status; können einfache HTML-Auszeichnungen wie `<b>` oder `<br>` enthalten
skipped_parts	object	Teilauswertungen, die mangels Daten nicht berechnet werden konnten
meta	object	Interne Berechnungsdaten und verwendete Eingabewerte des Checks

Vollständiges Antwortbeispiel

JSON – HTTP 200 Erfolgsantwort (gekürzt)

{
  "status": "ok",
  "mfi": {
    "mfi_version":      "1.0",
    "season":           "summer",
    "season_source":    "auto",
    "index_score":      95,
    "main_status":      "OK",
    "data_quality":     "full",
    "score_basis": {
      "checks_used":    5,
      "checks_total":   5,
      "limiting_check": "wind"
    },
    "available_fields": ["temperature", "precipitation_rate", "humidity", "wind_speed",
                         "wind_gusts", "dew_point", "solar", "soil_temperature",
                         "soil_moisture", "rain_1h", "rain_12h", "rain_24h", "rain_14d",
                         "minutes_since_rain", "min_temp_14d", "min_temp_3d", "min_temp_3h"],
    "missing_fields":   [],
    "protocol": {
      "skipped_checks": {},
      "partial_checks": {}
    },
    "checks": {
      "temperature": {
        "executed":        true,
        "status":          "OK",
        "score":           100,
        "data_confidence": "high",
        "reasons":         ["Temperatur-Check (Sommer): 22,0 °C – Temperatur im günstigen Bereich für den Rasenschnitt."],
        "skipped_parts":   {},
        "meta": { "temperature": 22.0, "season": "summer", "min_temp_14d": 12.0, "growth_phase_stable": true }
      },
      "soiltemp": {
        "executed":        true,
        "status":          "OK",
        "score":           97,
        "data_confidence": "high",
        "reasons":         ["Boden-Check (Sommer): 19,0 °C – Bodentemperatur im günstigen Bereich für Wurzelaktivität und Regeneration."],
        "skipped_parts":   {},
        "meta": { "soil_temp": 19.0, "season": "summer", "soil_moisture": 45.0, "soil_moisture_load_class": "low" }
      },
      "rain": {
        "executed":        true,
        "status":          "OK",
        "score":           100,
        "data_confidence": "high",
        "reasons":         ["Regen-Check (Sommer): 0,0 mm (letzte 24h) – aktuell stabile Bodenverhältnisse."],
        "skipped_parts":   {},
        "meta": {
          "rain_source":      "rain_24h",
          "rain_cumulative":  0.0,
          "rain_rate":        0.0,
          "soil_load":        0.0,
          "limiting_factor":  "soil",
          "season":           "summer",
          "models_executed":  ["dry_down", "sml", "residual_moisture"]
        }
      },
      "wind": {
        "executed":        true,
        "status":          "OK",
        "score":           92,
        "data_confidence": "high",
        "reasons":         ["Wind-Check (Sommer): 6,0 km/h – aktuell stabile Windverhältnisse."],
        "skipped_parts":   {},
        "meta": { "wind": 6.0, "gust": 10.0, "season": "summer" }
      },
      "humidity": {
        "executed":        true,
        "status":          "OK",
        "score":           96,
        "data_confidence": "high",
        "reasons":         ["Luftfeuchte-Check (Sommer): 55 % bei 22,0 °C – aktuell unkritische Feuchtebedingungen."],
        "skipped_parts":   {},
        "meta": { "humidity": 55.0, "temperature": 22.0, "season": "summer", "dew_point_depression": 10.0, "drying_potential": 1.0 }
      }
    },
    "rain_source_info": {
      "windows_used":      ["rain_1h", "rain_12h", "rain_24h"],
      "cumulative_source": "rain_24h",
      "not_provided":      [],
      "note":              "All provided rolling windows are combined: the broadest window provides the cumulative soil load, while the differences between windows form time slices for surface moisture. More windows yield finer slices and a more precise assessment."
    },
    "calculated_at": "2025-06-15 14:32:10"
  },
  "message": ""
}

Weiter in der Dokumentation

Implementierungstipps →

Wartungsmodus, Mähsaison und Darstellung des MFI

Authentifizierung →

API-Key Nutzung und Sicherheit

Endpoint /health →

API-Status und Verfügbarkeit prüfen

Regeln & Rate Limits →

Limits, Fehlercodes und API-Richtlinien

API Changelog →

Änderungen, Releases und Breaking Changes

MFI API Tester →

API direkt im Browser testen

API FAQ & Begriffe →

Erklärung von Datenfeldern, Statuswerten, Checks und Modellkennzahlen

Fragen, Probleme oder Feedback?

Bei Fragen zur API, technischen Problemen, gefundenen Fehlern oder Verbesserungsvorschlägen – einfach Kontakt aufnehmen.

Kontakt aufnehmen →