jecnarozvrh/web/content/posts/api/v3/index.md

title, date, tags, hiddenInHomelist

title	date	tags	hiddenInHomelist
API Dokumentace - Verze 3	2026-03-17	api docs v3	true

Tato stránka detailně popisuje Verzi 3 (v3) API Ječná Rozvrh. Endpoint poskytuje strukturovaná data o suplování, absencích, událostech a rezervacích místností.

Endpoint: GET /versioned/v3

Toto je hlavní endpoint, který poskytuje veškerá aktuální data.

Struktura Odpovědi

Odpověď je formátována jako JSON objekt obsahující dva hlavní uzly: schedule (samotná data rozvrhu) a status (metadata o rozvrhu).

Zobrazit příklad struktury odpovědi

{
  "schedule": { /* objekt denních rozvrhů */ },
  "status": { /* objekt stavu a metadat */ }
}

---

Datové Struktury

Sekce: schedule

Tato sekce je objekt, kde každý klíč představuje datum ve formátu YYYY-MM-DD (např. "2026-03-17"). Hodnotou je objekt reprezentující data pro daný den. Tento objekt obsahuje klíče: info, changes, absence, takesPlace a reservedRooms.

info

Objekt obsahující dodatečné informace o stavu rozvrhu pro daný den.

• inWork (boolean): Nabyde hodnoty true, pokud se s daným dnem ze strany školy ještě manipuluje (tzv. "příprava"). Znamená to, že data pro tento den nemusí být finální a mohou se ještě měnit.

changes

Objekt obsahující změny v rozvrhu pro jednotlivé třídy.

• Klíč: Název třídy (např. "A1", "C4a").
• Hodnota: Pole o přesně 10 prvcích, které reprezentují 1. až 10. vyučovací hodinu.
  • null: Pro danou hodinu není evidována žádná změna (výuka probíhá normálně, nebo hodina není v rozvrhu).
  • Objekt: Záznam o změně nebo specifické informaci.

Struktura objektu změny:

{
  text: string,               // Textový obsah změny (např. "M 5 odpadá")
  backgroundColor: string | null, // HEX kód barvy pozadí (např. "#DCEDD5")
  foregroundColor?: string,   // Volitelný HEX kód barvy textu (např. "#FF000000")
  willBeSpecified?: boolean   // True, pokud buňka značí "bude upřesněno" (obvykle žlutá barva)
}

Zobrazit příklad rozvrhu pro třídu A1

"A1": [
  {
    "text": "M 5 Kp(Ng)",
    "backgroundColor": "#FFCCCC",
    "foregroundColor": "#FF000000"
  },
  null,
  null,
  {
    "text": "M 5 odpadá",
    "backgroundColor": "#DCEDD5",
    "foregroundColor": "#FF000000"
  },
  null,
  null,
  null,
  null,
  null,
  null
]

absence

Pole objektů, kde každý objekt specifikuje jednu evidovanou absenci učitele nebo změnu jeho stavu (např. exkurze). Pokud pro daný den nikdo nechybí, pole je prázdné [].

Struktura objektu absence:

• teacher (string | null): Celé jméno učitele (např. "Ing. Jan Novák"), pokud je známé.
• teacherCode (string | null): Interní dvoupísmenná zkratka učitele malými písmeny (např. "no").
• type (string): Typ záznamu. Možné hodnoty:
  • "wholeDay": Učitel chybí celý den.
  • "single": Učitel chybí jednu konkrétní vyučovací hodinu.
  • "range": Učitel chybí v rozmezí několika vyučovacích hodin.
  • "exkurze": Učitel je mimo školu na exkurzi.
  • "zastoupen": Specifický stav, kdy učitele kompletně zastupuje někdo jiný.
  • "invalid": Záznam o absenci se nepodařilo zpracovat.
• hours (object | number | null): Specifikuje vyučovací hodiny, kterých se záznam týká.
  • null: Pro typy wholeDay, zastoupen, invalid a často i exkurze (pokud je na celý den).
  • number (např. 3): Pro typ single (týká se pouze 3. hodiny).
  • object (např. { "from": 2, "to": 4 }): Pro typ range nebo částečnou exkurze (týká se času od 2. do 4. hodiny).
• zastupuje (object | volitelné): Přítomno pouze u typu "zastoupen". Obsahuje vnořené klíče teacher a teacherCode pro učitele, který přebírá výuku.
• original (string | volitelné): Přítomno pouze u typu "invalid". Obsahuje původní textový řetězec, který se nepodařilo zpracovat.

Zobrazit příklady absencí

Celý den:

{
  "teacher": "Jan Novák",
  "teacherCode": "no",
  "type": "wholeDay",
  "hours": null
}

Jedna hodina:

{
  "teacher": "Jan Novák",
  "teacherCode": "no",
  "type": "single",
  "hours": 1
}

Rozsah hodin (od-do):

{
  "teacher": "Petr Svoboda",
  "teacherCode": "sv",
  "type": "range",
  "hours": { "from": 2, "to": 4 }
}

Exkurze: (celý den)

{
  "teacher": "Bc. Jakub Dvořák",
  "teacherCode": "dv",
  "type": "exkurze",
  "hours": null
}

Kompletní zastoupení:

{
  "teacher": "Ing. Zdeněk Vondra",
  "teacherCode": "vn",
  "type": "zastoupen",
  "hours": null,
  "zastupuje": {
    "teacher": "David Janoušek",
    "teacherCode": "jk"
  }
}

Neplatný záznam:

{
  "type": "invalid",
  "teacher": null,
  "teacherCode": null,
  "hours": null,
  "original": "Nezpracovatelný text"
}

takesPlace

String obsahující text aktuálně probíhajících akcí pro daný den (např. akce, exkurze, maturitní zkoušky).

• Může obsahovat znaky nového řádku \n pro oddělení více akcí.
• Pokud pro daný den žádná akce neprobíhá, vrací prázdný string "".

reservedRooms

Pole o přesně 10 prvcích, které reprezentuje rezervace konkrétních místností pro 1. až 10. vyučovací hodinu.

• string: Název rezervované místnosti (např. "19a", "TV").
• null: Pokud pro danou hodinu není evidována žádná rezervace místnosti.

Sekce: status - Stav a Metadata

Objekt poskytující informace o aktuálnosti dat.

• lastUpdated (string): Čas (ve formátu HH:MM), kdy byla data naposledy úspěšně získána a uložena na serveru.
• currentUpdateSchedule (number | volitelné): Interval v minutách, ve kterém systém periodicky kontroluje nová data (může se měnit v závislosti na denní době - kratší během vyučování, delší v noci).

Zobrazit příklad status

"status": {
  "lastUpdated": "08:30",
  "currentUpdateSchedule": 5
}