API-Dokumentation V1

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.

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 bzw. gültig sind.

in_future

Liefert nur Daten (z.B. Events), welche in der Zukunft liegen und noch nicht begonnen haben bzw. noch nicht gültig sind.

in_future_or_current

Liefert nur Daten (z.B. Events), welche in der Zukunft liegen oder aktuell stattfinden bzw. gültig sind.

in_past

Liefert nur Daten (z.B. Events), welche in der Vergangenheit liegen und bereits beendet bzw. nicht mehr gültig 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) bzw. gültig sind.

starts_after

Liefert nur Daten (z.B. Events), welche nach dem übergebenen Zeitpunkt beginnen (Beginn) bzw. gültig sind.

starts_between*

Liefert nur Daten (z.B. Events), welche zwischen den übergebenen Zeitpunkten beginnen (Beginn) bzw. gültig sind.

ends_before

Liefert nur Daten (z.B. Events), welche vor dem übergebenen Zeitpunkt enden (Ende) bzw. gültig sind.

ends_after

Liefert nur Daten (z.B. Events), welche nach dem übergebenen Zeitpunkt enden (Ende) bzw. gültig sind.

ends_between*

Liefert nur Daten (z.B. Events), welche zwischen den übergebenen Zeitpunkten enden (Ende) bzw. gültig sind.

takes_place_between*

Liefert nur Daten (z.B. Events), welche zwischen den übergebenen Zeitpunkten stattfinden oder gültig sind (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.

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

(Beispiel: ?filter[public_transport_line_geofence]=124,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 ÖPNV-Linie 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 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)

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)

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!