Bewertungs-API

Die Bewertungs-API ist eine REST (RESTful) API, über die die Daten aller Bewertungen eines Portals abgerufen werden können.

Zur Info: dieses Feature entsteht im Rahmen von Customizing für einen Kunden und umfasst nur die für den Kunden benötigten Features. Unterstützt wird z. B. noch nicht die Übergabe eines zeitlichen Filters (alle Bewertungen die im Jahr 2021 abgegeben wurden). Längerfristig wollen wir die API jedoch entsprechend erweitern, so dass darüber auch Szenarien anderer Portalbetreiber abgedeckt werden.

Aktivieren der API

Die API kann jederzeit durch den Support aktiviert werden. Weitere Einstellmöglichkeiten und Informationen zu Sicherheitseinstellungen werden dann im Portalmanagement unter Einstellungen > API angezeigt.

Datenformat eines Eintrags

Beispiel für JSON-Daten einer Nutzer-Bewertung:

{
    "RatingId": 4242,
    "EntryId": 23,
    "FirstName": "Max",
    "LastName": "Mustermann",
    "YearAndMonthOfVisit": "2021-09",
    "CreatedUtc": "2021-09-21T22:30:03Z",
    "RatingOverall": 5.0,
    "Summary": "Tolle Zeit",
    "Comment": "Uns hat es hier sehr gut gefallen.",
    "IsEditorialRating": false,
    "IsAggregateRating": false,
    "RatingCount": 1,
    "AggregateRatingSource": "Undefined",
    "RatingValues": [
        {
            "CategoryName": "Freundlichkeit Personal",
            "Value": 5
        },
        {
            "CategoryName": "Speisen und Getränke",
            "Value": 5
        },
        {
            "CategoryName": "Ausstattung",
            "Value": 4
        }
    ]
}

Beispiel für JSON-Daten einer Aggregierten Bewertung:

{
    "RatingId": 265395,
    "EntryId": 49,
    "FirstName": null,
    "LastName": null,
    "YearAndMonthOfVisit": null,
    "CreatedUtc": "2021-04-12T14:22:27Z",
    "RatingOverall": 4.4,
    "Summary": null,
    "Comment": null,
    "IsEditorialRating": false,
    "IsAggregateRating": true,
    "RatingCount": 451,
    "AggregateRatingSource": "Google",
    "RatingValues": []
}

Erläuterungen zu einzelnen Feldern:

• YearAndMonthOfVisit: Monat und Jahr des Besuchs durch den Nutzer (Eingabemaske erlaubt nur Monat und Jahr)
• CreatedUtc: Zeitpunkt der Abgabe der Bewertung oder der Aggregation der externen Bewertungen
• RatingOverall: Gesamteindruck (ist Durchschnittswert bei aggregierten Bewertungen)
• Summary: (kurzer) Titel
• Comment: (längerer) Kommentar
• IsEditorialRating: wahr falls es sich um eine redaktionelle Bewertung handelt
• IsAggregateRating: wahr falls es sich um eine aggregierte Bewertung handelt
• RatingCount: Anzahl der Bewertungen, die zu einer aggregierten Bewertung zusammengeführt wurden, ist immer 1 bei Nutzerbewertungen
• AggregateRatingSource: Herkunft der aggregierten Bewertung
• RatingValues: Liste der einzelnen Bewertungskategorien (wie im Portal eingestellt) und der Bewertungen durch den Nutzer, leer bei aggregierten Bewertungen

Allgemeine Funktionsweise

Wenn das Feature aktiviert ist, kann über einen abgesicherten API-Endpunkt die Abfrage von außen gestellt werden. Die Bewertungsdaten werden im Format JSON geliefert. Die Sicherheitsanforderungen besprechen wir beim Aktivieren des API-Endpunkts.

Abruf aller Bewertungsdaten (GET)

https://PORTAL-DOMÄNE/api/ratings/v1

Hier können alle Bewertungen als GET-Request abgerufen werden. Je nach Anzahl der Bewertungen im Portal kann die Antwort einige Megabyte groß sein und ein paar Sekunden dauern.

Abruf der Bewertungsdaten zu einem Eintrag (GET)

https://PORTAL-DOMÄNE/api/ratings/v1?entryId=23

Über den gleichen Endpunkt werden bei Angabe einer Eintrags-Id alle Bewertungen eines einzelnen Eintrags zurück geliefert.