OPlanner Web API

Read-only API pro web orchestru nebo souboru: nadcházející koncerty, archiv podle let a veřejné profily účinkujících – sólistů, dirigentů a sborů či souborů.

Přehled

Základní adresa:

http://oplanner.cz/api/v1

Všechny odpovědi jsou JSON v UTF-8. API pouze čte (GET), nic nemění.
Každý klíč patří jedné organizaci a vrací jen to, co organizace v OPlanneru výslovně zveřejnila: koncerty projektů se zapnutým „Zveřejnit na webu“ a profily účinkujících schválené pro web.
Zrušené a smazané koncerty ani interní údaje (hráči, honoráře, kontakty) API nikdy nevrací.

Autentizace

Klíč vytváří administrátor organizace v OPlanneru: Nastavení → Nastavení aplikace → Webové API. Má tvar opk_… a zobrazí se jen jednou. Posílejte ho v hlavičce:

Authorization: Bearer opk_VÁŠ_KLÍČ

Pokud hlavičku nastavit nejde (např. statický generátor), lze použít parametr ?key=opk_…. Klíč v URL se ale snáz dostane do logů, proto dáváme přednost hlavičce.

Doporučujeme volat API ze serveru webu (PHP, Node, build statického webu) a výsledek si na pár minut uložit. Klíč tak nebude vidět v prohlížeči. Klíč, který unikl, administrátor jedním kliknutím zruší a vytvoří nový.

Rychlý start

curl

curl -H "Authorization: Bearer opk_VÁŠ_KLÍČ" \
  "http://oplanner.cz/api/v1/concerts?when=upcoming&lang=cs&limit=10"

PHP

$ctx = stream_context_create(['http' => [
    'header' => "Authorization: Bearer " . getenv('OPLANNER_API_KEY'),
]]);
$json = file_get_contents('http://oplanner.cz/api/v1/concerts?lang=cs', false, $ctx);
$concerts = json_decode($json, true)['data'];
foreach ($concerts as $c) {
    echo htmlspecialchars($c['date_label'] . ' – ' . $c['title']), "<br>";
}

JavaScript (Node 18+ / server)

const res = await fetch('http://oplanner.cz/api/v1/concerts?when=upcoming&lang=en', {
  headers: { Authorization: `Bearer ${process.env.OPLANNER_API_KEY}` },
});
if (!res.ok) throw new Error(`OPlanner API ${res.status}`);
const { data: concerts, meta } = await res.json();

Jazyky, stránkování, cache

Jazyk – parametr lang: cs (výchozí), en, de. Týká se názvů, popisů, biografií, rolí (nástroje, „dirigent“) a date_label. Chybí-li překlad, vrátí se text v pořadí cs → en → de. Názvy skladeb a jména jsou jen v jedné podobě.
Stránkování – seznamy přijímají limit a offset a vracejí meta: {"total": 42, "limit": 50, "offset": 0, "has_more": false, "lang": "cs"}.
Cache – odpovědi mají Cache-Control: private, max-age=300 a ETag. S hlavičkou If-None-Match dostanete 304 Not Modified. Změny v OPlanneru se tak na webu projeví nejpozději do pár minut.
Čas – data jsou YYYY-MM-DD, časy HH:MM a starts_at je ISO 8601 v časovém pásmu Europe/Prague.
Texty – popisy a biografie jsou prostý text (mohou obsahovat konce řádků). Před vložením do HTML je escapujte a konce řádků převeďte na <br> nebo odstavce.

Endpointy

GET/concerts

Zveřejněné koncerty. Koncert je buď akce typu „Koncert“ v projektu, nebo koncert v programu zájezdu.

Parametr	Hodnoty	Popis
`when`	`upcoming` (výchozí), `past`, `all`	`upcoming` = od dneška, řazeno od nejbližšího. `past` a `all` řadí od nejnovějšího.
`year`	např. `2026`	Jen koncerty daného roku (archiv). Bez `when` vrací celý rok od nejnovějšího.
`lang`	`cs`, `en`, `de`	Jazyk textů.
`limit`, `offset`	1–200 (výchozí 50), ≥ 0	Stránkování.

GET /concerts?when=upcoming&lang=cs&limit=1

{
  "data": [ Concert … ],
  "meta": {"total": 12, "limit": 1, "offset": 0, "has_more": true, "lang": "cs"}
}

GET/concerts/years

Roky, ve kterých je aspoň jeden zveřejněný koncert, od nejnovějšího. Hodí se pro menu archivu.

{"data": [2026, 2025, 2024]}

GET/concerts/{id}

Jeden koncert. id je hodnota z výpisu: e812 (koncert projektu) nebo t45 (koncert zájezdu). Nezveřejněný, zrušený nebo neexistující koncert vrací 404. Parametr lang jako výše.

{"data": Concert}

GET/performers

Veřejné profily účinkujících seřazené podle jména: sólisté, dirigenti, sbory a soubory. Jen profily, které organizace schválila pro web.

Parametr	Hodnoty	Popis
`kind`	`soloist`, `conductor`, `ensemble`	Jen jeden druh. Bez parametru všechny.
`lang`	`cs`, `en`, `de`	Jazyk popisku druhu.
`limit`, `offset`	1–500 (výchozí 200), ≥ 0	Stránkování.

{
  "data": [
    {"id": 9, "kind": "conductor", "kind_label": "dirigent", "name": "Jaroslav Martinásek",
     "photo_url": "http://oplanner.cz/api/v1/performers/9/photo.jpg?v=1760090000", "website_url": null}
  ],
  "meta": {"total": 1, "limit": 200, "offset": 0, "has_more": false, "lang": "cs"}
}

GET/performers/{id}

Profil včetně biografie v jazyce lang. performer_id z koncertů vede právě sem.

{"data": Performer}

GET/performers/{id}/photo.jpg

Fotografie veřejného profilu (JPEG, nejvýše 1600 px). Bez klíče, takže ji lze přímo použít v <img src>. Používejte celou adresu z photo_url: parametr v se při změně fotky změní, a obrázek je proto možné dlouho cachovat.

Objekt koncertu

{
  "id": "e812",
  "project_id": 43,
  "source": "event",
  "title": "Koncert",
  "description": "Koncert se koná za finanční podpory statutárního města Brna.",
  "date": "2026-10-10",
  "time": "15:30",
  "starts_at": "2026-10-10T15:30:00+02:00",
  "date_label": "10. říjen 2026, 15:30, sobota",
  "venue": {
    "name": "Farní kostel Narození Panny Marie",
    "address": "Vranov, Česká republika",
    "map_url": "https://www.google.com/maps/search/?api=1&query=…"
  },
  "ticket_url": "https://vstupenky.example.cz/812",
  "image_url": null,
  "programme": [
    {"composer": "Antonín Rejcha",
     "works": [{"title": "Te Deum", "catalog_number": null, "movement": null, "arrangement": null, "encore": false}]},
    {"composer": "Wolfgang Amadeus Mozart",
     "works": [{"title": "Mše c moll", "catalog_number": "KV 427", "movement": "Kyrie", "arrangement": null, "encore": false}]}
  ],
  "performers": {
    "soloists":   [{"performer_id": 21, "name": "Jana Nováková", "roles": ["soprán"]}],
    "ensembles":  [{"performer_id": 17, "name": "Smíšený pěvecký sbor Rastislav", "roles": ["sbor"]}],
    "conductors": [{"performer_id": 9,  "name": "Jaroslav Martinásek", "roles": ["dirigent"]}]
  }
}

Pole	Popis
`id`	Stabilní identifikátor koncertu (`e…` projekt, `t…` zájezd).
`project_id`	Koncerty jednoho projektu nebo zájezdu sdílejí stejnou hodnotu. Hodí se pro seskupení turné.
`title`	Veřejný název nastavený v OPlanneru. Bez něj „Koncert“ / „Concert“ / „Konzert“.
`description`	Veřejný popis koncertu nebo projektu, prostý text, může být `null`.
`time`, `starts_at`	`null`, pokud čas ještě není určen.
`venue`	Název místa, adresa jako jeden řádek textu a odkaz na mapu. Kterékoli pole může být `null`.
`ticket_url`	Odkaz „koupit vstupenku“, nebo `null`.
`image_url`	Zatím vždy `null` (obrázky projektů připravujeme).
`programme`	Program po skupinách: po sobě jdoucí skladby jednoho skladatele jsou v jedné skupině, přestávky jsou vynechány. `encore` = přídavek.
`performers`	Tři bloky: `soloists`, `ensembles`, `conductors`. `roles` obsahuje nástroj nebo hlas sólisty, případně „dirigent“ či „sbor“ v jazyce `lang`. `performer_id` je `null`, pokud účinkující nemá profil schválený pro web. Jméno se i tak zobrazí, jen bez odkazu na profil.

Objekt účinkujícího

{
  "id": 21,
  "kind": "soloist",
  "kind_label": "sólista",
  "name": "Jana Nováková",
  "photo_url": "http://oplanner.cz/api/v1/performers/21/photo.jpg?v=1760090000",
  "website_url": "https://www.example.com",
  "biography": "Sopranistka Jana Nováková vystudovala…",
  "biography_languages": ["cs", "en"]
}

kind: soloist (sólista), conductor (dirigent), ensemble (sbor / soubor). Seznam /performers vrací stejná pole kromě biography a biography_languages. biography_languages říká, ve kterých jazycích biografie opravdu existuje. Můžete tak skrýt přepínač jazyka nebo označit text převzatý z jiného jazyka.

Chyby a limity

Chyby mají vždy tvar {"error": "kód", "message": "lidsky čitelný popis"}.

Status	`error`	Kdy
400	`invalid_parameter`	Neplatný `when`, `year` nebo `kind`.
401	`invalid_token`	Chybí klíč, je neplatný nebo byl zrušen.
403	`feature_not_in_plan`	Organizace nemá v plánu modul Webové API.
404	`not_found`	Koncert nebo profil neexistuje nebo není zveřejněný.
429	`rate_limited`	Více než 300 požadavků za minutu na jeden klíč.

Volání z prohlížeče (CORS)

Ve výchozím stavu API odpovídá bez hlaviček CORS, takže ho prohlížeč z cizí domény přímo volat nemůže. Pokud chcete volat API z JavaScriptu v prohlížeči, administrátor u klíče vyplní „Povolené weby“ (např. https://www.example.cz). Odpověď pak obsahuje Access-Control-Allow-Origin pro tuto adresu. Vše, co API vrací, je veřejné, ale klíč v kódu stránky může kdokoli zkopírovat a čerpat z něj limit požadavků. Proto doporučujeme volání ze serveru.

OpenAPI

Strojově čitelný popis (OpenAPI 3.1) pro generátory klientů a nástroje typu Postman nebo Swagger UI: http://oplanner.cz/api/v1/openapi.json

Verze API 1.0.0. Nová pole mohou přibýt bez změny verze. Odstranění nebo změna významu pole by přišla až s novou cestou /api/v2.