Eintrags-API: Eigenschaften

Die Entries API unterstützt bisher die wichtigsten Eigenschaftstypen.

Grundsätzlicher Aufbau

Die Eigenschaften sind ein Array einzelner Eigenschaften. Zu jeder Eigenschaft gibt es die drei Felder Name, Type und Value. Der Name ist die Propertybezeichnung im Code, also ohne Leerzeichen, Sonderzeichen, etc. Diese Bezeichnung ändert sich nicht, auch wenn sich der Anzeigename im Portal angepasst wird – die API-Struktur bleibt verlässlich.

Eigenschaftstypen

Hier werden die unterstützten Eigenschaftstypen aufgelistet mit einer kurzen Beschreibung des erwarteten Formats. Die englischen Bezeichnungen in Klammern entsprechen den Eigenschaftstypen, so wie sie in der API verwendet werden.

Vorhanden Ja / Nein (Available)

Bei dieser Eigenschaft kann der Wert „true“ oder „false“ sein.

{ 
  "Name": "barrierefrei", 
  "Type": "Available", 
  "Value": "true" 
}

Text (Text)

Bei Texteigenschaften wird der Wert einfach als string angegeben.

{
  "Name": "Description",
  "Type": "Text",
  "Value": "This is the description."
}

Hierbei muss man beachten, dass bei Text-Eigenschaften eine maximale Länge festgelegt sein kann. Diese wird z. B. auf der Eintrag-Editieren Seite bei dem jeweiligen Feld angezeigt:

Link (Link)

Bei Link-Eigenschaften wird der Wert einfach als string angegeben.

{
  "Name": "ExternerLink",
  "Type": "Link",
  "Value": "https://mein-link.de"
}

Individueller Button (CustomCallToActionLink)

Das Format ist das gleiche wie bei normalen Links.

{
  "Name": "OnlineBuchung",
  "Type": "CustomCallToActionLink",
  "Value": "https://buchen-plattform.de/hier-buchen"
}

Zahl (Number)

Bei Zahleigenschaften wird der Wert einfach als string angegeben. Der Wert „999999999999“ entspricht im discoverize Portal dem Maximalwert (je nach Kontext oft als „unbegrenzt“ gebraucht). Der Wert „-999999999999“ entspricht „nicht vorhanden“. Der Wert „0“ kann je nach Konfiguration im Portal auf Eintragsseiten besonders dargestellt werden, z.B. als „vor Ort“.

{
  "Name": "Entfernung",
  "Type": "Number",
  "Value": "1.5"
}

Mehrfachauswahl (MultipleChoice)

Bei Mehrfachauswahl-Eigenschaften werden die aktiven Optionen durch „,,“ (zwei Kommas) getrennt angegeben.

{
  "Name": "KulturelleEinrichtung",
  "Type": "MultipleChoice",
  "Value": "Kino,,Konzert"
}

Kategorie (Category)

Bei einer Kategorie-Eigenschaft kann immer nur eine Option ausgewählt sein. Der Text der Option wird als Wert verwendet.

{
  "Name": "Anrede",
  "Type": "Category",
  "Value": "Frau"
}

Saisonale Öffnungszeiten (OpeningPeriodsInfo)

Der Wert dieser Eigenschaften ist ein als String codiertes JSON-Konstrukt des OpeningPeriodsInfo Objekts. Die saisonalen Perioden, in denen der Eintrag geöffnet ist, sind eine Liste von StartDate–EndDate-Paaren. Bei den Datums-Zeit-Angaben sind nur Monat und Tag entscheidend – der Rest ist mit Standardwerten befüllt (1900 für Jahr, 0 Uhr für Zeit). Falls der Eintrag im gesamten Kalenderjahr offen ist, so ist IsAlwaysOpen:true.

{
  "Name": "SaisonaleFfnungszeiten",
  "Type": "OpeningPeriodsInfo",
  "Value": "{\"OpeningPeriods\":[{\"StartDate\":\"1900-03-12T00:00:00\",\"EndDate\":\"1900-09-17T00:00:00\"},{\"StartDate\":\"1900-01-01T00:00:00\",\"EndDate\":\"1900-01-07T00:00:00\"}],\"IsAlwaysOpen\":false,\"IsAlwaysClosed\":false,\"IsNotAvailable\":false}"
}

Tägliche Öffnungszeiten (DailyOpeningHours)

Der Wert dieser Eigenschaften ist ein als String codiertes JSON-Konstrukt des DailyOpeningHours Objekts. Das JSON ist eine Liste von Wochentagen (OpeningHoursOnMondays, …, OpeningHoursOnSundays) und einem Platzhalter für Feiertage (OpeningHoursOnHolidays). Jeder dieser Tage ist analog zum OpeningPeriodsInfo Objekt aufgebaut: Die Zeitblöcke, während derer der Eintrag offen hat, sind eine Liste von StartDate–EndDate-Paaren. Bei den Datums-Zeit-Angaben ist nur die Uhrzeit entscheidend – der Rest ist mit Standardwerten befüllt (1.1.1900 für Datum). Alternativ zu Zeitblöcken kann auch angegeben, dass der Eintrag an diesen Tagen durchgehen geöffnet ist (IsAlwaysOpen:true) oder durchgehend geschlossen hat (IsAlwaysClosed:true).

{
  "Name": "OpeningHours",
  "Type": "DailyOpeningHours",
  "Value": "{\"OpeningHoursOnMondays\":{\"OpeningPeriods\":[],\"IsAlwaysOpen\":true,\"IsAlwaysClosed\":false,\"IsNotAvailable\":false},\"OpeningHoursOnTuesdays\":{\"OpeningPeriods\":[{\"StartDate\":\"1900-01-01T08:00:00\",\"EndDate\":\"1900-01-01T12:00:00\"},{\"StartDate\":\"1900-01-01T14:00:00\",\"EndDate\":\"1900-01-01T18:00:00\"}],\"IsAlwaysOpen\":false,\"IsAlwaysClosed\":false,\"IsNotAvailable\":false},\"OpeningHoursOnWednesdays\":{\"OpeningPeriods\":[],\"IsAlwaysOpen\":true,\"IsAlwaysClosed\":false,\"IsNotAvailable\":false},\"OpeningHoursOnThursdays\":{\"OpeningPeriods\":[],\"IsAlwaysOpen\":true,\"IsAlwaysClosed\":false,\"IsNotAvailable\":false},\"OpeningHoursOnFridays\":{\"OpeningPeriods\":[{\"StartDate\":\"1900-01-01T01:00:00\",\"EndDate\":\"1900-01-01T23:00:00\"}],\"IsAlwaysOpen\":false,\"IsAlwaysClosed\":false,\"IsNotAvailable\":false},\"OpeningHoursOnSaturdays\":{\"OpeningPeriods\":[],\"IsAlwaysOpen\":false,\"IsAlwaysClosed\":true,\"IsNotAvailable\":false},\"OpeningHoursOnSundays\":{\"OpeningPeriods\":[],\"IsAlwaysOpen\":false,\"IsAlwaysClosed\":true,\"IsNotAvailable\":false},\"OpeningHoursOnHolidays\":{\"OpeningPeriods\":[],\"IsAlwaysOpen\":false,\"IsAlwaysClosed\":true,\"IsNotAvailable\":false},\"IsNotAvailable\":false}"
}

Veranstaltung (Event)

Events bestehen aus Listen von Datums-Intervallen mit jeweils einem Titel. Diese können jeweils ein bis mehrere Intervalle mit Uhrzeiten und einem Detail-Text enthalten. Alternativ kann das Event auch „ganztags“ stattfinden. Dann können keine Uhrzeiten angegeben werden.

Die Uhrzeiten bestehen nur aus Stunden und Minuten (z. B. „13:30“). Die Datumsintervalle enthalten nur das Datum selbst (ohne Uhrzeit), also z. B. „2022-05-31“.

Beispiel für ein Event mit zwei Datums-Intervallen. Im ersten Teil des Events besteht das Event aus zwei Blöcken mit Uhrzeiten. Im zweiten Teil wird keine Uhrzeit angegeben, sondern nur der Zustand „ganztags“. Der Screenshot zeigt die Veranstaltung im Editor im Portalmanagement:

Das JSON für den Wert muss wieder als String verpackt werden (im JSON für ganztägige Veranstaltungen können leere TimePeriods gelistet sein):

{ 
   "Name": "Event", 
   "Type": "Event", 
   "Value": "{\"EventDates\":[{\"ItemId\":1,\"HighestUsedItemId\":2,\"Title\":\"Wochenend-Workshop I\",\"StartDate\":\"2022-04-30\",\"EndDate\":\"2022-05-01\",\"IsAllDay\":false,\"TimePeriods\":[{\"ItemId\":1,\"StartTime\":\"10:00\",\"EndTime\":\"12:00\",\"Details\":\"Vormittagssession\"},{\"ItemId\":2,\"StartTime\":\"14:00\",\"EndTime\":\"17:00\",\"Details\":\"Nachmittagssession\"}]},{\"ItemId\":2,\"HighestUsedItemId\":1,\"Title\":\"Wochenend-Workshop Teil II\",\"StartDate\":\"2022-05-06\",\"EndDate\":\"2022-04-10\",\"IsAllDay\":true,\"TimePeriods\":[]}],\"HighestUsedItemId\":2}"
}

ItemId und HighestUsedItemId

Die Datumsintervalle und auch die möglicherweise enthaltenen Zeitintervalle mit Uhrzeiten enthalten jeweils IDs (ItemId). Diese sind notwendig, um die zugeordneten Textbausteine eindeutig zu markieren. Das ist wichtig für Mehrsprachigkeit: damit können übersetzte Texte von Events immer mit dem Original-Baustein in der Originalsprache zugeordnet werden und auch den passenden Uhrzeiten. Deswegen gibt es auch die Property „HighestUsedItemId“. Diese wird beim Editieren im Portalmanagement automatisch befüllt und aktualisiert gehalten, damit beim Löschen von Intervallen und späterem Neu-Hinzufügen keine alten Übersetzungen fälschlicherweise dem neuen Intervall zugeordnet werden. Auf Portalen, die keine Mehrsprachigkeit unterstützen (sollen), sind diese Eigenschaften zwar theoretisch nicht so wichtig, jedoch könnte es beim Fehlen bzw. falschen IDs evtl. zu Problemen mit dem Editor im Portalmanagement kommen. In einer späteren Version der API werden diese Werte evtl. aus der Schnittstelle entfernt und beim Lesen/Schreiben über die API entsprechend aktualisiert.