Istraživački API /api/v1

Pristup i ključevi

Ključeve izdaje operator (samoLabs): zahtjev s imenom, ustanovom i svrhom uporabe na info@samolabs.de. Istraživački ključevi su besplatni i vremenski ograničeni; svaki ključ vrijedi za jednu osobu ili jedan sustav.

Svaki zahtjev za podacima nosi ključ kao Bearer token u zaglavlju Authorization:

Authorization: Bearer ffw_YOUR_KEY

401 znači: nema ključa ili je nepoznat. Pribavite pristup. 403 znači: ključ je poznat, ali je blokiran ili istekao. Javite se operatoru. Prazan rezultat uz HTTP 200 znači, naprotiv: provjereno, nema ničega.

Vrijedi ograničenje od 120 zahtjeva u minuti po ključu. Kod 429 poštujte zaglavlje Retry-After.

Krajnje točke

Pet krajnjih točaka s podacima, sve uz ključ, sve u formatu GeoJSON i CSV:

GET /api/v1/hotspots

Detekcije aktivnih požara s punim sirovim stupcima izvora (temperature sjaja, dimenzije piksela, FRP, oznaka proizvoda). Detekcije su pikseli, a ne broj požara.

GET /api/v1/burnt-areas

Perimetri opožarenih površina iz EFFIS-a sa svim opisnim atributima. Geometrija je u GeoJSON inačici; CSV inačica je pripadajuća atributna tablica.

GET /api/v1/fire-danger

Opasnost od požara kao vremenski niz sa svim podindeksima kanadskog sustava FWI (FFMC, DMC, DC, ISI, BUI). Točno jedan model po odgovoru; referentne razine country i adminArea nikada ne miješati.

GET /api/v1/sensor-stations

Popis postaja mreže zemaljskih senzora: matični podaci uz mjerne nizove, uključujući oznaku simulated.

GET /api/v1/sensor-readings

Mjerni nizovi senzorske mreže kao nedodirljive sirove vrijednosti u 10-minutnom taktu; ?series=corrected vraća (ubuduće verzionirani) korekcijski sloj.

Potpuni, strojno čitljiv ugovor dostupan je kao dokument OpenAPI 3.0 na GET /api/v1/docs i može se izravno učitati u Swagger UI ili Postman.

Formati i vremenski prozori

Svaka krajnja točka vraća GeoJSON (RFC 7946, s dodatnim meta blokom), a uz ?format=csv i CSV inačicu: odvojenu zarezima, s jednim retkom zaglavlja, UTF-8. Bez dodatnih postavki čitaju je pandas.read_csv i readr::read_csv.

Vremenski prozor dolazi iz ?from i ?to (ISO 8601; sam datum vrijedi kao ponoć po UTC-u). Za ponovljive izvatke uvijek navedite obje granice. Stvarno korišteni prozor stoji u meta.window. Ako meta.truncated javi skraćivanje, suzite prozor; parametra offset namjerno nema.

Svaki JSON odgovor nosi meta.observation: je li lanac podataka koji ga hrani uopće radio i koliko je star njegov posljednji uspjeh. Prazna zbirka znači „motreno, ništa nije pronađeno“; HTTP 503 znači „nije provjereno“. Te dvije tvrdnje nikada ne izjednačavati.

Ponovljivost: obveze verzije v1

Dio putanje /v1 obveza je stabilnosti prema radovima koji su u tijeku: unutar v1 polja, parametri, enum vrijednosti i kodovi pogrešaka nikada se ne uklanjaju, ne preimenuju niti im se mijenja značenje. Proširenja su isključivo aditivna. Prekid bi značio /v2, uz dokumentirano prijelazno razdoblje za v1.

Svi vremenski žigovi su ISO 8601 u UTC-u. Istraživački podaci nikada ne prelaze u prikaznu vremensku zonu. Lokalno vrijeme sučelja samo je prikaz.

Senzorska mreža sadrži simulirane demo postaje. Svaka postaja i svaki mjerni redak zato nose polje simulated; analize ga filtriraju kao prvi korak. Simulirani nizovi ne pojavljuju se ni u jednom skupu podataka prikladnom za citiranje.

?series=raw vraća nedodirljiv sirovi niz. ?series=corrected je korekcijski sloj: trenutačno vraća iste sirove vrijednosti, ali s correctionModel: null, „nijedna korekcija nije primijenjena“ kao tvrdnju koja se može citirati. Kada se naknadno ugrade serverski, verzionirani modeli korekcije (bias vlage, čimbenici kolokacije), correctionModel će nositi oznaku modela, a da se oblik odgovora pritom ne mijenja.

Primjeri

Primjeri namjerno nisu prevedeni; HOST zamijenite adresom instalacije.

Dohvat uz 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