Öffentliche REST-API

API v1 · PRO6 Min.Stand: 31. Oktober 2026

Die öffentliche Schnittstelle unter convention-schedule-planner/public/v1 liefert das Programm lesend als JSON – für Apps, Partner-Websites, Infoscreens und Beschilderungssysteme. Einschalten und Schlüssel vergeben beschreibt Reiter API; hier geht es um die Anbindung.

Ein Vertrag, der hält

Die API hat ein eigenes, festes Datenformat, unabhängig von der Kalenderanzeige. Felder kommen höchstens hinzu, werden aber nie umbenannt oder entfernt. Fehlt ein Feld, ist der zugehörige Datenbereich im Reiter API ausgeschaltet.

Adresse und Schlüssel

Alle Adressen beginnen mit der Basis-Adresse, z. B. https://ihre-seite.de/wp-json/convention-schedule-planner/public/v1. Bei „einfachen“ Permalinks sieht sie anders aus (?rest_route=/convention-schedule-planner/public/v1/…) – die im Reiter API angezeigte Adresse stimmt immer.

Weg	Beispiel	Hinweis
Header `X-EC-API-Key`	`X-EC-API-Key: ecpk_…`	Empfohlen.
Header `Authorization`	`Authorization: Bearer ecpk_…`	Gleichwertig.
Parameter `api_key`	`?api_key=ecpk_…`	Nur für Werkzeuge ohne Header – der Schlüssel landet dann in Server-Logs.

Kein Schlüssel in öffentliches JavaScript

Was im Browser Ihrer Besucher läuft, kann jeder lesen. Für Widgets auf fremden Websites den Zugriff „Öffentlich“ wählen oder die Daten über einen Server holen.

Endpunkte

Endpunkt	Inhalt
`GET /info`	Name der Website, Zeitzone, API-Version, Datenumfang, Anzahlen, Primärfarbe. Ohne Schlüssel lesbar.
`GET /events`	Programmpunkte, seitenweise, mit Filtern (siehe unten).
`GET /events/{id}`	Ein Programmpunkt oder eine Hauptveranstaltung samt Beschreibung.
`GET /venues`	Alle Orte mit Hierarchie, Farbe und Bild. `hide_empty=true` zeigt nur genutzte.
`GET /categories`	Alle Kategorien mit Hierarchie und Farbe.
`GET /speakers`	Öffentliche Sprecherprofile, seitenweise, mit Suche. Nur bei eingeschaltetem Datenbereich „Sprecher“. Das Feld `company_logo` enthält hier und in `/speakers/{id}` die Adresse des Beitragsbilds des verknüpften Ausstellers, sonst `null`, unabhängig vom Schalter „Sprecher: Firmenlogo“.
`GET /speakers/{id}`	Ein Sprecherprofil mit Beschreibung und den IDs seiner Programmpunkte.
`GET /openapi`	Maschinenlesbare Beschreibung (OpenAPI 3.1) für Postman, Insomnia, Swagger UI und Code-Generatoren. Ohne Schlüssel lesbar.

Begriffe: Eine Hauptveranstaltung (Messe, Festival) enthält Programmpunkte. Programmpunkte ohne Hauptveranstaltung gelten ebenfalls als Programmpunkte.

Parameter von /events

Parameter	Werte / Standard	Bedeutung
`type`	`item` · `main` · `all` – Standard `item`	Programmpunkte, Hauptveranstaltungen oder beides.
`parent`	ID	Nur Programmpunkte dieser Hauptveranstaltung.
`from`, `to`	`JJJJ-MM-TT`	Zeitraum. Hauptveranstaltungen zählen, wenn sich ihr Zeitraum überschneidet.
`venue`	IDs oder Slugs, kommagetrennt	Schließt Unterorte ein – der Filter für eine Halle findet auch ihre Räume.
`category`	IDs oder Slugs, kommagetrennt	Schließt Unterkategorien ein.
`search`	Text	Volltextsuche in Titel, Kurzbeschreibung und Beschreibung.
`status`	`any` · `scheduled` · `cancelled` – Standard `any`	Nach Status filtern.
`modified_since`	ISO 8601	Nur seitdem Geänderte – für die schrittweise Synchronisation.
`orderby`, `order`	`start` · `title` · `modified`; `asc` · `desc`	Standard: nach Beginn, aufsteigend.
`speaker`	ID	Nur Programmpunkte mit diesem Sprecher (Datenbereich „Sprecher“).
`include`	`description`	Lange Beschreibung auch in Listen (Datenbereich „Beschreibung“).
`page`, `per_page`	ab 1; 1–100, Standard 50	Seitenweise Ausgabe.
`_fields`	Feldliste	Nur die genannten Felder, z. B. `_fields=id,title,start`. Für jeden Endpunkt.

Filter lassen sich mit & beliebig kombinieren. Ein unbekannter Ort oder eine unbekannte Kategorie liefert eine leere Liste, nicht alle Einträge.

Typische Abfragen

/events?type=main
/events?parent=123&per_page=100
/events?parent=123&from=2026-10-17&to=2026-10-17&venue=grosser-saal
/events?parent=123&status=cancelled
/events?modified_since=2026-10-17T00:00:00Z
/events?parent=123&_fields=id,title,start,end,venue

So sieht ein Programmpunkt aus

Antwort (gekürzt)

{
  "id": 4711,
  "type": "item",
  "status": "scheduled",
  "title": "Workshop: Feenflügel malen",
  "date": "2026-10-17",
  "start_time": "14:00",
  "end_time": "15:30",
  "start": "2026-10-17T14:00:00+02:00",
  "end": "2026-10-17T15:30:00+02:00",
  "parent": { "id": 123, "title": "Convention 2026" },
  "venue": { "id": 12, "slug": "werkstatt", "name": "Werkstatt" },
  "categories": [ { "id": 7, "slug": "workshop", "name": "Workshop" } ],
  "color": "#8e44ad",
  "image": { "url": "https://…/workshop.jpg", "is_fallback": false },
  "speakers": [ { "id": 55, "name": "Erika Mustermann", "role": "Sprecher" } ],
  "price": "12 €",
  "ticket_url": "https://tickets.example.com/",
  "permalink": "https://…/events/workshop-feenfluegel-malen/",
  "url": "https://…/events/workshop-feenfluegel-malen/",
  "link_type": "page",
  "modified": "2026-10-17T09:12:00+00:00"
}

Feld	Bedeutung
`start_time`, `end_time` / `start`, `end`	Ortszeit – und zusätzlich vollständig mit Datum und Zeitzone. Liegt das Ende vor dem Beginn, läuft der Punkt über Mitternacht; `end` liegt dann am Folgetag.
`type`	`item` oder `main`. Hauptveranstaltungen tragen zusätzlich `date_range` und `items_count`.
`status`	`cancelled` bei Absagen. Abgesagte bleiben in der Liste, damit Apps die Absage zeigen können.
`url`, `link_type`	Wohin ein Klick führt – wie auf der Website: Detailseite, externer Link oder nirgends (`null`). `permalink` ist immer die Detailseite.
`speakers[].id`	Nur bei öffentlichen Sprecherprofilen gesetzt, sonst `null`. Der Name ist immer enthalten.
`color`	Hervorhebungsfarbe von Ort oder Kategorie. Bei `null` die `primary_color` aus `/info` verwenden.

Seiten und Aktualität

Listen kommen in Seiten zu höchstens 100 Einträgen. Die Gesamtzahl steht in den Headern X-WP-Total und X-WP-TotalPages; der Link-Header enthält die Adresse der nächsten Seite.

ETag (empfohlen): Jede Antwort trägt einen ETag. Schickt die Anwendung ihn als If-None-Match zurück, kommt bei unveränderten Daten ein kurzes 304 Not Modified.
modified_since: Liefert nur Geändertes. Gelöschte oder zurückgezogene Punkte tauchen dabei einfach nicht mehr auf – laden Sie deshalb regelmäßig (etwa einmal täglich) das ganze Programm und entfernen Sie fehlende IDs.

Sinnvolle Abstände: während der Veranstaltung alle 5 bis 15 Minuten, sonst einige Male am Tag. Die Mengenbegrenzung (Standard 120 Anfragen pro Minute) liegt weit darüber.

Codebeispiele

JavaScript – alle Seiten eines Programms laden

const BASE = 'https://ihre-seite.de/wp-json/convention-schedule-planner/public/v1';
const KEY  = 'ecpk_…';

async function loadProgram(parentId) {
  const events = [];
  for (let page = 1; ; page++) {
    const res = await fetch(BASE + '/events?parent=' + parentId + '&per_page=100&page=' + page, {
      headers: { 'X-EC-API-Key': KEY }
    });
    if (!res.ok) throw new Error('HTTP ' + res.status);
    events.push(...await res.json());
    if (page >= Number(res.headers.get('X-WP-TotalPages'))) break;
  }
  return events;
}

PHP – auf einer WordPress-Partnerseite, 10 Minuten zwischengespeichert

$events = get_transient( 'partner_program' );

if ( false === $events ) {
    $response = wp_remote_get(
        'https://ihre-seite.de/wp-json/convention-schedule-planner/public/v1/events?parent=123&per_page=100',
        array( 'headers' => array( 'X-EC-API-Key' => 'ecpk_…' ), 'timeout' => 15 )
    );
    $events = ( 200 === wp_remote_retrieve_response_code( $response ) )
        ? json_decode( wp_remote_retrieve_body( $response ), true )
        : array();
    set_transient( 'partner_program', $events, 10 * MINUTE_IN_SECONDS );
}

Beispiele mit Ihren eigenen Daten

Die Plugin-Hilfe im Backend zeigt dieselben Beispiele mit einer echten Hauptveranstaltung und einem echten Ort Ihrer Website – jede Adresse lässt sich dort kopieren und direkt ausprobieren.

Fehlermeldungen

Fehler kommen als JSON mit code, message und data.status – im selben Format wie die WordPress-REST-API.

Status	Code	Bedeutung
400	`rest_invalid_param`	Ein Parameter hat das falsche Format, z. B. `from=17.10.2026` statt `2026-10-17`.
400	`ec_api_invalid_page`	Die angefragte Seite liegt hinter der letzten.
401	`ec_api_key_missing`	Kein Schlüssel gesendet, die API verlangt aber einen.
401	`ec_api_key_invalid`	Schlüssel falsch oder gesperrt.
404	`rest_no_route`	API ausgeschaltet oder Adresse vertippt.
404	`ec_api_not_found`	Kein veröffentlichter Eintrag mit dieser ID.
429	`ec_api_rate_limited`	Zu viele Anfragen in einer Minute; der Header `Retry-After` nennt die Wartezeit in Sekunden.

Datenschutz

Die API gibt nur weiter, was Besucher auf der Website ohnehin sehen. Entwürfe, passwortgeschützte Einträge, Favoritenzähler und „nur intern“ markierte Sprecher sind nie enthalten; E-Mail-Adressen sind standardmäßig ausgeschaltet.