Hozana.si

API dostop

Podatke s strani hozana.si lahko uporabite tudi na svoji spletni strani ali v aplikaciji. Na voljo sta dve poti:

  1. osnovni_podatki.json – brezplačna datoteka z osnovnimi podatki o vseh dnevih tekočega koledarskega leta (brez ključa),
  2. api.php – vmesnik z vsebino Božje besede dneva, brevirja in koledarja (potreben je ključ).

1. Osnovni podatki: osnovni_podatki.json

Datoteka https://hozana.si/osnovni_podatki.json vsebuje za vsak dan tekočega leta ime obhajanja, njegovo stopnjo in vrstico dneva – za vse škofije in redove hkrati. Osvežuje se samodejno ob spremembah v bazi. Ključ ni potreben.

Zgradba:

  • skofije: seznam škofijskih koledarjev (id, skofija), npr. slovenija, ljubljana, maribor;
  • redovi: seznam redovnih koledarjev (id, red), npr. kapucini, franciskani, jezuiti;
  • data: seznam obhajanj s polji id, opis (npr. »Sv. Marija, Božja mati«), teza_opis (stopnja: slovesni praznik, praznik, obvezni god, god …), opis_dolgi (opis s stopnjo in dodatki) in vrstica (vrstica dneva iz evangelija);
  • map: preslikava datuma na obhajanja – vsak vnos ima selektor v obliki LLLL-MM-DD-skofija-red (npr. 2026-01-01-slovenija-kapucini) in data_ids s seznamom identifikatorjev iz data; prvi je obhajanje dneva, nadaljnji so morebitni neobvezni godovi.

2. Vmesnik api.php

Vmesnik se nahaja na naslovu https://hozana.si/api.php in vrača podatke v strukturirani JSON obliki (UTF-8). Za uporabo je potreben ključ, za katerega pišite na naslov [email protected], pri čemer navedite, za katero spletno stran ali aplikacijo ga potrebujete.

URL parametri

  • kljuc (obvezen): dodeljeni API ključ.
  • kaj: kaj želite dobiti – bb (Božja beseda dneva; privzeto), brevir (molitveno bogoslužje dneva), koledar (seznam škofij in redov), nakljucni_odpev (naključni psalmski odpev).
  • datum: datum v obliki d.m.llll (npr. datum=23.8.2026); brez parametra se vrne današnji dan. Namesto tega lahko uporabite time s katerimkoli zapisom, ki ga razume PHP funkcija strtotime (npr. time=2026-08-23); če sta podana oba, velja datum.
  • skofija: škofijski koledar (slovenija – privzeto, ljubljana, celje, maribor, murska_sobota, novo_mesto, koper).
  • red: redovni koledar (npr. kapucini, franciskani, minoriti, klarise, 3red, ursulinke, salezijanci, hmp, neo, fmm, cm, hkl, ms, karmel, jezuiti); privzeto noben. Veljavne vrednosti za skofija in red vrne kaj=koledar.
  • brevir (1): opis dneva naj se ravna po brevirju, ki se moli, namesto po Božji besedi, ki se bere pri sv. maši. Razlika nastopi zgolj pri obveznih godovih, kjer se svetuje, naj imajo berila od dneva prednost pred lastnimi berili svetnika; z brevir=1 dobite svetnikova berila in opis.
  • format: json (privzeto) ali txt – kratek besedilni povzetek beril (samo pri kaj=bb, glej spodaj).

kaj=bb – Božja beseda dneva

Vrne en JSON objekt z obhajanjem dneva za izbrani koledar. Najpomembnejša polja:

  • id, opis, opis_dolgi, teza (stopnja obhajanja, številčno), teza_opis (npr. »obvezni god«), teza_brevir, tag;
  • datum (npr. »Nedelja, 23. avgust 2026«), timestamp (Unix čas), krog (nedeljsko leto A/B/C), liturgicni_cas (A advent, B božični čas, P postni čas, V velikonočni čas, L čas med letom; cas je interna oznaka vrstice, pri svetnikih X), barva (liturgična barva dneva: B bela, R rdeča, Z zelena, V vijolična), barva_casa (barva liturgičnega časa);
  • vrstica: vrstica dneva iz evangelija;
  • berilo1, berilo2 (ob delavnikih prazno), psalm, evangelij: svetopisemski sklici; k vsakemu še *_naslov (naslov odlomka), *_vsebina (besedilo odlomka v HTML), *_napoved (napoved knjige, npr. »Berilo iz knjige preroka Izaija«); pri psalmu odpev in psalm_vsebina; aleluja (vrstica pred evangelijem);
  • opis_2vecernice, opis_2vecernice_dolgi, teza_2vecernice: obhajanje, ki velja ob večernicah (ob nedeljah in slovesnih praznikih se s prvimi večernicami že začne naslednji dan);
  • mp3: povezava do zvočnega posnetka beril, če obstaja; video: povezave do posnetkov, če obstajajo;
  • pri svetnikih še dan (d.m.), skloni (ime v sklonih), opomba.

Z format=txt dobite besedilni povzetek (opis dneva, sklici beril, psalma in evangelija ter vrstica dneva), prelomljen na 37 znakov – primeren za ozke prikazovalnike.

kaj=brevir – molitveno bogoslužje dneva

Vrne objekt s polji status, id, opis, vrstica, stevilo_skupnih in brevir. Slednje je seznam (po en vnos za vsako različico skupnih molitev, navadno eden) z deli molitvenega bogoslužja v HTML obliki: povabilo, bb (bogoslužno branje), hvalnice, dmu (dnevna molitvena ura), vecernice, magnifikat, sklepnice (sklepna molitvena ura) ter skupna in skupna_ime (uporabljene skupne molitve). Polje css vsebuje slogovno datoteko, s katero se HTML pravilno izriše (namenjeno projekciji). Parametra skofija in red določata koledar, brevir tu ni potreben.

kaj=koledar in kaj=nakljucni_odpev

kaj=koledar vrne seznama vseh škofijskih in redovnih koledarjev (identifikator → ime), ki jih sprejmeta parametra skofija in red. kaj=nakljucni_odpev vrne naključen psalmski odpev iz baze (polje odgovor).

Primeri

  • https://hozana.si/api.php?kljuc=VAŠ_KLJUČ – Božja beseda današnjega dne po splošnem slovenskem koledarju
  • https://hozana.si/api.php?kljuc=VAŠ_KLJUČ&datum=23.8.2026&skofija=ljubljana&red=kapucini – določen dan po ljubljanskem kapucinskem koledarju
  • https://hozana.si/api.php?kljuc=VAŠ_KLJUČ&brevir=1 – opis in berila glede na brevir dneva
  • https://hozana.si/api.php?kljuc=VAŠ_KLJUČ&format=txt – besedilni povzetek
  • https://hozana.si/api.php?kljuc=VAŠ_KLJUČ&kaj=brevir&datum=21.8.2026 – molitveno bogoslužje dneva
  • https://hozana.si/api.php?kljuc=VAŠ_KLJUČ&kaj=koledar – seznam koledarjev

Napake in omejitve

  • Ob napaki vmesnik vrne objekt s poljem napaka in opisom (manjkajoč ali neveljaven ključ, porabljena dnevna kvota, neobstoječa datoteka).
  • Vsak ključ ima dnevno na razpolago 10 zahtevkov; števec se ponastavi ob polnoči. Enaki zahtevki se na strežniku predpomnijo.
  • API je namenjen izključno uporabi v zaledju (backend): podatke prenesite enkrat dnevno in jih shranite na svojem strežniku, ne kličite vmesnika ob vsakem obisku svoje strani.
  • Podatke lahko zahtevate za katerikoli datum (koledar se izračuna sproti). Besedila beril so v HTML obliki; pri objavi navedite vir hozana.si.

Za celoten izvoz baze (datoteka baza_lekcionar.json, ki jo uporablja Android aplikacija Lekcionar) je potreben poseben dogovor – pišite na [email protected].