Stand der Dokumentation: 05.02.2025
Technische Dokumentation des Standard-Importers
Über unsere standardisierte Schnittstelle können wir einfach und zuverlässig täglich aktuelle Veranstaltungsinformationen importieren.
Inhalt
-
-
1.3 Formate
-
1.4 Kodierung
-
1.5 Datentypen
-
-
2.1 Datenmodell
-
2.1.1 Rahmenbedingungen
-
-
2.2 Datenstruktur
-
2.2.1 Veranstaltung
-
2.2.2 Spielstätte
-
-
2.3 Erläuterungen
-
2.3.1 Lizenzen
-
2.3.2 Veranstaltungstermine
-
2.3.3 Kategorien
-
2.3.4 Merkmale
-
2.3.5 Termin-Meta-Tags
-
2.3.6 Veranstaltungsreihen
-
2.3.7 Preise
-
2.3.8 Bilder
-
-
2.4 Datenformat XML
-
4. Downloads
1. Basisinformationen
1.1 Daten bereitstellen
Es gibt zwei Möglichkeiten, die Daten zu übertragen:
- Stellen Sie uns eine URL, ggfs. mit Authentifizierung (Benutzername, Passwort) zur Verfügung, über die wir die Daten abrufen können.
- Legen Sie die Daten per FTP-PUSH auf dem VADB-Server ab
1.2 Daten ändern, löschen, neu anlegen
Damit die Informationen über alle Änderungen korrekt und performant in der VADB ankommen, gibt es folgende Importstrategie:
- Liefern Sie immer alle aktuell gültigen Datensätze aus Ihrem System, versehen mit dem Zeitpunkt der letzten Änderung.
- Der Importer überträgt nur die Daten, die sich seit dem letzten erfolgreichen Import geändert haben, in die VADB.
- Außerdem vergleicht der Importer alle Datensätze in der VADB mit den gelieferten Datensätzen und deaktiviert in der VADB diejenigen Datensätze, die in der Lieferung nicht mehr dabei sind. Damit ist sichergestellt, dass Daten, die aus dem Quellsystem entfernt wurden, auch in der VADB deaktiviert werden.
Fällt es Ihnen schwer, diese Importstrategie zu unterstützen, so wenden Sie sich an Ihre Ansprechpartner bei der Hamburg Tourismus GmbH, um Alternativen zu vereinbaren.
1.3 Formate
Die Daten können in standardisiertem XML in die VADB importiert werden. Bei Downloads befindet sich ein Beispiel.
1.4 Kodierung
Die Dateien müssen im UTF-8-Format geliefert werden.
1.5 Datentypen
In der VADB wird im Wesentlichen mit zwei Objekttypen gearbeitet: Veranstaltungen und Spielstätten
Jede Veranstaltung muss grundsätzlich eine Spielstätte haben. Kann ein Datenlieferant für eine Veranstaltung keine Spielstätten-Informationen bereitstellen, wird beim Import automatisch eine Standard-Spielstätte zugewiesen.
Jeder Datensatz ohne Spielstätte wird von Seiten Hamburg Tourismus vor einer möglichen Freigabe redaktionell geprüft. Die Chancen für eine Veröffentlichung sind gering.
2. Anforderungen
2.1 Datenmodell
Das Datenmodell in der imx.Platform enthält die Objekttypen:
- Veranstaltung (Event)
- Spielstätte (AddressPoi)
2.1.1 Rahmenbedingungen
- Jedes importierte Objekt muss eine systemweit eindeutige Fremd-ID besitzen.
- Jede Veranstaltung muss genau eine Spielstätte haben.
- Jede Veranstaltung muss mindestens einen Termin haben.
- Die Daten können einsprachig (deutsch) oder zweisprachig (deutsch, englisch) übergeben werden.
2.2 Datenstruktur
2.2.1 Veranstaltung (Tabelle nach rechts scrollbar!)
Attribut | Name im xml | Pflicht | Beschreibung / Hinweis |
---|---|---|---|
FremdID | id | Ja | ID des zu importierenden Datensatzes im Quell-System. Die FremdID muss eindeutig im gesamten Datenbestand im Quell-System sein. |
Spielstätte | location.AddressPoi.id | Ja | |
PLZ der Spielstätte |
location.AddressPoi.contact1.address.zipcode | Ja | Die PLZ muß innerhalb der Metropolregion Hamburg liegen. Alle anderen PLZs werden ignoriert. |
Veranstalter | contibutor.AddressPoi.id | Nein | Wird automatisch mit Standard-ID3972 befüllt, da es keine VADB-Veranstalterinfos gibt. |
Titel | title | Ja | |
Beschreibung | shortDescription | Ja | HTML-Formatierung möglich |
Autor | author | Nein | Autor des Beschreibungstextes |
Lizenz | mediaLicense.MediaLicense | Nein | Lizenz-Typ des Beschreibungstextes Siehe Erläuterungen zu den Lizenzen. |
Link zum Event |
link | Nein | Weiterführender Link, der zur Eventbeschreibungsseite des Veranstalters oder Ticketshops führen kann. Es sind nur gültige URLs zugelassen. |
Buchungslink | bookingLink | Nein | Es sind nur gültige URLs zugelassen. |
Kategorie | categories.Category | Ja | Siehe Erläuterungen zu den Kategorien. |
Merkmale | criteria.Criterion | Nein | Siehe Erläuterungen zu den Merkmalen. |
Veranstaltungs- reihe |
series.EventSeries.id | Nein | Bitte erfragen Sie die für Sie relevanten IDs bei der Redaktion. |
Preise | pricing.fromPrice pricing.toPrice pricing.freeOfCharge pricing.priceDescription |
Nein | Siehe Erläuterungen zu Preisen. |
Veranstaltungs- termine |
eventDates.SpecificEventDate.date eventDates.SpecificEventDate.startTime eventDates.SpecificEventDate.duration eventDates.SpecificEventDate.bookingLink eventDates.SpecificEventDate.cancelled eventDates.SpecificEventDate.soldout |
Ja | Es muss mindestens einen Termin geben. Siehe Erläuterungen zu Veranstaltungsterminen. |
Termin-Meta-Tags | Event.eventDates.EventDate.tags.EventDateTag | Nein | Siehe Erläuterungen zu den Termin-Meta-Tags. |
Bilder | media.EventImage media.EventImage.imageType media.EventImage.sortingValue media.EventImage.pooledMedium.PooledEventMedium |
Nein | Siehe Erläuterungen zu Bildern. |
Metadaten zu Bildern |
media.EventImage.pooledMedium.PooledEventMedium.title media.EventImage.pooledMedium.PooledEventMedium.description media.EventImage.pooledMedium.PooledEventMedium.copyright media.EventImage.pooledMedium.PooledEventMedium.altText media.EventImage.pooledMedium.PooledEventMedium.mediaLicense |
copyright ist Pflichtfeld |
Siehe Erläuterungen zu Bildern. |
Abgesagt | cancelled | Nein | true/false |
Erstell-Datum | creationTime | Ja | Voraussetzung für unsere Import-Strategie. |
Änderungs- Zeitstempel |
lastChangeTime | Ja | Voraussetzung für unsere Import-Strategie. |
2.2.2 Spielstätte
Attribut | Name im xml | Pflicht | Beschreibung / Hinweis |
---|---|---|---|
FremdID* | id | Ja | ID des zu importierenden Datensatzes im Quell-System. Die FremdID muss eindeutig im gesamten Datenbestand im Quell-System sein. |
Titel | title | Ja | |
Postleitzahl | contact1.address.zipcode | Ja | Die PLZ muß innerhalb der Metropolregion Hamburg liegen. |
Ort | contact1.address.city | Nein | |
Straße | contact1.address.street | Ja | |
Hausnummer | contact1.address.streetNo | Nein | |
Geo-Koordinaten | geoInfo.GeoInfo.coordinates.latitude geoInfo.GeoInfo.coordinates.longitude |
Nein |
*FremdID Spielstätte
- Achtung, die FremdID darf nur dann aus Ziffern bestehen, wenn eine konkret bekannte bzw. passende ID des Zielsystems verwendet wird. Diese ID erhalten Sie von der Redaktion der VADB.
- Andernfalls muss bei der Verwendung von Ziffern ein Präfix als ID-Zusatz eingesetzt werden, damit nicht fälschlicherweise eine falsche Spielstätte zur Veranstaltung zugeordnet wird. Beispiel: SHMH385
2.3 Erläuterungen
2.3.1 Lizenzen
Bei der Veranstaltung und bei jedem Bild kann ein Lizenztyp wie CC0, CC-BY usw. angegeben werden.
Im Zielsystem gibt es einen vorgegebenen Satz an Lizenztypen:
MediaLicense.id | name |
---|---|
1 | CC0 |
2 | CC-BY |
3 | CC-BY-SA |
2.3.2 Veranstaltungstermine
Jede Veranstaltung muss mindestens einen und kann beliebig viele Termine haben.
Attribut | Name im xml | Pflichtfeld | Format/Einheit |
---|---|---|---|
Datum | date | Ja | 00:00:00 |
Uhrzeit | start Time | Ja | 00:00:00 |
Dauer | duration | Nein | Minuten |
Ausverkauft | soldout | Nein | true/false |
Abgesagt | cancelled | Nein | true/false |
2.3.3 Kategorien
Kategorien dienen der Einteilung von Veranstaltungen. Typische Kategorien sind z.B.:
- Theater
- Festivals
- Klassik
- …
Im Zielsystem gibt es einen vorgegebenen Satz an Veranstaltungskategorien, siehe Liste Veranstaltungskategorien.
Es gibt zwei Varianten für die Übertragung der Kategorien aus dem Quell-System:
- 1) Das Quell-System liefert genau die passenden IDs der VADB (siehe VADB-Kategorienbaum)
- 2) Die Redaktion der VADB erzeugt ein Mapping der Kategorien des Quell-Systems.
- Bitte stellen Sie uns hierfür eine Liste Ihrer Kategorien samt IDs zur Verfügung. Dabei ist es unerheblich, ob die IDs des Quellsystems aus Ziffern bestehen oder nicht.
2.3.4 Merkmale
Merkmale dienen der Klassifizierung von Veranstaltungen zusätzlich zu den Kategorien. Typische Merkmale sind z.B.:
- Kulinarisch
- Speziell für Kinder oder Familien
- Sprache: Englisch
- …
Im Zielsystem gibt es einen vorgegebenen Satz an Veranstaltungsmerkmalen, siehe Liste Veranstaltungsmerkmale.
Es gibt zwei Varianten für die Übertragung der Merkmale aus dem Quell-System:
- 1) Das Quell-System liefert genau die passenden IDs der VADB (siehe VADB-Merkmale)
- 2) Die Redaktion der VADB erzeugt ein Mapping der Merkmale des Quell-Systems.
- Bitte stellen Sie uns hierfür eine Liste Ihrer Merkmale samt IDs zur Verfügung. Dabei ist es unerheblich, ob die IDs des Quellsystems aus Ziffern bestehen oder nicht.
2.3.5 Termin-Meta-Tags
Termin-Meta-Tags dienen der Kennzeichnung von einzelnen Veranstaltungsterminen innerhalb eines Datensatzes. Typische Tags sind z.B.:
- Premiere
- Vernissage
- …
Im Zielsystem gibt es einen vorgegebenen Satz an Termin-Meta-Tags, siehe hier.
05.02.: Das Zielsystem verfügt bereits über diese Tags. Der Event-Import muß für diese Daten noch erweitert werden.
2.3.6 Veranstaltungsreihen
Event-Reihen dienen dazu, die Zusammengehörigkeit von einzelnen Veranstaltungen zu einem großen Programm bzw. einer Aktion zu kennzeichnen.
Bitte erfragen Sie die für Sie relevanten IDs bei der Redaktion.
2.3.7 Preise
In der xml-Schnittstellendatei können folgende Preis-Elemente übergeben werden:
Attribut | Format/Einheit |
---|---|
fromPrice | Zahl |
toPrice | Zahl |
absolutePrice | Zahl |
freeOfCharge | Boolean (true/false) |
priceDescription | Text |
2.3.8 Bilder
Aus der xml-Beispieldatei ergibt sich, wie die Bild-Informationen zu übergeben sind.
- Das Feld imageType.ImageType.id soll immer mit dem Wert 1 (= Standard-Bild) gefüllt werden.
- Das Feld sortingValue kann Werte von 0 bis 10 enthalten und steuert die Reihenfolge der Bilder (0 = Bild an erster Position, usw.)
- Das Feld mediaLicense muss mit der korrekten Lizenz-ID gefüllt werden, siehe Tabelle Lizenzen.
Bilder ohne Copyright werden nicht übernommen.
2.4 Datenformat XML
Grundsätzlich dienen die bereitgestellten Beispiel-Dateien als Referenz und Arbeitsgrundlage.
Die Import-Dateien müssen exakt dieselbe Struktur haben wie die Beispiele.
Enthält eine Import-Datei zusätzliche Strukturelemente, die über die Elemente der Beispiele hinausgehen, so stört das den Import nicht. Diese zusätzlichen Daten werden aber auch nicht importiert.
Die Datenübernahme im XML-Format muss eine zentrale Datei liefern, welche sämtliche relevante Informationen zu den Spielstätten und Veranstaltungen liefert.