API-Dokumentation V1

Grundlegendes

Die API liefert Daten im JSON-Format zurück. Aktuell sind nur lesende Operationen möglich.

Authentifizierung

Die Authentifizierung erfolgt mittels HTTP-Basic bei jeder Anfrage. Die Zugangsdaten (Benutzername & Passwort) entsprechen den hinterlegten Daten eines "API Benutzers", welcher mit einem Benutzer verknüpft ist. Die Berechtigungen des verknüpften Benutzers werden genutzt.

Abfrage

Die Abfrage der Daten erfolgt grundsätzlich via GET.

Parameter

Für Paginierung, Filterung oder Sortierung von Massenabfragen können beliebig viele Parameter an die URL angehangen werden. Die Abfrage eines einzelnen Datensatzes akzeptiert keine Parameter.

Format

Das Zeichenformat ist UTF-8. Dezimaltrennzeichen ist ein Punkt. Datumsformat ist ISO 8601 YYYY-MM-DD oder YYYY-MM-DDTHH:MM:SS (Beispiel: 2022-01-24T14:19:50+01:00).

Paginierung

Bei einer Massenabfrage werden die Daten automatisch limitiert und paginiert.

Standardmäßig ist die Anzahl der Datensätze pro Seite auf 50 gesetzt. Mittels Parameter page[size] (Beispiel: ?page[size]=100) kann die Anzahl zwischen 1 und 200 verändert werden.

Die Navigation durch die einzelnen Seiten erfolgt durch den Parameter page[number] (Beispiel: ?page[number]=2).
Links zu den Seiten werden automatisch unter first_page_url, last_page_url, next_page_url und prev_page_url mit allen gesetzten Parametern zurückgegeben.

Filtern

Bei Massenabfragen können kombinierbare Filter zur Eingrenzung des Ergebnisses als Parameter gesetzt werden.

Standardfilter

Standardfilter werden mittels Parameter filter[feldname] gesetzt (Beispiel: ?filter[event_organizers.id]=13).

ODER-Filter:
Mehrere Werte können durch kommaseparierte Aneinanderreihung gesetzt werden (Beispiel: ?filter[characteristics.id]=1,14,65).

Weiterhin können mehrere Filter gleichzeitig gesetzt und somit kombiniert werden (Beispiel: ?filter[characteristics.id]=1,14,65&filter[event_organizers.id]=13).

Sonderfilter

Während Standardfilter nur Werte 1:1 vergleichen, erfüllen Sonderfilter logische, dynamische Funktionen.
Sonderfilter können immer mit Standardfiltern kombiniert werden. Gewisse Sonderfilter können allerdings nicht mit anderen Sonderfiltern angewandt werden.

UND-Filter:
Normale Feldfilter bilden immer eine ODER-Abfragelogik ab. Um nach Datensätzen zu filtern, welche alle übergebenen Kriterien erfüllen, stehen die Filter characteristic_ids_all (für Eigenschaften), department_ids_all (für Abteilungen) und type_ids_all (für Typen) zur Verfügung.
Hier werden die jeweils abzufragenden IDs kommasepariert aneinandergereiht (Beispiel: ?filter[characteristic_ids_all]=1,14,65).

NICHT-Filter:
Um nach Datensätzen zu filtern, welche nicht mindestens eines der übergebenen Kriterien erfüllen (also diese ausschließen), stehen die Filter characteristic_ids_not (für Eigenschaften), department_ids_not (für Abteilungen) und type_ids_not (für Typen) zur Verfügung.
Hier werden die jeweils abzufragenden IDs kommasepariert aneinandergereiht (Beispiel: ?filter[characteristic_ids_not]=1,14,65).

Feste Zeitfilter:
Feste Zeitfilter sind nicht miteinander kombinierbar und akzeptieren keine Parameter.
current
Liefert nur Daten (z.B. Events), welche aktuell stattfinden.
in_future
Liefert nur Daten (z.B. Events), welche in der Zukunft liegen und noch nicht begonnen haben.
in_future_or_current
Liefert nur Daten (z.B. Events), welche in der Zukunft liegen oder aktuell stattfinden.
in_past
Liefert nur Daten (z.B. Events), welche in der Vergangenheit liegen und bereits beendet sind.
(Beispiel: ?filter[in_future]=1. Achtung: Der Parameter wird nicht beachtet. Der Filter wird angewendet, sobald ein beliebiger Wert vorliegt!)

Dynamische Zeitfilter:
Dynamische Zeitfilter sind miteinander kombinierbar und akzeptieren als Parameter ein Datum oder einen Zeitpunkt.
Filter mit einem Zeitraum benötigen zwei Parameter, welche mit einem Komma separiert werden.
starts_before
Liefert nur Daten (z.B. Events), welche vor dem übergebenen Zeitpunkt beginnen (Beginn).
starts_after
Liefert nur Daten (z.B. Events), welche nach dem übergebenen Zeitpunkt beginnen (Beginn).
starts_between*
Liefert nur Daten (z.B. Events), welche zwischen den übergebenen Zeitpunkten beginnen (Beginn).
ends_before
Liefert nur Daten (z.B. Events), welche vor dem übergebenen Zeitpunkt enden (Ende).
ends_after
Liefert nur Daten (z.B. Events), welche nach dem übergebenen Zeitpunkt enden (Ende).
ends_between*
Liefert nur Daten (z.B. Events), welche zwischen den übergebenen Zeitpunkten enden (Ende).
takes_place_between*
Liefert nur Daten (z.B. Events), welche zwischen den übergebenen Zeitpunkten stattfinden (Beginn vor dem Startzeitpunkt und Ende nach dem Endzeitpunkt oder Beginn/Ende zwischen den Zeitpunkten).
* = Benötigt zwei Parameter: Startzeitpunkt, Endzeitpunkt

(Beispiel: ?filter[starts_after]=2018-05-10T12:30:00&filter[starts_before]=2018-08-08)
(Beispiel: ?filter[takes_place_between]=2018-05-10,2018-08-08)

Dynamischer Positionsfilter:
Der dynamische Positionsfilter geofence kann mit allen anderen Filtern kombiniert werden und liefert Daten (z.B. POIs oder Events) im Umkreis einer gegebenen Geokoordinate.
Als Parameter müssen Breitengrad (latitude), Längengrad (longitude), minimaler Abstand (in km) und maximaler Abstand (in km) gesetzt werden.
Um direkt ab der gegebenen Geokoordinate zu suchen wird 0 als minimaler Abstand gewählt.

(Beispiel: ?filter[geofence]=51.949457,7.639741,0,10.5)

Ist ein Positionsfilter gesetzt, wird im Datensatz das Feld geofence_distance_in_km hinzugefügt, welches die Distanz zu den gewählten Koordinaten in km angibt. Nach diesem Feld kann auch sortiert werden.

Routen-Positionsfilter:
Der Routen-Positionsfilter route_geofence kann mit allen anderen Filtern kombiniert werden und liefert Daten (z.B. POIs oder Events) im Umkreis entlang der Wegpunkte einer gegebenen Route.
Als Parameter müssen ID der Route, minimaler Abstand (in km) und maximaler Abstand (in km) gesetzt werden.
Um direkt ab der gegebenen Route zu suchen wird 0 als minimaler Abstand gewählt.

(Beispiel: ?filter[route_geofence]=6,0,0.5)

Ist ein Positionsfilter gesetzt, wird im Datensatz das Feld geofence_distance_in_km hinzugefügt, welches die Distanz zu der gewählten Route in km angibt. Nach diesem Feld kann auch sortiert werden.

Qualitätsmanagement Filter:
Der erreichte Erfüllungsgrad des Qualitätsmanagements (z.B. für POIs oder Events) kann mit dem Filter quality_score_in_percent_minimum eingeschränkt werden.
Als Parameter wird der minimale Erfüllungsgrad in Prozent gesetzt.

(Beispiel: ?filter[quality_score_in_percent_minimum]=75)

Parent/Child Filter:
Gewisse Datensätze wie POIs haben eine Parent-Child-Verknüpfung, können also einen übergeordneten oder untergeordneten Datensatz haben.
Diese Filter sind nicht miteinander kombinierbar und akzeptieren keine Parameter.
only_parent
Liefert nur Daten (z.B. POIs), die keinen übergeordneten Datensatz haben.
only_child
Liefert nur Daten (z.B. POIs), die einem Datensatz untergeordnet sind.
(Beispiel: ?filter[only_parent]=1. Achtung: Der Parameter wird nicht beachtet. Der Filter wird angewendet, sobald ein beliebiger Wert vorliegt!)

Eigenschaften-Werte Filter:
Gewisse Datensätze wie POIs und Events können "Erweiterte Eigenschaften" mit hinterlegten Werten haben.
Mit dem Filter characteristic_values kann eine Filterung der Datensätze für übergebene Werte vorgenommen werden.
Als Parameter müssen ID der Characteristic (Eigenschaft), Vergleichs-Operator und Wert übergeben werden.

Folgende Vergleichs-Operatoren stehen zur Verfügung:
=
Text-Vergleich "Wert ist".
!=
Text-Vergleich "Wert ist nicht".
~
Text-Vergleich "Wert enthält".
==
Numerischer Vergleich "Wert ist gleich".
<>
Numerischer Vergleich "Wert ist ungleich".
>
Numerischer Vergleich "Wert ist größer".
<
Numerischer Vergleich "Wert ist kleiner".
>=
Numerischer Vergleich "Wert ist größer gleich".
<=
Numerischer Vergleich "Wert ist kleiner gleich".
Bei numerischen Werten ist auch ein Text-Vergleich möglich. Bei textbasierten Werten können nur Operatoren für den Text-Vergleich genutzt werden.
Wahrheitswerte (Boolean) lassen sich per numerischem Vergleich mit == und <> filtern.
Mehrere Filter können kommasepariert übergeben werden. Dabei gilt die UND-Abfragelogik.

(Beispiel: ?filter[characteristic_values]=12==1)
(Beispiel: ?filter[characteristic_values]=12>=12)
(Beispiel: ?filter[characteristic_values]=12<=12,33<>234.4)

Sortieren

Die Sortierung einer Massenabfrage kann mittels Parameter sort für angegebene Felder (diese entsprechen den verfügbaren Standardfiltern) manuell gesetzt werden.
(Beispiel: ?sort=events.name)

Um die Sortierreihenfolge zu negieren wird ein "-" (Minus) vor das zu sortierende Feld gesetzt. (Beispiel: ?sort=-events.name)

Mehrere Felder können kommasepariert, nach absteigender Sortierrangfolge, gesetzt werden. (Beispiel: ?sort=events.start_datetime,poi.name)

Zusätzliche Daten anhängen

Bei einigen Abfragen können mittels Parameter append zusätzliche Daten bzw. Relationen der Datensätze angehangen werden.
(Beispiel: ?append=public_media)

Mehrere Daten können kommasepariert gesetzt werden. (Beispiel: ?append=public_media,public_events,all_translations_grouped)

Achtung: Daten sollten für eine bessere Performance immer nur dann angehangen werden, wenn dies wirklich notwendig ist!

Übersetzungen

Einige Felder der Datensätze können in diverse Sprachen übersetzt werden.

Verfügbare Übersetzungs-Sprachen können unter dem Endpunkt
https://www.datenportal-muensterland.de/api/v1/translation_languages
abgerufen werden.

Mittels Parameter ?append=all_translations_grouped können alle Übersetzungen angehangen werden.
Die Übersetzungen sind unter all_translations_grouped, gruppiert nach ISO-Code der jeweiligen Übersetzungs-Sprache aufgeführt.

Achtung: Übersetzungen sollten für eine bessere Performance immer nur dann angehangen werden, wenn dies wirklich notwendig ist!

Endpunkte für Daten

Weitere Endpunkte