Forschungs-API /api/v1

Zugang und Schlüssel

Schlüssel gibt der Betreiber (samoLabs) aus — Anfrage mit Name, Einrichtung und Verwendungszweck an info@samolabs.de. Forschungsschlüssel sind kostenlos und befristet; jeder Schlüssel gilt für eine Person oder ein System.

Jede Datenanfrage trägt den Schlüssel als Bearer-Token im Authorization-Kopf:

Authorization: Bearer ffw_YOUR_KEY

401 heißt: kein oder unbekannter Schlüssel — Zugang beschaffen. 403 heißt: Schlüssel bekannt, aber gesperrt oder abgelaufen — beim Betreiber melden. Ein leeres Ergebnis mit HTTP 200 heißt dagegen: nachgesehen, nichts da.

Es gelten 120 Anfragen je Minute und Schlüssel. Bei 429 den Retry-After-Kopf beachten.

Endpunkte

Fünf Datenendpunkte, alle mit Schlüssel, alle in GeoJSON und CSV:

GET /api/v1/hotspots

Aktivfeuer-Detektionen mit den vollen Rohspalten der Quelle (Helligkeitstemperaturen, Pixelmaße, FRP, Produktkennung). Detektionen sind Pixel, keine Brandzahlen.

GET /api/v1/burnt-areas

Brandflächen-Perimeter aus EFFIS mit allen Sachattributen. Geometrie in der GeoJSON-Fassung; die CSV-Fassung ist die Sachtabelle dazu.

GET /api/v1/fire-danger

Brandgefahr als Zeitreihe mit allen Teilindizes des kanadischen FWI-Systems (FFMC, DMC, DC, ISI, BUI). Je Antwort genau ein Modell; die Bezugsebenen country und adminArea nie mischen.

GET /api/v1/sensor-stations

Stationsverzeichnis des Bodensensornetzes — die Stammdaten zu den Messreihen, inklusive simulated-Kennzeichen.

GET /api/v1/sensor-readings

Messreihen des Sensornetzes als unantastbare Rohwerte im 10-Minuten-Takt; ?series=corrected liefert die (künftig versionierte) Korrekturebene.

Der vollständige, maschinenlesbare Vertrag steht als OpenAPI-3.0-Dokument unter GET /api/v1/docs und lässt sich direkt in Swagger UI oder Postman laden.

Formate und Zeitfenster

Jeder Endpunkt liefert GeoJSON (RFC 7946, mit zusätzlichem meta-Block) und mit ?format=csv eine CSV-Fassung: Komma-getrennt, eine Kopfzeile, UTF-8 — pandas.read_csv und readr::read_csv lesen sie ohne Zusatzoptionen.

Das Zeitfenster kommt aus ?from und ?to (ISO 8601; ein reines Datum gilt als UTC-Mitternacht). Für reproduzierbare Abzüge immer beide Grenzen angeben — das tatsächlich verwendete Fenster steht in meta.window. Meldet meta.truncated eine Kürzung, das Fenster verkleinern; einen Offset-Parameter gibt es bewusst nicht.

Jede JSON-Antwort trägt meta.observation: ob die speisende Datenkette überhaupt lief und wie alt ihr letzter Erfolg ist. Eine leere Sammlung heißt „beobachtet, nichts gefunden“; HTTP 503 heißt „nicht nachgesehen“. Die beiden Aussagen nie gleichsetzen.

Reproduzierbarkeit — die Zusagen von v1

Der Pfadbestandteil /v1 ist eine Stabilitätszusage an laufende Arbeiten: Felder, Parameter, Enum-Werte und Fehlercodes werden innerhalb von v1 nie entfernt, nie umbenannt und nie umgedeutet — Erweiterungen sind ausschließlich additiv. Ein Bruch bedeutete /v2, mit dokumentierter Übergangszeit für v1.

Alle Zeitstempel sind ISO 8601 in UTC. Forschungsdaten wechseln nie in eine Anzeige-Zeitzone — die Ortszeit der Oberfläche ist reine Darstellung.

Das Sensornetz enthält simulierte Demo-Stationen. Jede Station und jede Messzeile trägt deshalb das Feld simulated; Auswertungen filtern es als ersten Schritt. Simulierte Reihen erscheinen in keinem zitierfähigen Datensatz.

?series=raw liefert die unantastbare Rohreihe. ?series=corrected ist die Korrekturebene: Sie liefert derzeit dieselben Rohwerte, aber mit correctionModel: null — „keine Korrektur angewandt“ als zitierbare Aussage. Sobald serverseitige, versionierte Korrekturmodelle (Feuchte-Bias, Co-Location-Faktoren) nachgerüstet sind, trägt correctionModel die Modellkennung, ohne dass sich die Antwortform ändert.

Beispiele

Die Beispiele sind bewusst nicht übersetzt; HOST durch die Adresse der Installation ersetzen.

Abruf mit curl

curl -H "Authorization: Bearer ffw_YOUR_KEY" \
  "https://HOST/api/v1/hotspots?from=2026-07-01&to=2026-08-01&country=BA&format=csv" \
  -o hotspots_ba_2026-07.csv

Python (pandas)

import io
import requests
import pandas as pd

resp = requests.get(
    "https://HOST/api/v1/sensor-readings",
    params={"from": "2026-06-01", "to": "2026-07-01",
            "series": "raw", "format": "csv"},
    headers={"Authorization": "Bearer ffw_YOUR_KEY"},
    timeout=60,
)
resp.raise_for_status()

df = pd.read_csv(io.StringIO(resp.text), parse_dates=["measuredAtUtc"])
df = df[~df["simulated"]]  # always drop simulated demo stations

R (httr2 + readr)

library(httr2)
library(readr)

resp <- request("https://HOST/api/v1/fire-danger") |>
  req_url_query(model = "effis", from = "2026-06-01",
                to = "2026-08-01", format = "csv") |>
  req_auth_bearer_token("ffw_YOUR_KEY") |>
  req_perform()

danger <- read_csv(resp_body_string(resp))
danger <- subset(danger, level == "adminArea")  # never mix reference levels