Истраживачки API /апи/v1

Приступ читању података оперативног центра за завршне радове, истраживање и скрипте надлежних служби: детекције активних пожара (NASA FIRMS/GWIS), опожарене површине (EFFIS), опасност од пожара (FWI) и мрежа земаљских сензора као сирови низови.

Приступ и кључеви

Кључеве издаје оператер (samoLabs): захтев са именом, установом и сврхом употребе на info@samolabs.de. Истраживачки кључеви су бесплатни и временски ограничени; сваки кључ важи за једну особу или један систем.

Сваки захтев за подацима носи кључ као Bearer токен у Authorization заглављу:

Authorization: Bearer ffw_YOUR_KEY

401 значи: нема кључа или је непознат. Прибавите приступ. 403 значи: кључ је познат, али је блокиран или истекао. Јавите се оператеру. Празан резултат уз HTTP 200, насупрот томе, значи: проверено, нема ничега.

Важи ограничење од 120 захтева у минути по кључу. Код 429 поштујте Retry-After заглавље.

Ендпоинти

Пет ендпоинта са подацима, сви уз кључ, сви у GeoJSON и CSV формату:

GET /api/v1/hotspots: Детекције активних пожара са пуним сировим колонама извора (температуре сјаја, димензије пиксела, FRP, ознака производа). Детекције су пиксели, а не број пожара.
GET /api/v1/burnt-areas: Периметри опожарених површина из EFFIS-a са свим описним атрибутима. Геометрија је у GeoJSON верзији; CSV верзија је припадајућа атрибутска табела.
GET /api/v1/fire-danger: Опасност од пожара као временски низ са свим подиндексима канадског FWI система (FFMC, DMC, DC, ISI, BUI). Тачно један модел по одговору; референтне нивое country и adminArea никада не мешати.
GET /api/v1/sensor-stations: Регистар станица мреже земаљских сензора: матични подаци уз мерне низове, укључујући ознаку simulated.
GET /api/v1/sensor-readings: Мерни низови сензорске мреже као недодирљиве сирове вредности у 10-минутном такту; ?series=corrected враћа (убудуће верзионисани) корекциони слој.

Потпун, машински читљив уговор доступан је као OpenAPI 3.0 документ на GET /api/v1/docs и може се директно учитати у Swagger UI или Postman.

Формати и временски прозори

Сваки ендпоинт враћа GeoJSON (RFC 7946, са додатним мета блоком), а уз ?format=csv и CSV верзију: одвојену зарезима, са једним редом заглавља, UTF-8. Без додатних опција читају је pandas.read_csv и readr::read_csv.

Временски прозор долази из ?from и ?to (ISO 8601; сам датум важи као поноћ по UTC-у). За репродуцибилне изводе увек наведите обе границе. Стварно коришћени прозор стоји у meta.window. Ако meta.truncated јави скраћивање, сузите прозор; параметра offset намерно нема.

Сваки JSON одговор носи meta.observation: да ли је ланац података који га храни уопште радио и колико је стар његов последњи успех. Празна збирка значи „осматрано, ништа није пронађено“; HTTP 503 значи „није проверено“. Те две тврдње никада не изједначавати.

Репродуцибилност: обавезе верзије v1

Део путање /v1 је обавеза стабилности према радовима који су у току: унутар v1 поља, параметри, enum вредности и кодови грешака никада се не уклањају, не преименују нити им се мења значење. Проширења су искључиво адитивна. Прекид би значио /v2, уз документован прелазни период за v1.

Сви временски печати су ISO 8601 у UTC-у. Истраживачки подаци никада не прелазе у приказну временску зону. Локално време интерфејса је само приказ.

Сензорска мрежа садржи симулиране демо станице. Свака станица и сваки мерни ред зато носе поље simulated; анализе га филтрирају као први корак. Симулирани низови не појављују се ни у једном скупу података погодном за цитирање.

?series=raw враћа недодирљив сирови низ. ?series=corrected је корекциони слој: тренутно враћа исте сирове вредности, али са correctionModel: null, „ниједна корекција није примењена“ као изјаву која се може цитирати. Када се накнадно уграде серверски, верзионисани модели корекције (биас влаге, фактори колокације), correctionModel ће носити ознаку модела, а да се облик одговора притом не мења.

Примери

Примери намерно нису преведени; HOST замените адресом инсталације.

Преузимање уз 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