API Документација

Потврђује да је процес жив и да HTTP сервер прихвата везе. Овај ендпоинт не изводи никакав I/O и увек враћа 200 OK док год процес ради. Користите као пробу живости контејнера.

Одговори

Примери кода

curl -s http://opendata.kosava.cloud/health/live

import requests

resp = requests.get("http://opendata.kosava.cloud/health/live")
print(resp.json())
# {"status": "ok", "check": "live"}

const resp = await fetch("http://opendata.kosava.cloud/health/live");
const data = await resp.json();
console.log(data);
// { status: "ok", check: "live" }

Проверава да ли је Redis конекција исправна и да ли верзија активног снимка одговара EXPECTED_SCHEMA_VERSION. Враћа 200 са snapshot_id када је спреман. Враћа 503 када Redis није доступан, показивач снимка недостаје или верзија шеме није компатибилна. Користите као пробу спремности контејнера и здравствену капију баласера оптерећења.

Одговори

Примери кода

curl -s http://opendata.kosava.cloud/health/ready

import requests

resp = requests.get("http://opendata.kosava.cloud/health/ready")
if resp.status_code == 200:
    print("Ready:", resp.json()["snapshot_id"])
else:
    print("Not ready:", resp.json()["detail"])

const resp = await fetch("http://opendata.kosava.cloud/health/ready");
const data = await resp.json();
if (resp.ok) console.log("Snapshot:", data.snapshot_id);
else console.error("Not ready:", data.detail);

Враћа манифест тренутно активног Redis снимка: временску ознаку генерисања, подржане прозоре мерења и агрегатне бројеве за организације, мреже, станице, компоненте и редове мерења. Користите supported_windows да сазнате које вредности прозора су важеће за упите мерења.

Одговори

Примери кода

curl -s http://opendata.kosava.cloud/meta | python3 -m json.tool

import requests

meta = requests.get("http://opendata.kosava.cloud/meta").json()
print("Snapshot:", meta["generated_at"])
print("Windows:", meta["supported_windows"])
print("Stations:", meta["counts"]["stations"])

const meta = await fetch("/meta").then(r => r.json());
console.log(meta.supported_windows); // ["1h","1d","7d","14d","30d"]
console.log(meta.counts.stations);   // 12

Враћа све организације у активном снимку. Пошто је једна инстанца портала везана за једну организацију путем KEY_PREFIX, ова листа обично садржи тачно један унос. Сваки објекат укључује organization_id, name и short_name.

Одговори

Примери кода

curl -s http://opendata.kosava.cloud/organizations

orgs = requests.get("http://opendata.kosava.cloud/organizations").json()
org_id = orgs[0]["organization_id"]  # typically 1 org

const orgs = await fetch("/organizations").then(r => r.json());
const orgId = orgs[0].organization_id;

Враћа све мреже за праћење дефинисане у активном снимку. Мреже групишу станице унутар именованог програма мерења или географског подручја. Сваки објекат укључује network_id, network_code, name и short_name.

Одговори

Примери кода

curl -s http://opendata.kosava.cloud/networks

networks = requests.get("http://opendata.kosava.cloud/networks").json()
for n in networks:
    print(n["network_code"], "-", n["name"])

const networks = await fetch("/networks").then(r => r.json());
networks.forEach(n => console.log(n.network_code, n.name));

Враћа све јавне станице за праћење у свим организацијама и мрежама у активном снимку. Сваки објекат укључује station_id, station_name, station_code, organization_id, network_id, network_code и географска поља као што су city и municipality где су доступна. За филтрирање по организацији користите GET /{organization_id}/stations.

Одговори

Примери кода

curl -s http://opendata.kosava.cloud/stations

stations = requests.get("http://opendata.kosava.cloud/stations").json()
for s in stations:
    print(s["station_id"], s["station_name"], s["city"])

const stations = await fetch("/stations").then(r => r.json());
console.log(`${stations.length} stations found`);

Враћа све компоненте мерења (загађивачи и метеоролошки параметри) дефинисане у активном снимку. Сваки објекат укључује component_id, short_name и unit. Овде се појављују само јавно видљиве компоненте. Метеоролошки параметри укључују брзину ветра, температуру, влажност и падавине; параметри загађења укључују честице (PM10, PM2.5) и гасовите загађиваче.

Одговори

Примери кода

curl -s http://opendata.kosava.cloud/components

components = requests.get("http://opendata.kosava.cloud/components").json()
pm10 = next(c for c in components if c["short_name"] == "PM10")
print(pm10["component_id"], pm10["unit"])  # 1001 ug/m3

const components = await fetch("/components").then(r => r.json());
const pm10 = components.find(c => c.short_name === "PM10");
console.log(pm10.component_id, pm10.unit);

Враћа све јавне станице за праћење за одређену организацију. Облик одговора је идентичан GET /stations, али филтриран по датом organization_id. Враћа 404 ако организација не постоји или нема јавних станица у активном снимку.

Параметри путање

Одговори

Примери кода

curl -s http://opendata.kosava.cloud/1/stations

org_id = 1
stations = requests.get(
    f"http://opendata.kosava.cloud/{org_id}/stations"
).json()
print(f"{len(stations)} stations in org {org_id}")

const orgId = 1;
const stations = await fetch(`/${orgId}/stations`).then(r => r.json());
console.log(`${stations.length} stations`);

Враћа детаљне метаподатке за једну станицу, укључујући листу јавних компоненти мерења (public_components) доступних за ту станицу. Сваки унос компоненте укључује component_id, short_name и unit. Ово је полазна тачка за откривање које компоненте могу бити упитане путем ендпоината мерења. Враћа 404 ако организација или станица не постоје у активном снимку.

Параметри путање

Одговори

Примери кода

curl -s http://opendata.kosava.cloud/1/stations/101/meta

meta = requests.get(
    "http://opendata.kosava.cloud/1/stations/101/meta"
).json()
for comp in meta["public_components"]:
    print(comp["component_id"], comp["short_name"], comp["unit"])

const meta = await fetch("/1/stations/101/meta").then(r => r.json());
meta.public_components.forEach(c =>
  console.log(c.component_id, c.short_name, c.unit)
);

Враћа нормализоване податке временских серија за једну компоненту на једној станици током траженог временског прозора. Сва четири параметра упита су обавезна. Одговор укључује назив станице, детаље компоненте, коришћени прозор и низ points сортиран узлазно по датуму и времену. Свака тачка има date (ГГГГ-ММ-ДД), time (ЧЧ:ММ) и нумеричку вредност value. Параметар window мора бити један од: 1h, 1d, 7d, 14d, 30d — и мора бити присутан у supported_windows снимка.

Параметри упита

Одговори

Примери кода

curl -s \
  "http://opendata.kosava.cloud/measurements?organization_id=1&station_id=101&component_id=1001&window=1d"

import requests

resp = requests.get(
    "http://opendata.kosava.cloud/measurements",
    params={
        "organization_id": 1,
        "station_id": 101,
        "component_id": 1001,
        "window": "1d",
    },
)
resp.raise_for_status()
data = resp.json()
print(f"{data['station_name']} — {data['component_short_name']} ({data['unit']})")
for pt in data["points"]:
    print(pt["date"], pt["time"], pt["value"])

const params = new URLSearchParams({
  organization_id: "1",
  station_id: "101",
  component_id: "1001",
  window: "1d",
});
const resp = await fetch(`/measurements?${params}`);
if (!resp.ok) throw new Error(await resp.text());
const data = await resp.json();
console.log(`${data.station_name} — ${data.component_short_name} (${data.unit})`);
data.points.forEach(pt => console.log(pt.date, pt.time, pt.value));

Враћа сва мерења компоненти забележена у последњем сату за одређену станицу. Тело одговора садржи низ hours где сваки унос има date (ISO-8601 стринг датума), time (ЧЧ:ММ) и листу components. Сваки унос компоненте укључује component_id и нумеричку вредност value. Враћа 404 ако станица не постоји или нема података за последњи сат.

Параметри путање

Одговори

Примери кода

curl -s http://opendata.kosava.cloud/1/stations/101/measurements/last_hour

data = requests.get(
    "http://opendata.kosava.cloud/1/stations/101/measurements/last_hour"
).json()
for hour in data["hours"]:
    print(hour["date"], hour["time"])
    for comp in hour["components"]:
        print("  component", comp["component_id"], "=", comp["value"])

const data = await fetch("/1/stations/101/measurements/last_hour")
  .then(r => r.json());
data.hours.forEach(hour => {
  console.log(hour.date, hour.time);
  hour.components.forEach(c => console.log(" component", c.component_id, "=", c.value));
});

Враћа сва мерења компоненти забележена током последњих 24 сата за одређену станицу. Структура тела идентична је last_hour: низ hours где сваки унос има date, time и components. Све јавно изложене компоненте станице су укључене у сваки сатни унос где постоје подаци. Враћа 404 ако станица не постоји или нема података за последњих 24 сата.

Параметри путање

Одговори

Примери кода

curl -s http://opendata.kosava.cloud/1/stations/101/measurements/last_24h

data = requests.get(
    "http://opendata.kosava.cloud/1/stations/101/measurements/last_24h"
).json()
print(f"{len(data['hours'])} hours of data")

const data = await fetch("/1/stations/101/measurements/last_24h")
  .then(r => r.json());
console.log(`${data.hours.length} hours of data`);

Гради и стримује датотеку табеле за преузимање која садржи податке временских серија мерења за једну компоненту наједној станици. Свих пет параметара упита је обавезно. Прозор 1h није подржан за извоз. Извезена датотека садржи један ред по тачки мерења са колонама: organization_id, organization_name, station_id, station_name, station_code, network_id, network_code, date, time, component_id, component_short_name, unit, value. Нумеричке вредности су форматиране на две децимале.

Параметри упита

Одговори

Примери кода

# Download as CSV
curl -OJ \
  "http://opendata.kosava.cloud/portal/export?organization_id=1&station_id=101&component_id=1001&window=7d&format=csv"

# Download as XLSX
curl -OJ \
  "http://opendata.kosava.cloud/portal/export?organization_id=1&station_id=101&component_id=1001&window=7d&format=xlsx"

import requests, re

resp = requests.get(
    "http://opendata.kosava.cloud/portal/export",
    params={
        "organization_id": 1,
        "station_id": 101,
        "component_id": 1001,
        "window": "7d",
        "format": "csv",
    },
)
resp.raise_for_status()

# Extract filename from Content-Disposition header
cd = resp.headers.get("Content-Disposition", "")
m = re.search(r'filename="(.+?)"', cd)
filename = m.group(1) if m else "export.csv"

with open(filename, "wb") as f:
    f.write(resp.content)
print(f"Saved: {filename}")

const params = new URLSearchParams({
  organization_id: "1", station_id: "101",
  component_id: "1001", window: "7d", format: "csv",
});
const resp = await fetch(`/portal/export?${params}`);
if (!resp.ok) throw new Error(await resp.text());

const blob = await resp.blob();
const cd = resp.headers.get("content-disposition") ?? "";
const filename = (cd.match(/filename="(.+?)"/) ?? [])[1] ?? "export.csv";

// Trigger browser download
const a = document.createElement("a");
a.href = URL.createObjectURL(blob);
a.download = filename;
a.click();

Враћа комплетан HVD дескриптор: schema_version, dataset_version, snapshot_id, retention_days, декларисани data_status (preliminary), aggregation_type (hourly_mean), supported_windows, applicable_legislation (ELI линк на 2023/138), лиценцу, и линкове на правне странице (license, terms, qos, contact, dataset) и документацију (docs, redoc, openapi). Погодно за harvester-е и клијентске интеграционе провере.

Одговори

Примери кода

curl -s http://opendata.kosava.cloud/api/v1/metadata | python3 -m json.tool

import requests
m = requests.get("http://opendata.kosava.cloud/api/v1/metadata").json()
print(m["data_status"], m["retention_days"])
print(m["applicable_legislation"])

const meta = await fetch("/api/v1/metadata").then(r => r.json());
console.log(meta.license, meta.retention_days);

Враћа све monitoring станице у HVD облику (Компонента A стандарда). Свака станица носи station_id (string), station_name, latitude/longitude, municipality, station_type (traffic/urban/background/industrial/rural/other), operator, active, last_updated_utc и опциона поља (elevation_m, address, start_date, end_date, notes). Подржани филтери: active, municipality (case-insensitive), station_type, bbox (min_lon,min_lat,max_lon,max_lat).

Параметри упита

Примери кода

curl -s "http://opendata.kosava.cloud/api/v1/stations?municipality=Kikinda"

stations = requests.get(
  "http://opendata.kosava.cloud/api/v1/stations",
  params={"bbox": "19,44,21,46"},
).json()
for s in stations:
  print(s["station_id"], s["station_name"], s["municipality"])

const stations = await fetch("/api/v1/stations?active=true").then(r => r.json());
stations.forEach(s => console.log(s.station_id, s.municipality));

Враћа контролисани речник мерних параметара (Компонента B стандарда). Сваки запис има parameter_code (нпр. PM10, PM2.5, NO2, O3, SO2), parameter_name, unit и фиксни averaging_period=1h. Опционо: cas_number, description.

Одговори

Примери кода

curl -s http://opendata.kosava.cloud/api/v1/parameters

params = requests.get("http://opendata.kosava.cloud/api/v1/parameters").json()
codes = [p["parameter_code"] for p in params]
# ['SO2', 'PM10', 'O3', 'NO2', 'PM2.5', ...]

const params = await fetch("/api/v1/parameters").then(r => r.json());

Враћа сатно упрошечена мерења у HVD облику (Компонента C). Сваки record има station_id, parameter_code, time_start_utc, time_end_utc, value, unit, data_status=preliminary, aggregation_type=hourly_mean, published_at_utc, updated_at_utc, coverage. Прозор се аутоматски сече на rolling 30 дана; meta блок одговора наводи requested_window и actual_window плус out_of_retention_window flag. Без филтера враћа све станице × све параметре (може бити велики payload).

Параметри упита

Примери кода

curl -s "http://opendata.kosava.cloud/api/v1/observations?station_id=1¶meter_code=PM10"

obs = requests.get(
  "http://opendata.kosava.cloud/api/v1/observations",
  params={
    "from": "2026-04-01T00:00:00Z",
    "to": "2026-04-08T00:00:00Z",
    "parameter_code": "PM2.5",
  },
).json()
print(obs["meta"]["actual_window"])
print(len(obs["data"]), "records")

const q = new URLSearchParams({station_id: "1", parameter_code: "PM10"});
const resp = await fetch(`/api/v1/observations?${q}`).then(r => r.json());
console.log(resp.meta.out_of_retention_window);

Враћа листу bulk ресурса за активни snapshot. Сваки запис има name, format, content_type, size_bytes, sha256, download_url. Bundle укључује stations.csv/geojson, parameters.csv/json, observations CSV и Parquet (краћи ~13× од CSV-а), README.md са data dictionary-јем и CHECKSUMS.sha256. Lazy on-demand build са snapshot-id keyed cache-ом.

Одговори

Примери кода

curl -s http://opendata.kosava.cloud/api/v1/bulk | python3 -m json.tool

index = requests.get("http://opendata.kosava.cloud/api/v1/bulk").json()
for r in index["resources"]:
  print(r["name"], r["size_bytes"], r["sha256"])

const idx = await fetch("/api/v1/bulk").then(r => r.json());
console.log(idx.snapshot_id, idx.resources.length);

Сервира један bulk фајл као attachment. Response заглавља укључују Content-Disposition (attachment; filename="..."), Content-Length, Content-Type и X-Content-SHA256 (мора се подударати са sha256 у индексу).

Параметри путање

Одговори

Примери кода

curl -O http://opendata.kosava.cloud/api/v1/bulk/observations_hourly_preliminary_last30days.parquet

import requests, pyarrow.parquet as pq
from io import BytesIO
data = requests.get("http://opendata.kosava.cloud/api/v1/bulk/observations_hourly_preliminary_last30days.parquet").content
table = pq.read_table(BytesIO(data))
print(table.num_rows, table.column_names)

const blob = await fetch("/api/v1/bulk/stations.geojson").then(r => r.blob());
// feed blob to Leaflet, OpenLayers, etc.

Враћа DCAT-AP HVD каталог као application/ld+json са @context и @graph од 16 нодова: један dcat:Catalog, foaf:Organization (publisher) и vcard:Organization (контакт), три dcat:Dataset (stations, parameters, observations), девет dcat:Distribution (API + CSV/GeoJSON/JSON/Parquet по датасету), један dcat:DataService. Сваки Dataset/Distribution носи dcatap:applicableLegislation (ELI 2023/138) и dcatap:hvdCategory (Earth observation and environment). Погодно за harvest на EU/националним порталима.

Одговори

Примери кода

curl -s -H "Accept: application/ld+json" http://opendata.kosava.cloud/api/v1/dcat

cat = requests.get("http://opendata.kosava.cloud/api/v1/dcat").json()
datasets = [n for n in cat["@graph"] if n.get("@type") == "dcat:Dataset"]
print(len(datasets), "datasets")

const cat = await fetch("/api/v1/dcat").then(r => r.json());
// JSON-LD compatible with rdflib, jsonld.js, Apache Jena

Враћа JSON са дефиницијама свих поља у три компоненте (stations, parameters, observations) плус листу забрањених поља. Погодан за клијентске валидације и аутоматску генерацију форми/документације.

Параметри упита

Идентификација и геолокација мерних места. Endpoint /api/v1/stations враћа листу са свим пољима испод; bulk дистрибуције су stations.csv и stations.geojson.

Контролисани речник мерних величина. Endpoint /api/v1/parameters враћа низ; bulk дистрибуције су parameters.csv и parameters.json.

Сатно упрошечена мерења са свим станицама и параметрима у rolling 30-day прозору. Endpoint /api/v1/observations враћа JSON са data + meta блоком; bulk дистрибуције су observations_hourly_preliminary_last30days.csv и .parquet.