Basisdaten-API

Die Basisdaten-API ist ein jüngerer Ableger der Eintrags-API. Über diese werden immer alle vohandenen aktiven Einträge eines Portals zurückgegeben. Daten können über die API nicht verändert werden, es ist also eine Schnittstelle nur zum Lesen von Daten.

Aktivierung der API

Die API kann jederzeit durch den Support aktiviert werden.

Unter Einstellungen > API Einstellungen wird dann ein automatisch generierter API-Key angezeigt, den man als Portalbetreiber dem Nutzer der API mitteilen kann. Dieser kann jederzeit auch verändert werden, z. B. bei Missbrauch. Nach Änderung ist ab sofort nur noch der neue Key gültig.

Auf Wunsch kann diese API natürlich auch jederzeit wieder deaktiviert werden. Temporär kann man auch einfach einen neun Token vergeben, um Zugriffe auf die API sofort zu unterbinden.

Nutzung der API

Die API hat ihren Endpunkt auf dem jeweiligen Portal unter „/basic-entries/v1“. Um auf die API zuzugreifen, muss ein GET-Request mit einem X-Auth-Token im Header des Aufrufs abgesetzt werden, der Value ist der Token, den der Portalbetreiber festlegen kann bzw. der beim Aktivieren der API automatisch erstellt wurde.

Aufbau der Daten

Die API gibt alle veröffentlichten Einträge auf dem Portal zurück im JSON-Format. Auf der obersten Ebene handelt es sich um ein Array, das Einträge enthält. Diese bestehen aus Basisdaten wie der ID eines Eintrags und Erstell- und Änderungsdatum. Außerdem enthält jeder Eintrag eine Liste mit befüllten Eigenschaften.

Der Name einer Eigenschaft wird normalerweise nur beim Anlegen einer Eigenschaft angelegt und bleibt für immer unverändert. Der DisplayText, also der Anzeigetext dieser Eigenschaft kann sich jedoch ändern.

Das Format der Eigenschaftstypen (also das jeweilige Value-Feld) ist identisch mit dem der Eintrags-API und es wird dort auf der Seite Eintragstypen beschrieben. Die Übersetzungen der Eigenschaften erfolgt jedoch nur hier in der Basisdaten-API.

Die Liste der Einträge wird jede Nacht aktualisiert, d.h. die Daten über die API sind immer nur tagesaktuell. Diese können also in Einzelfällen von den aktuellen Daten im Portal abweichen, wenn diese am gleichen Tag bereits geändert worden sind. Es können hier auch noch Einträge zurückgeben werden, die evtl. bereits deaktiviert sind bzw. Einträge fehlen, die erst am gleichen Tag angelegt oder aktiviert worden sind.

[
    {
        "EntryId":150463,
        "ModifiedDate":"2023-11-21T14:05:54",
        "CreatedDate":"2023-10-18T15:59:02",
        "Url":"http://discoverize/yoga/bozena-anna-bartnik",
        "NumberOfRatings":1,
        "AverageRating":5.0,
        "Pictures":[],
        "Properties":
        [
            {
                "Name":"Name",
                "DisplayText":"Name des Eintrags",
                "Type":"Text",
                "Value":"Bozena Anna Bartnik"
            }, 
            {
                "Name":"Kurzbeschreibung",
                "DisplayText":"Kurzbeschreibung",
                "Type":"Text",
                "Value":"Die Kurzbeschreibung des Eintrags",
                "Translations": [
                { 
                    "Culture": "de-DE",
                    "DisplayText": "Kurzbeschreibung",
                    "Value": "Die Kurzbeschreibung des Eintrags"
                },
                {
                    "Culture": "en-US",
                    "DisplayText": "Short description",
                    "Value": "The short description of the entry"
                }]
            }
        ]
    }
]

Mehrsprachige Eigenschaften

Die Anzeigetexte von Eigenschaftsnamen und die Werte der jeweiligen Eigenschaft werden auch in übersetzter Form zur Verfügung gestellt. Das erfolgt für alle Sprachen, die vollständig aktiviert sind, also auch für die Indizierung. Diese Sprachen werden im Portal ohne „(beta)“ in der Sprachauswahl-Liste angezeigt.

Export von Bildern

Bis zu 8 Bilder werden zu jedem Eintrag exportiert. Für jedes Bild gibt es ein Objekt mit den folgenden Eigenschaften:

• Url: Die Url des Bildes auf dem Portal
• Description: die Bildbeschreibung
• PictureCredits: Copyright-Angaben zum jeweiligen Bild (falls nichts im Portal hinterlegt ist wird der Eintrag als Copyright-Holder hinterlegt)
• PictureCreditsUrl: eine optionale URL zum Fotografen oder Urheber des jeweiligen Bildes

{
    "Url": "https://camping-bayern.info/Media/Default/Gallery/90/5683.png",
    "Description": "Mainglueck Campingplatz Platzplan",
    "PictureCredits": "(c) Mainglück Camping",
    "PictureCreditsUrl": null
}