API-Dokumentation SHOPVOTE

API-Dokumentation | Autor: Dirk Stuwe | Stand: 14.08.2015


Inhaltsverzeichnis

Einführung

Die ShopVote "VotesAPI" ermöglicht eingetragenen Anbietern den Abruf von Bewertungsdaten aus dem ShopVote-Bewertungssystem. Diese Daten können dann durch den Anbieter weiter verarbeitet werden, um z.B. bei ShopVote aggregierte Bewertungen innerhalb des eigenen Shops darstellen zu können.

Datenabruf

Der Datenabruf erfolgt über eine einmalige API-URL, die den [API-Key] und die [ShopID] des Online-Shops enthält. War der Aufruf erfolgreich, werden die zuliefernden Daten im XML-Format zurückgegeben.

https://api.shopvote.de/ratings/v1/[Funktion]/[ShopID]/[API-Key]

Die Angaben "Funktion", "ShopID" und "API-Key" sind Pflichtwerte. Werden falsche Werte angegeben, liefert der Aufruf den HTTP-Statuscode 400 oder 403. Die vollständige API-URL für die jeweilige Funktion wird im Händler-Bereich angeboten.

Mögliche Funktionen
[Funktion] Datenumfang / Rückgabewerte
last25 Die Funktion "last25" gibt die letzten 25 Bewertungen des Online-Shop zurück. Zu jeder Bewertung werden das Bewertungsdatum, Bewertungssterne, Autor und vorhandene Antworten geliefert. Diese Funktion ist verfügbar, wenn das Addon "VotesAPI" gebucht wurde.
last25ext Entspricht der Funktion "last25" und gibt zusätzlich das Bewertungsprofil (Bewertungsnote, Anzahl aller Bewertungen, Anzahl positiver, neutraler, negativer Bewertungen) des Online-Shops zurück. Diese Funktion ist verfügbar, wenn das Kombi-Addon "RatingStars+VotesAPI" gebucht wurde.
ratingstars Die Funktion gibt die Bewertungsstatistik (Bewertungsnote, Anzahl aller Bewertungen, Anzahl positiver, neutraler, negativer Bewertungen) des Online-Shops zurück. Die Daten sind optimiert für die Nutzung des Addons "RatingStars".

Datenabruf für Drittanbieter (zustimmungspflichtig durch Händler)

ShopVote ermöglicht es Händlern, ihre Bewertungsdaten auch bestimmten Drittanbietern zur Verfügung zu stellen. An welche Drittanbieter die Daten übermittelt werden können, wird durch ShopVote vorgegeben. Eine Übersicht der verfügbaren Drittanbieter steht im Händlerbereich unter dem Punkt "API-Daten" zur Verfügung.

Wichtig: Der Abruf von Bewertungsdaten durch Drittanbieter ist immer zustimmungspflichtig durch den Händler. Der Händler muss einem Drittanbieter über den Menüpunkt "API-Daten" den Zugriff auf die Bewertungsdaten explizit erlauben. Eine Anleitung zur Nutzung der API-Schnittstelle wird Drittanbietern ausserhalb dieser Dokumentation separat bereitgestellt. Händler haben bei der Bereitstellung von Bewertungsdaten für Drittanbieter keinen Programmieraufwand.


XML-Daten Struktur am Beispiel der API-Funktion "last25ext"

Die nachfolgend aufgeführte XML-Daten Struktur stellt den maximal möglichen Datenumfang dar, der beim API-Aufruf zurückgeliefert werden kann. Die Funktion "last25ext" (Kombi-Addon "RatingStars + VotesAPI") liefert den maximalen Datenumfang. Die Funktionen "last25" und "ratingstars" geben jeweils Teilmengen zurück. So wird bei der Funktion "last25" (Addon "VotesAPI") der Knoten rating_summary (Zeile 8 - 17) nicht zurückgeliefert. Dagegen wird bei Aufruf der Funktion "ratingstars" (Addon "RatingStars") der Knoten reviews (Zeile 18-38) nicht zurückgegeben (siehe Beispiel).

<?xml version="1.0" encoding="UTF-8"?>
<shoprating>
	<shopid>1234</shopid>
	<name>beispieldomain.de</name>
	<profile>https://www.shopvote.de/bewertungen_xxxx.html</profile>
	<shopurl>http://www.beispieldomain.de</shopurl>
	<last_vote>Wed, 11 June 2014 12:05:41 GMT</last_vote>
	<rating_summary>
		<rating_value type="stars">4.85</rating_value>
		<rating_value type="score">1.15</rating_value>
		<rating_value type="word">Sehr gut</rating_value>
		<ratings_count>420</ratings_count>
		<ratings_positive>400</ratings_positive>
		<ratings_neutral>12</ratings_neutral>
		<ratings_negative>8</ratings_negative>
		<comments_count>360</comments_count>
	</rating_summary>
	<reviews>
		<review>
			<review_url>https://www.shopvote.de/erfahrungsbericht_xxxxx.html</review_url>
			<review_rating name="stars">4.40</review_rating>
			<review_date>Fri, 13 June 2014 10:13:29 GMT</review_date>
			<reviewer>[Benutzername des Autors]</reviewer>
			<text>[Text der Bewertung]</text>
			<review_answers>
				<answer>
					<type>Shop</type>
					<date>Fri, 13 June 2014 10:18:21 GMT</date>
					<text>[Text der Antwort]</text>
				</answer>
				<answer>
					<type>Kunde</type>
					<date>Fri, 13 June 2014 10:22:51 GMT</date>
					<text>[Text der Antwort]</text>
				</answer>
			</review_answers>
		</review>
	</reviews>
</shoprating>
		

XML-Daten Struktur am Beispiel der Funktion "ratingstars"

<?xml version="1.0" encoding="UTF-8"?>
<shoprating>
	<shopid>1234</shopid>
	<name>beispieldomain.de</name>
	<profile>https://www.shopvote.de/bewertungen_xxxx.html</profile>
	<shopurl>http://www.beispieldomain.de</shopurl>
	<last_vote>Wed, 11 June 2014 12:05:41 GMT</last_vote>
	<rating_summary>
		<rating_value type="stars">4.85</rating_value>
		<rating_value type="score">1.15</rating_value>
		<rating_value type="word">Sehr gut</rating_value>
		<ratings_count>420</ratings_count>
		<ratings_positive>400</ratings_positive>
		<ratings_neutral>12</ratings_neutral>
		<ratings_negative>8</ratings_negative>
		<comments_count>360</comments_count>
	</rating_summary>
</shoprating>
		

Beschreibung der XML-Elemente

Element Beschreibung
shoprating Der Root-Knoten, dem alle weiteren Elemente untergeordnet sind.
shopid Beinhaltet die ShopID des Shops bei ShopVote.
name Gibt die Domain zurück, unter der ein Shop bei ShopVote gelistet wird.
profile Gibt die URL zum Bewertungsprofil des Online-Shops zurück.
shopurl Gibt die URL zum Online-Shops zurück. (Wird für das SnippetCode des Addons "RatingStars" benötigt.)
last_vote Gibt den Timestamp der letzten Bewertung im Format YYYY-MM-DD HH:MM:SS (MySQL: DATETIME) zurück.
rating_summary Knoten, der die Bewertungsstatistik des Online-Shops enthält. Hinweis: Dieser Knoten mit seinen Child-Elementen wird nur bei Aufruf der Funktion "last25ext" ausgeliefert. Dazu muss das Addon "RatingStars + VotesAPI" gebucht worden sein.
rating_value[type=stars] Gibt die Anzahl der Bewertungssterne als dezimalen Wert zurück (5 Sterne = Sehr gut; 1 = Sehr schlecht). Dezimalzeichen ist der Punkt "."
rating_value[type=score] Gibt die Bewertungsnote im Schulnotenstil zurück (1 = Sehr gut; 5 = Sehr schlecht). Dezimalzeichen ist der Punkt "."
rating_value[type=word] Gibt die Bewertungsnote als Wort zurück. Mögliche Werte: Sehr gut; Gut; Befriedigend; Schlecht; Sehr schlecht
ratings_count Anzahl aller Bewertungen, die der Shop erhalten hat.
ratings_positive Anzahl aller positiven Bewertungen, die der Shop erhalten hat.
ratings_neutral Anzahl aller neutral Bewertungen, die der Shop erhalten hat.
ratings_positive Anzahl aller negative Bewertungen, die der Shop erhalten hat.
comments_count Anzahl der Bewertungen, die mit Kommentar abgegeben wurden. (Bewertungen mit Text)
reviews Knoten, der die Child-Elemente für die maximal 25 letzten Bewertungen enthält.
review Knoten, der die Daten zu einer einzelnen Bewertung enthält.
review_url Gibt die URL zum jeweiligen Erfahrungsbericht zurück.
review_rating[name=stars] Gibt die Anzahl der Bewertungssterne der jeweiligen Einzelbewertung als dezimalen Wert zurück. Dezimalzeichen ist der Punkt "."
review_date Gibt den Timestamp der Bewertung im Format YYYY-MM-DD HH:MM:SS (MySQL: DATETIME) zurück.
reviewer Beinhaltet den Benutzernamen des Autors des Erfahrungsberichtes.
text Gibt den gesamten Bewertungstext zurück.
review_answers Dieser Knoten wird ausgeliefert, wenn zur Bewertung Antworten vorhanden sind.
answer Dieser Knoten repräsentiert eine Antwort, die auf die Bewertung gegeben wurde. Er enthält die Child-Elemente type, date, text.
type Gibt den Autor der Antwort zurück. Kann die Werte "Shop" oder "Kunde" enthalten.
date Gibt den Timestamp der Antwort im Format YYYY-MM-DD HH:MM:SS (MySQL: DATETIME) zurück.
text Beinhaltet den Text der Anwtort.

Beispiel-Code für den Datenabruf und die Verwendung Daten mit PHP

Die folgenden Code-Beispiele zeigen exemplarisch, wie die Daten aus der XML-Rückgabe verarbeitet werden können. Damit Sie die Daten wie im Beispiel abrufen können, benötigen Sie die PHP-Erweiterung cURL.

Beispiel 1: Abruf der letzen 25 Bewertungen mit der Funktion "last25" (Addon "VotesAPI")
<?php
	$apiFunction = "last25";
	$svShopID    = "1404";
	$apiKey      = "c6042629fc76e19d564c88638039dabc";
	$apiUrl      = 'https://api.shopvote.de/ratings/v1/'.$apiFunction.'/'.$svShopID.'/'.$apiKey;
       
	$ch = curl_init();
	curl_setopt($ch, CURLOPT_USERAGENT, 'SVApiV1; L25 for ShopID '.$svShopID );
	curl_setopt($ch, CURLOPT_HEADER, false);
	curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
	curl_setopt($ch, CURLOPT_URL, $apiUrl);
	$output = curl_exec($ch);
	curl_close($ch);
	
	if ($xml = simplexml_load_string($output)) {		 
		foreach ($xml->reviews->review as $review) {
			$stars       = $review->review_rating;
			$review_text = $review->text;
			foreach ($review->answers->answer as $answer) {
				$answer_date = $answer->date;
				$answer_text = $answer->text;
			}
		}
	}
?>
		

Der Aufruf der API-Funktion "last25" aus Beispiel 1 liefert folgendes XML-Objekt:

SimpleXMLElement Object
(
    [api_documentation] => https://api.shopvote.de/documentation.html
    [shopid] => 1404
    [name] => demo.shopvote.de
    [profile] => https://www.shopvote.de/bewertung_demo_shopvote_de_1404.html
    [shopurl] => http://demo.shopvote.de
    [lastvote] => 2014-06-14 21:17:36
    [reviews] => SimpleXMLElement Object
    (
        [review] => SimpleXMLElement Object
        (
            [@attributes] => Array
            (
                [id] => 6214
            )
            [review_url] => https://www.shopvote.de/erfahrungsbericht_demo_shopvote_de_6214.html
            [review_date] => 2015-01-03 22:05:15
            [review_rating] => 3.9
            [reviewer] => TestUser
            [text] => Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy...
            [answers] => SimpleXMLElement Object
            (
                [answer] => Array
                (
                    [0] => SimpleXMLElement Object
                    (
                        [author] => Shop
                        [date] => 2015-01-05 16:07:35
                        [text] => Vielen Dank für Ihre Bewertung.
                    )
                    [1] => SimpleXMLElement Object
                    (
                        [author] => Kunde
                        [date] => 2015-01-05 16:15:53
                        [text] => Ich bedanke mich für Ihre Unterstützung und den guten Service.
                    )
                    [2] => SimpleXMLElement Object
                    (
                        [author] => Shop
                        [date] => 2015-01-13 21:54:19
                        [text] => Gern geschehen.
                    )
                )
            )
        )
    )
)
		

Beispiel 2: SnippetCode des Addons "RatingStars" mit der Funktion "ratingstars" oder "last25ext" generieren:

Händler, die das Addon "RatingStars" oder das Kombi-Addon "RatingStars + VotesAPI" gebucht haben, erhalten mit dem Aufruf der Funktionen "ratingstars" oder "last25ext" die Bewertungsstatistik Ihres Online-Shops zurückgeliefert. Damit ist es möglich, aus den Rückgabewerten den SnippetCode (vgl. Zeile 25 - 32) entsprechend dem Addon "RatingStars" zu generieren.

<?php
	$apiFunction = "ratingstars";	// oder $apiFunction = "last25ext";
	$svShopID    = "1404";
	$apiKey      = "c6042629fc76e19d564c88638039dabc";
	$apiUrl      = 'https://api.shopvote.de/ratings/v1/'.$apiFunction.'/'.$svShopID.'/'.$apiKey;
       
	$ch = curl_init();
	curl_setopt($ch, CURLOPT_USERAGENT, 'SVApiV1; L25ext for ShopID '.$svShopID );
	curl_setopt($ch, CURLOPT_HEADER, false);
	curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
	curl_setopt($ch, CURLOPT_URL, $apiUrl);
	$output = curl_exec($ch);
	curl_close($ch);
	
	if ($xml = simplexml_load_string($output)) {		 
		$shopname   = $xml->name;
		$shopprofil = $xml->profile;
		$shopurl    = $xml->shopurl;
		$bewertungssterne   = $xml->rating_summary->rating_value[0];
		$bewertungsnote     = $xml->rating_summary->rating_value[1];
		$anzahl_bewertungen = $xml->rating_summary->ratings_count;
	} 
?>
	
<span itemscope itemtype="http://schema.org/WebPage">
<span>ShopVote-Note von <span itemprop="name"><? echo $shopname; ?></span>: </span>
<meta itemprop="url" content="<? echo $shopurl; ?>">
<span itemprop="aggregateRating" itemscope itemtype="http://schema.org/AggregateRating">
<? echo $bewertungsnote; ?> (entspricht <span itemprop="ratingValue"><? echo $bewertungssterne; ?></span> / 5 Sternen) aus
<span itemprop="ratingCount"><? echo $anzahl_bewertungen; ?></span>
<a itemprop="sameAs" href="<? echo $shopprofil; ?>" target="_blank">Bewertungen</a>
</span></span>
		

Der Aufruf der API-Funktion "ratingstars" aus Beispiel 2 liefert folgendes XML-Objekt:

SimpleXMLElement Object
(
    [api_documentation] => https://api.shopvote.de/documentation.html
    [shopid] => 1404
    [name] => demo.shopvote.de
    [profile] => https://www.shopvote.de/bewertung_demo_shopvote_de_1404.html
    [shopurl] => http://demo.shopvote.de
    [lastvote] => 2014-06-14 21:17:36
    [rating_summary] => SimpleXMLElement Object
        (
            [rating_value] => Array
                (
                    [0] => 3.90
                    [1] => 2.10
                    [2] => Gut
                )
            [ratings_count] => 1
            [ratings_positive] => 1
            [ratings_neutral] => 0
            [ratings_negative] => 0
            [comments_count] => 1
        )
)