Istraživački API /api/v1

Čitanje podataka situacionog centra za završne radove, istraživanje i skripte nadležnih službi: detekcije aktivnih požara (NASA FIRMS/GWIS), opožarene površine (EFFIS), opasnost od požara (FWI) i mreža zemaljskih senzora kao sirovi nizovi.

Pristup i ključevi

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

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

Authorization: Bearer ffw_YOUR_KEY

401 znači: nema ključa ili je nepoznat. Pribavite pristup. 403 znači: ključ je poznat, ali blokiran ili istekao. Javite se operateru. Prazan rezultat uz HTTP 200, nasuprot tome, znači: provjereno, nema podataka.

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

Endpointi

Pet podatkovnih endpointa, svi uz ključ, svi u GeoJSON i CSV formatu:

GET /api/v1/hotspots: Detekcije aktivnih požara s punim sirovim kolonama izvora (temperature sjaja, dimenzije piksela, FRP, oznaka proizvoda). Detekcije su pikseli, ne broj požara.
GET /api/v1/burnt-areas: Perimetri opožarenih površina iz EFFIS-a sa svim atributima. Geometrija u GeoJSON varijanti; CSV varijanta je tabela atributa.
GET /api/v1/fire-danger: Opasnost od požara kao vremenski niz sa svim podindeksima kanadskog FWI sistema (FFMC, DMC, DC, ISI, BUI). Tačno jedan model po odgovoru; referentne nivoe country i adminArea nikada ne miješati.
GET /api/v1/sensor-stations: Registar stanica 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 (kasnije verzionisani) korekcijski sloj.

Kompletan mašinski čitljiv ugovor dostupan je kao OpenAPI 3.0 dokument na GET /api/v1/docs i učitava se direktno u Swagger UI ili Postman.

Formati i vremenski prozori

Svaki endpoint vraća GeoJSON (RFC 7946, s dodatnim meta blokom) i, uz ?format=csv, CSV varijantu: odvojenu zarezima, s jednim redom zaglavlja, UTF-8. Bez dodatnih opcija čitaju je pandas.read_csv i readr::read_csv.

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

Svaki JSON odgovor nosi meta.observation: da li je lanac podataka uopšte radio i koliko je star njegov zadnji uspjeh. Prazna kolekcija znači „posmatrano, ništa nije nađeno“; HTTP 503 znači „nije provjereno“. Ove dvije izjave nikada ne izjednačavati.

Reproducibilnost: obaveze verzije v1

Dio putanje /v1 je obećanje stabilnosti tekućim radovima: unutar v1 polja, parametri, enum vrijednosti i kodovi grešaka nikada se ne uklanjaju, ne preimenuju i ne mijenjaju značenje. Proširenja su isključivo aditivna. Prekid bi značio /v2, uz dokumentovan prelazni period za v1.

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

Senzorska mreža sadrži simulirane demo stanice. Svaka stanica i svaki mjerni red zato nose polje simulated; analize ga filtriraju kao prvi korak. Simulirani nizovi ne ulaze ni u jedan citabilan skup podataka.

?series=raw vraća nedodirljivi sirovi niz. ?series=corrected je korekcijski sloj: trenutno vraća iste sirove vrijednosti, ali s correctionModel: null, „nijedna korekcija nije primijenjena“ kao citabilna izjava. Kada serverski, verzionisani korekcijski modeli (vlažnosni bias, kolokacijski faktori) budu dograđeni, correctionModel će nositi oznaku modela bez ikakve promjene oblika odgovora.

Primjeri

Primjeri namjerno nisu prevedeni; HOST zamijenite adresom instalacije.

Preuzimanje 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