Coaster API Dokumentation

Einleitung

Willkommen zur Coaster API (kurz: CAPI), die REST API für Freizeitparks. Diese Dokumentation soll dir beim Einstieg unterstützen und erste Fragen beantworten. Bei der Coaster API handelt es sich um eine so genannte Open API, also eine Schnittstelle die kostenlos und ohne Anmeldung genutzt werden kann. Du benötigst daher keine ID, Benutzer oder Passwort um Daten abzufragen. Die zurückgelieferten Daten können frei von dir unter der Create Commons Lizenz CC-BY-ND 4.0 verwendet werden (zb. um deine Webseite, App oder Blog mit technischen Daten zu ergänzen). Informationen zur Lizenz kannst du hier einsehen.

Die Basis

Die API unterstützt aktuell drei Ressourcen: Parks (parks), Attraktionen (attractions) und Logs (logs). Jeder Park und Attraktion hat eine so genannte UUID, welches als Identifier dient. Die UUID ändert sich nie und kann daher fest verwendet werden. Die Basis URL lautet https://coaster-platform.org/api. An dieser Basis URL fügen wir dann die zu abfragende Ressource an. Möchten wir eine Liste von Parks abfragen, lautet die Abfrage https://coaster-platform.org/api/parks - für Attraktionen dementsprechend https://coaster-platform.org/api/attractions.

Das Ergebnis ist paginiert. Die aktuelle Seite kann mit dem Query Parameter page, die Anzahl der Datensätze pro Seite mit itemsPerPage übergeben werden. Bei dieser Abfrage sind wir auf Seite 3 und geben 10 Datensätze pro Seite aus: https://coaster-platform.org/api/attractions?page=3&itemsPerPage=10

Möchten wir einen bestimmten Park oder Attraktion abfragen, hängen wir nach der Ressource noch die UUID an. Der Movie Park hat die UUID a5fb81f1-cc4e-4a7e-8419-98cc523487e3 - daher lautet die URL https://coaster-platform.org/api/parks/a5fb81f1-cc4e-4a7e-8419-98cc523487e3.

Als Rückgabe wird das JSON Format verwendet.

API Limit

Die Coaster API hat ein so genanntes Rate Limit um uns vor Ausnutzung zu schützen und sicherzustellen, dass wir eine große Anzahl an Requests verarbeiten können. Das API Limit wird an der IP Adresse gesetzt und beträgt aktuell 10.000 Requests pro Tag. Sofern du für dein Projekt ein höheres API Limit benötigst kannst du gerne mit uns Kontakt aufnehmen.

Suchen

Du kannst nach Parks und Attraktionen suchen. Dabei wird nicht nur nach dem exakten Wort gesucht sondern auch nach ähnlichen Begriffen bzw. Teilbegriffe - zudem wird die Suche auf mehrere Teile des Datensatzes und nicht ausschließlich auf den Namen beschränkt. Um nach einen Park / Attraktion zu suchen fügst du als Query lediglich ein search=DEIN SUCHWORT an der Ressource an. Die Suche nach "movie park" sieht dann wie folgt aus: https://coaster-platform.org/api/parks?search=movie park

Filtern

Mit dem filter Query Parameter können Parks und Attraktionen gefiltert werden. Einige Beispiele für Filtermöglichkeiten findest du in der rechten Spalte dieser Dokumentation. In folgenden Beispiel erhalten wir alle Attraktionen zurück, die mindesten einen LSM Launch enthalten: https://coaster-platform.org/api/attractions?filter=elements.lsm_launch.quantity > 0

Playground & SDK

Genug Theorie? Dann teste doch einfach die Coaster API auf unserer Spielwiese. Im Playground kannst du Testweise Daten Abfragen und mit der Suche und Filterung spielen. Der Playground führt echte Abfragen an unserer REST API aus und gibt das jeweilige Ergebnis zurück.

Alternative findest du auf Github ein Javascript SDK um Daten aus der REST API noch einfacher laden zu könne.