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.
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.
| [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". |
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.
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 id="123456"> <isVerified>1</isVerified> <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 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>
| 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. |
isVerified |
Gibt an, ob der Bewertung ein "Verifizierter Kaufvorgang" zugrunde liegt. (0 = unverifizierte Bewertung; 1 = verifizierte Bewertung) |
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. |
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.
<?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.
)
)
)
)
)
)
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
)
)