Datenschnittstelle für Inhalte

Inhalte (Ad-Hoc-Datenendpunkte)

Flexible Datenendpunkte für verschiedene Inhaltstypen und Anwendungsfälle.

Verfügbare Endpunkte

Datenschnittstelle für Inhalte - Grundlegende Inhaltsverwaltung
Autovervollständigung - Intelligente Suchvorschläge
Höhenprofile - Topografische Daten
GeoJSON - Geografische Datenformate
Vector Tiles - Vektorkarten für Mapping

ℹ️ Hinweis: Diese Dokumentation verwendet die dataCycle-Schnittstelle in der Version v4.

🚀 Einstieg in die Datenschnittstelle

In dataCycle gibt es zwei Möglichkeiten, Inhalte über die Datenschnittstelle verfügbar zu machen:

Statische Inhaltssammlungen: Manuell ausgewählte, festgelegte Inhalte
Dynamische Inhaltssammlungen: Automatisch generiert basierend auf Filterkriterien

Beide Sammlungstypen werden über ein einheitliches URL-Schema bereitgestellt. Die konkrete URL kann in der Benutzeroberfläche kopiert werden.

🔎 Filtern von Inhalten

Beispiel für eine Filterung nach Klassifizierung:

HTTP-GET

GET /api/v4/endpoints/ffa78ef5-6e6a-47fa-a817-a771390d48dc?token=YOUR_ACCESS_TOKEN&filter[classifications][in][withSubtree][]=3b9b4787-99e5-47c1-8d09-db65c1db43cc

HTTP-POST

{
  "token": "YOUR_ACCESS_TOKEN",
  "filter": {
    "classifications": {
      "in": {
        "withSubtree": ["3b9b4787-99e5-47c1-8d09-db65c1db43cc"]
      }
    }
  }
}

Hinweis: Filterparameter müssen exakt den Vorgaben entsprechen (Array vs. String).

🔄 Volltextsuche

Beispiel für eine Suche nach “Musik”:

HTTP-GET

GET /api/v4/endpoints/ffa78ef5-6e6a-47fa-a817-a771390d48dc?token=YOUR_ACCESS_TOKEN&filter[q]=Musik

HTTP-POST

{
  "token": "YOUR_ACCESS_TOKEN",
  "filter": {
    "q": "Musik"
  }
}

🧩 Klassifizierungen - filter[classifications]

Möglichkeiten der Klassifizierungsfilterung:

Parameter	Beschreibung
`filter[classifications][in][withSubtree][]`	Inhalte müssen mit Klassifizierung oder Sub-Klassifizierung verknüpft sein
`filter[classifications][in][withoutSubtree][]`	Nur direkte Klassifizierung (ohne Sub-Klassifizierungen)
`filter[classifications][notIn][withSubtree][]`	Ausschluss von Klassifizierung oder Sub-Klassifizierung
`filter[classifications][notIn][withoutSubtree][]`	Ausschluss nur direkter Klassifizierung

Beispiel: Galerien oder Museen, barrierefrei, ohne moderne Kunst

{
  "token": "YOUR_ACCESS_TOKEN",
  "filter": {
    "classifications": {
      "in": {
        "withSubtree": [
          "b482d10a-8101-45aa-80e7-1a74884f5401,28505016-25d9-4ed8-a8ab-fc432a46e1af",
          "a1a626c2-3324-4118-b71b-aaecd10bd775"
        ]
      },
      "notIn": {
        "withSubtree": ["cae91ec2-7b32-44e2-ad99-26c5d1fe7ff5"]
      }
    }
  }
}

📅 Attribute - filter[attribute]

Filterung nach numerischen Attributen wie Erstellungsdatum oder Veranstaltungstermin.

Beispiel: Veranstaltungen im Herbst/Winter, außer Weihnachtsfeiertage

{
  "token": "YOUR_ACCESS_TOKEN",
  "filter": {
    "attribute": {
      "eventSchedule": {
        "in": {
          "min": "2020-09-23",
          "max": "2021-03-20"
        },
        "notIn": {
          "min": "2020-12-24",
          "max": "2021-01-06"
        }
      }
    }
  }
}

🔄 Aktualisierungen - filter[attribute][dct:created|dct:modified|dct:deleted]

Spezielle Attribute für Änderungshistorie:

dct:created - Erstellungsdatum
dct:modified - Änderungsdatum
dct:deleted - Nur über /api/v4/things/deleted Endpunkt

Beispiel: Am 21. Oktober 2015 erstellte Inhalte

{
  "token": "YOUR_ACCESS_TOKEN",
  "filter": {
    "attribute": {
      "dct:created": {
        "in": {
          "min": "2015-10-21",
          "max": "2015-10-21"
        }
      }
    }
  }
}

📅 Termine - filter[attribute][eventSchedule]

Spezialfilter für Veranstaltungstermine mit optimierter Sortierung.

Beispiel: Space Shuttle Mission Juli 2011

{
  "token": "YOUR_ACCESS_TOKEN",
  "filter": {
    "attribute": {
      "eventSchedule": {
        "in": {
          "min": "2011-07-10",
          "max": "2011-07-19"
        }
      }
    }
  }
}

📊 ContentScore (dataCycle) - filter[attribute][internalContentScore]

Gibt es Inhalte mit einem ContentScore (dataCycle), können diese auch darüber gefiltert werden.

{
  "token": "YOUR_ACCESS_TOKEN",
  "filter": {
    "attribute": {
      "internalContentScore": {
        "in": {
          "min": 80,
          "max": 100
        }
      }
    }
  }
}

🌍 Geobasierte Filterung - filter[geo]

Filterung nach geografischen Kriterien.

📍 Bounding-Box

{
  "token": "YOUR_ACCESS_TOKEN",
  "filter": {
    "geo": {
      "in": {
        "box": [9.530748, 46.372268, 17.160776, 49.020530]
      }
    }
  }
}

⭕ Umkreissuche

{
  "token": "YOUR_ACCESS_TOKEN",
  "filter": {
    "geo": {
      "in": {
        "perimeter": [12.69390, 47.07453, 50000]
      }
    }
  }
}

🔗 Graphbasierte Filterung - filter[linked]

Filterung über Inhaltsverknüpfungen.

{
  "token": "YOUR_ACCESS_TOKEN",
  "filter": {
    "linked": {
      "location": {
        "contentId": {
          "in": ["d419e7bf-1dc6-4689-8e2b-b6e689f81f73"]
        }
      }
    }
  }
}

🔀 Sortieren von Inhalten

Implizites (automatisches) Sortieren von Inhalten

Je nachdem, welche Filter beim Abfragen von Inhalten verwendet werden, kann in speziellen Fällen automatisch eine passende Sortierung angewendet werden. Sollen beispielsweise Veranstaltungen für einen bestimmten Zeitraum abgefragt werden, können diese auf Basis des Veranstaltungstermins sortiert werden. Ist eine der in weiterer Folge beschriebenen Sortierungen anwendbar, wird diese automatisch verwendet. Eine manuelle Auswahl der impliziten Sortiermethoden ist nicht möglich. Der Grund dafür ist, dass es sich dabei um Sortierungen handelt, die nur in einem sehr speziellen Kontext sinnvoll angewendet werden können und einen oder mehrere Referenzwerte (z.B. einen Zeitraum) benötigen.

Relevanzbasierte Sortierung

Bei der Volltextsuche werden verschiedene Attribute mit unterschiedlichen Gewichtungen berücksichtigt. Auf Basis der gefundenen Treffer und der jeweiligen Gewichtungen wird eine relevanzbasierte Sortierung durchgeführt. Neben den offensichtlichen Text-Attributen werden auch Klassifizierungen bei der Volltextsuche berücksichtigt. Außerdem werden alle Attribute und nicht nur diejenigen, die über den Parameter fields angefragt werden, sowohl bei der Volltextsuche als auch bei der relevanzbasierten Sortierung berücksichtigt. Diese beiden Punkte sollten immer im Hinterkopf behalten werden, falls eine Sortierung auf den ersten Blick nicht passend erscheint.

Terminbasierte Sortierung

Werden Inhalte auf Basis von Terminen gefiltert (z.B. bei Veranstaltungen), erscheint eine Sortierung auf Basis des Startzeitpunktes eines Termins als optimal. Diese Art der Sortierung führt allerdings dazu, dass Termine mit einer sehr langen Dauer (z.B. Wochen oder Monate) und einem Startzeitpunkt in der Vergangenheit nach vorne gereiht werden. Dieses Verhalten ist im Regelfall nicht wünschenswert! Deshalb berücksichtigt die terminbasierte Sortierung neben dem Startzeitpunkt auch das Ende und in gewisser Weise auch die Dauer eines Termins.

Manuelle Sortierung für Inhaltssammlungen

Bei Inhaltssammlungen gibt es die Möglichkeit, über die Benutzeroberfläche eine manuelle Sortierung festzulegen. Wenn diese Sortierung ausgewählt wird, werden Inhaltssammlungen standardmäßig in dieser manuellen Reihenfolge ausgegeben.

Explizites (benutzerdefiniertes) Sortieren von Inhalten

Neben den automatisch angewendeten impliziten Sortierungen, gibt es die Möglichkeit direkt beim Abrufen der Inhalte über die API, eine explizite, benutzerdefinierte Sortierung festzulegen. Soll eine solche explizite Sortierung verwendet werden, weil z.B. für die abgefragten Inhalte keine der verfügbaren impliziten Sortierungen angewendet werden kann oder weil die implizite Sortierung nicht das gewünschte Ergebnis liefert, muss diese über den Parameter sort übergeben werden. Inhalte können dabei sowohl auf- als auch absteigend sortiert werden. Die Richtung kann über ein Voranstellen eines Plus- bzw. Minuszeichens festgelegt werden, wobei die aufsteigende Sortierung (+) als Standard verwendet wird.

Beispiel: Aufsteigende Sortierung nach Erstellungsdatum

HTTP-POST:

{
  "token": "YOUR_ACCESS_TOKEN",
  "sort": "dct:created"
}

HTTP-GET:

GET /api/v4/endpoints/ffa78ef5-6e6a-47fa-a817-a771390d48dc?token=YOUR_ACCESS_TOKEN&sort=dct:created

Verfügbare Sortierattribute

Die Attribute, die für die Sortierung nutzbar sind, können pro Installation individuell eingeschränkt werden. Prinzipiell stehen aber die folgenden Attribute zur Verfügung:

dct:created - Erstellungsdatum
dct:modified - Änderungsdatum
name - Name/Titel
default - Standardsortierung

Zufallssortierung

Neben den beiden bereits beschriebenen Möglichkeiten zum Sortieren von Inhalten, gibt es auch eine Möglichkeit um Inhalte in zufälliger Reihenfolge abzufragen. Ein möglicher Anwendungsfall dafür wäre beispielsweise, wenn aus einer großen Anzahl von Inhalten bei jedem Zugriff fünf zufällige Inhalte ausgewählt werden sollen.

{
  "token": "YOUR_ACCESS_TOKEN",
  "sort": "random",
  "page": {
    "size": 5
  }
}

⚠️ ACHTUNG: Der Zufallsgenerator wird bei jeder Abfrage zurückgesetzt! Es ist daher möglich, dass bei einer Abfrage über mehrere Seiten Inhalte doppelt ausgeliefert werden können. Um sicherzugehen, dass jeder Inhalt nur genau einmal ausgeliefert wird, sollte nur eine Seite mit einer passenden Seitengröße abgefragt werden.

Zusammengefasst

Mit der dataCycle-Datenschnittstelle kannst du ganz einfach genau die Inhalte finden, die du brauchst – egal ob Artikel, Veranstaltungen, Orte oder Bilder. Die API ist sehr flexibel und lässt sich mit Filtern, Suchbegriffen und Sortierungen genau an deine Wünsche anpassen.

Das Wichtigste auf einen Blick:

Statische und dynamische Inhaltssammlungen: Du kannst entweder eine feste Auswahl von Inhalten bereitstellen (z.B. eine bestimmte Liste von Artikeln), oder du lässt dir immer automatisch die passenden Inhalte anzeigen – je nachdem, welche Filter du setzt.
Filtern: Du kannst Inhalte nach fast jedem Kriterium filtern – zum Beispiel nach Kategorien (Klassifizierungen), nach bestimmten Eigenschaften wie Datum, nach Orten (Geodaten), nach einem Bewertungsscore oder sogar nach Verknüpfungen zu anderen Inhalten.
Volltextsuche: Mit dem Filter q findest du Inhalte, die einen bestimmten Suchbegriff enthalten – das funktioniert wie bei einer Suchmaschine.
Kombinieren: Du kannst mehrere Filter gleichzeitig verwenden, um sehr gezielt zu suchen. Zum Beispiel: „Alle Veranstaltungen im Herbst, die barrierefrei sind und nicht das Thema moderne Kunst haben“.
Sortieren: Du kannst die Reihenfolge der Ergebnisse bestimmen – zum Beispiel nach Erstellungsdatum, Name, Relevanz, Termin oder sogar zufällig.
Manuelle und automatische Sortierung: Je nach Endpunkt und Filter werden Inhalte automatisch sinnvoll sortiert (z.B. Termine nach Datum). Du kannst aber auch selbst festlegen, nach welchem Feld sortiert werden soll.
Zufallssortierung: Wenn du zum Beispiel fünf zufällige Inhalte anzeigen willst, geht das mit sort: “random” und einer passenden Seitengröße.
Geobasierte Filter: Du kannst gezielt nach Inhalten in einem bestimmten Umkreis, einer Region oder innerhalb von bestimmten Flächen suchen.
Antworten im JSON-Format: Die Ergebnisse sind immer strukturiert und maschinenlesbar, sodass du sie einfach weiterverarbeiten kannst – zum Beispiel für Webseiten, Apps oder Auswertungen.

Warum ist das praktisch?

Du kannst für deine Nutzer:innen dynamische Listen, Suchfunktionen oder Kartenansichten bauen, die immer aktuell sind.
Du kannst Inhalte für spezielle Kampagnen, Übersichten oder Auswertungen gezielt zusammenstellen.
Du sparst Zeit, weil du nicht manuell suchen oder sortieren musst – die API liefert dir genau das, was du brauchst.

So startest du am besten:

Probiere die Beispiel-Filter und -Sortierungen aus – entweder im Browser, mit Postman oder mit curl auf der Kommandozeile.
Passe die Filter an deine eigenen Anforderungen an (z.B. andere Kategorien, Zeiträume oder Orte).
Nutze die Sortierung, um die Ergebnisse für deine Anwendung optimal aufzubereiten.
Wenn du spezielle Fragen hast, schau in die Tabelle mit den Filtermöglichkeiten oder frage dein Team.

Tipp: Wenn du einmal nicht weiterkommst oder ein Filter nicht wie erwartet funktioniert, prüfe die genaue Schreibweise und die Struktur der Filter-Objekte – oft liegt es an einem kleinen Tippfehler oder daran, ob ein Wert als Array oder String übergeben werden muss.

Mit diesen Möglichkeiten kannst du die Inhalte in dataCycle flexibel, schnell und gezielt nutzen – für jede Anwendung, die du dir vorstellen kannst!