jecnarozvrh/web/content/posts/api-usage/v1.md

title, date, tags, hiddenInHomelist

title	date	tags	hiddenInHomelist
API Dokumentace - Verze 1	2025-12-20	api docs v1	true

Tato stránka detailně popisuje Verzi 1 (v1) API Ječná Rozvrh.

Endpoint: GET /versioned/v1

Toto je hlavní endpoint, který poskytuje veškerá data o rozvrhu pro v1.

Struktura Odpovědi

Odpověď je JSON objekt, který obsahuje tři hlavní klíče: schedule, props, a status.

Zobrazit příklad struktury odpovědi

{
  "schedule": [ /* pole denních rozvrhů */ ],
  "props": [ /* pole vlastností dnů */ ],
  "status": { /* objekt stavu */ }
}

---

Datové Struktury

Sekce: schedule

Tato sekce je pole, kde každý prvek představuje jeden den. Každý den je objekt, jehož klíče jsou názvy jednotlivých tříd (např. A1, C2a, E4) a speciální klíč ABSENCE.

Rozvrh Třídy

• Klíč: Název třídy (např. "A1")
• Hodnota: Pole s 10 prvky, které reprezentují 10 vyučovacích hodin.
  • string: Pokud je hodina normálně vyučována, obsahuje název předmětu nebo informaci o změně.
  • null: Pokud hodina odpadá nebo pro ni není záznam.
  • Text (bude upřesněno) může být připojen k předmětu, pokud je změna nejistá.

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

"A1": [
  "M 5 Kp(Ng)",
  null,
  null,
  "(Me) (bude upřesněno)",
  null,
  null,
  null,
  null,
  null,
  null
]

Absence Učitelů

• Klíč: "ABSENCE"
• Hodnota: Pole objektů, kde každý objekt specifikuje jednu absenci. Struktura objektu je následující:
  • teacher (string | null): Celé jméno učitele, pokud je známé.
  • teacherCode (string | null): Zkratka jména učitele (např. "me", "ad").
  • type (string): Typ absence. Může nabývat následujících hodnot:
    • "wholeDay": Učitel chybí celý den.
    • "single": Učitel chybí jednu vyučovací hodinu.
    • "range": Učitel chybí v rozmezí několika hodin.
    • "exkurze": Učitel je na exkurzi.
    • "invalid": Záznam o absenci se nepodařilo zpracovat.
  • hours (object | number | null): Specifikuje hodiny absence.
    • null: Pro typy wholeDay, exkurze, a invalid.
    • number (např. 3): Pro typ single.
    • object (např. { "from": 2, "to": 4 }): Pro typ range.
  • original (string | null): Pouze pro typ invalid, obsahuje původní nezpracovaný text.

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:

{
  "teacher": "Jan Novák",
  "teacherCode": "no",
  "type": "range",
  "hours": { "from": 2, "to": 4 }
}

Exkurze:

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

Neplatný záznam:

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

Sekce: props - Vlastnosti Dnů

Pole objektů, které doplňují metadata ke každému dni v poli schedule. Pořadí prvků v props přesně odpovídá pořadí dnů v schedule.

• date (string): Datum daného rozvrhu ve formátu YYYY-MM-DD.
• priprava (boolean): Hodnota je true, pokud je den součástí "přípravného týdne", jinak false.

Zobrazit příklad props

"props": [
  {
    "date": "2025-12-20",
    "priprava": false
  },
  {
    "date": "2025-12-21",
    "priprava": true
  }
]

Sekce: status - Stav a Metadata

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

• lastUpdated (string): Čas poslední úspěšné aktualizace dat ve formátu HH:MM.
• currentUpdateSchedule (number): Interval v minutách, ve kterém scraper interně kontroluje a stahuje novou verzi rozvrhu. Tento interval se dynamicky mění 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
}

---

Kompletní Příklad Odpovědi z GET /versioned/v1

Zobrazit kompletní příklad

{
  "schedule": [
    {
      "A1": [
        "M 6 Kp(Ng)",
        null,
        null,
        null,
        "(Me) (bude upřesněno)",
        null,
        null,
        null,
        null,
        null
      ],
      "C2": [
        "M 6 Kp(Ng)",
        null,
        null,
        null,
        "(Me) (bude upřesněno)",
        null,
        null,
        null,
        null,
        null
      ],
      "ABSENCE": [
        {
          "teacher": "Jan Novák",
          "teacherCode": "no",
          "type": "range",
          "hours": {"from": 1, "to": 3}
        }
      ]
    }
  ],
  "props": [
    {
      "date": "2025-12-20",
      "priprava": false
    }
  ],
  "status": {
    "lastUpdated": "14:30",
    "currentUpdateSchedule": 5
  }
}