Belegungsdaten

Über die Belegungsabfrage erfährt ein externes System, wann welche Plätze eines Standorts belegt sind. Typische Anwendung ist die Steuerung von Licht und Heizung: Sind in einem Zeitfenster Plätze reserviert, schaltet die Steuerung das Licht dieser Plätze ein und wärmt die Halle auf. Die Antwort enthält pro Zeitfenster die Zahl freier und belegter Plätze und den Schaltzustand je Platz.

Begriffe

Zusammenhang

Die Abfrage berücksichtigt nur Reservierungen, die tatsächlich Platz belegen. Gesperrte, deaktivierte und stornierte Reservierungen, auch kurzfristig stornierte, zählen nicht als Belegung. Hat der Standort an dem Tag keine Öffnungszeiten, liefert die Antwort den Standortstatus closed und keine Zeitfenster. Änderungen im Reservierungskalender erscheinen bei der nächsten Abfrage, das System speichert nichts zwischen.

Die Nummer des Standorts lesen Sie im Backend aus der Adresszeile, wenn Sie den Standort in der Formularansicht öffnen (am Ende der Adresse #id=<Nummer>). Der Schlüssel für die Abfrage kommt aus der Authentifizierung.

Typischer Ablauf

1. Schlüssel einrichten – siehe Authentifizierung.
2. Standortnummer ermitteln – wie oben beschrieben.
3. Abfrage senden – zum Beispiel stündlich oder beim Start der Steuerung:

curl -X GET "https://<jawengo-url>/api/location/<location-id>/power?date=2026-10-05" \
     -H "Accept: application/json" \
     -H "API_KEY: <api-key>"

Der Parameter date (Format JJJJ-MM-TT) ist optional; ohne Angabe gilt das heutige Datum.

1. Antwort auswerten – die Steuerung schaltet je Zeitfenster Licht und Heizung:

{
  "date": "2026-10-05",
  "location_id": 3,
  "location_state": "open",
  "location_name": "Air Dome",
  "slots": [
    {
      "time_from": 7.0,
      "free_pitches": 1,
      "used_pitches": 0,
      "total_pitches": 1,
      "heat_state": "cold",
      "light_states": [
        {"pitch_id": 28, "pitch_name": "Court 7", "light_state": "off"}
      ]
    },
    {
      "time_from": 8.0,
      "free_pitches": 0,
      "used_pitches": 1,
      "total_pitches": 1,
      "heat_state": "warm",
      "light_states": [
        {"pitch_id": 28, "pitch_name": "Court 7", "light_state": "on"}
      ]
    }
  ]
}

Ist der Standort weder als Center noch als allgemeiner Standort freigegeben, antwortet die Abfrage mit false.

Weitere Abfragen zum Angebot

Sportarten und ihre Standorte liefert GET /api/sports (ein einzelner Eintrag: /api/sports/<id>); die Plätze GET /api/pitches. Freie Zeitfenster einer Sportart liefert GET /api/sports/<id>/availability mit den optionalen Parametern location, date, duration, time_from und time_to. Alle Adressen stehen in Weitere Endpunkte.

curl -X GET "https://<jawengo-url>/api/sports" -H "API_KEY: <api-key>"

Beispielantwort, gekürzt:

[
  {
    "name": "Tennis",
    "location_ids": [{"id": 3, "name": "Air Dome"}],
    "pitch_ids": [{"id": 28, "name": "Court 7", "location_id": {"id": 3}}]
  }
]

Die Einträge der Sportarten enthalten keine eigene Nummer. Ein einzelner Eintrag (/api/sports/<id>) kommt ebenfalls als Liste mit einem Element.

Freie Zeitfenster einer Sportart

Mit Angabe des Standorts (location) enthält die Antwort je Zeitfenster Preisfelder:

curl -X GET "https://<jawengo-url>/api/sports/<sport-id>/availability?location=<location-id>&date=2026-10-12&duration=1" \
     -H "API_KEY: <api-key>"

{
  "sport_id": 89,
  "sport_name": "Tennis",
  "location_id": 164,
  "location_name": "Air Dome",
  "date": "2026-10-12",
  "time_slots": [
    {
      "start": 8.0,
      "end": 9.0,
      "free": 1,
      "price_info": "$ 50.00 / hour",
      "amount": 50.0,
      "discount_amount": 0.0,
      "total_amount": 50.0,
      "discount_info": [],
      "pitches": [{"id": 105, "name": "Court 7"}]
    }
  ]
}

Jedes Zeitfenster hat zusätzlich formatierte Texte wie start_formatted und total_amount_formatted. amount und total_amount sind Zahlen. Ohne location antwortet die Abfrage ebenfalls, aber ohne Preis: amount ist 0 und price_info enthält einen Hinweis, dass der Standort für die Preisangabe fehlt.

Tipp: Fragen Sie die Belegung nicht öfter ab, als Ihre Steuerung schalten muss. Für Licht und Heizung genügt eine Abfrage pro Zeitfenster des Standorts.

Hinweis: Die Adressen mit dem Präfix /api/v1/ liefern dieselben Daten wie die Adressen ohne Präfix.

In diesem Kapitel

• Authentifizierung – Schlüssel einrichten
• Weitere Endpunkte – Übersicht aller Schnittstellen
• Häufige Fragen API – Fehler und Stolperfallen