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.

Integration / Shop (Integration)

Status: noch nicht unterstützt

Partner (Affiliate)

Bei einer Partner-Eigenschaft kann der Wert auf true oder false gesetzt werden. Außerdem kann ein individueller Link hinterlegt werden, ansonsten wird der globale Link der Eigenschaft verwendet.

Das JSON für den Wert muss wieder als String verpackt werden, enthält aber nur die zwei Eigenschaften IndividualLink  und Value:

{
    "Name": "Partnereigenschaft",
    "Type": "Affiliate",
    "Value": "{\"IndividualLink\":\"https://an-individual-link.com\",\"Value\":true}"
}

Liste (CompoundList)

Status: noch nicht unterstützt (wg. Dateien)

Audio/Video einbetten (EmbeddedMedia)

Das JSON für den Wert muss wieder als String verpackt werden:

{
    "Name": "Partnereigenschaft",
    "Type": "Affiliate",
    "Value": "{\"EmbeddedMediaItems\":[{\"ItemId\":1,\"Description\":\"Tiny desk concert Fred again...\",\"Source\":\"https://www.youtube.com/watch?v=4iQmPv_dTI0\"}],\"ValueForNotSelected\":null,\"HighestUsedItemId\":1}"
}

Hier wird eine Liste von eingebettenen Medien als Wert übergeben. Wenn „nicht verfügbar“ eingestellt werden soll (s. weiter unten), dann kann das über die Property ValueForNotSelected erfolgen.
Die Medien bekommen als ID einfach aufsteigende Werte. Und als HighestUsedItemId wird dann einfach die höchste ID angegeben.

Hintergrund: die IDs sind primär auf Portalen relevant, die mindestens zwei Sprachen verwenden. Um die Textbausteine in anderen Sprachen eindeutig zuordnen zu können, bekommt jedes Medien-Item eine eindeutige ID. Falls Medien gelöscht werden, stellt die höchste ID sicher, dass neue Medien, die über die Eintrag-Editieren-Seite hinzugefügt werden, keine ID bekommen, die schon existiert hat. Ansonsten würde evtl. ein Sprachbaustein in einer anderen Sprache diesem Video fälschlicherweise zugeordnet werden. Auf den meisten Portalen reicht es wahrscheinlich, hier über die API einfach konsistente Werte neu zu generieren.

Dokumente (DocumentUpload)

Status: noch nicht unterstützt (wg. Dateien)

Verknüpfungen mit Einträgen (EntryReference)

Status: noch nicht unterstützt

Datum (Date)

Status: noch nicht unterstützt

Dieser Eigenschaftstyp wird nur für das Ablaufdatum verwendet (auf Anzeigenportalen)

Spezialfall für „nicht verfügbar“

Bei den meisten Eigenschaftstypen kann ein Text für nicht verfügbar in der Eigenschaftsverwaltung im Portalmanagement hinterlegt werden:

Bei den Eigenschaften steht dann die Auswahl des angegebenen Texts als Alternative zur Verfügung. Wenn dieser Wert ausgewählt wurde, dann enthält Value in der Eigenschaft die Konstante „NOT_AVAILABLE“.

{
  "Name": "OnlineBuchung",
  "Type": "CustomCallToActionLink",
  "Value": "NOT_AVAILABLE"
}

Löschen von Eigenschaften

{
  "Name": "ExternerLink",
  "Type": "Link",
  "Value": null
}

Um eine Eigenschaft zu leeren, kann der Wert auf null gesetzt werden oder ein Leerstring übergeben werden („“).