Cookbook/Reviews

Publishing Review Data

Overview

In the following you find RDFa markup patterns for exposing textual reviews and numeric ratings for products, places, or organizations.

The difference of the following pattern as per the original Google patterns is the fact that our pattern combines the

so your data will be understood by more clients.

Notes:

  1. The Google documentation for RDFa currently uses the wrong property v:rating instead of v:average for the average rating, which can lead to incorrect star ratings in the preview. We have already asked them to fix this.
  2. The min/max values refer to the scale used for ratings in your shop system, NOT for the lowest/highest actual rating. So if you have zero reviews for an item and you are using a scale from 0 to 5, it would be
    • min (review:minRating) = 0
    • max (review:maxRating) = 5
    • mean (review:rating and v:average) = 0
    • number of reviews (review:totalRatings and v:votes = 0
  3. Google has clarified that they accept the v:count' property only if the respective reviews actually exist on the page, i.e. that there is the text of the review available. Thus, use v:votes instead in order to publish the number of people who at least rated the product (i.e., assigned a star rating without necessarily writing a textual explanation). If you want to use v:count, you must also mark-up and make available the individual review text on the same page.

See below for more details on that issue.

Markup Example

RDFa

<div xmlns:review="http://purl.org/stuff/rev#"
xmlns:v="http://rdf.data-vocabulary.org/#">
<br />Product Reviews:
<div rel="review:hasReview v:hasReview">
<span typeof="v:Review-aggregate review:Review">
<br />Average:
<span property="review:rating v:average" datatype="xsd:float">4.5</span>, avg.:
<span property="review:minRating" datatype="xsd:integer">0</span>, max:
<span property="review:maxRating" datatype="xsd:integer">5</span> (count:
<span property="review:totalRatings v:votes" datatype="xsd:integer">45</span>)<br />
</span>
</div>
</div>

Recommendation 1: In your HTML template, you should include the review markup only if there is review data for this article, because Google will otherwise display zero stars, which may convey a worse reputation than no star rating.

The best approach is a conditional pattern, which could look like

{% if {review_count}>0 %}
... markup for the review data ...
{% endif %}

Recommendation 2:' You may feel tempted to suppress bad ratings, i.e. by a condition in the template to add the data markup only for ratings above 3, like

{% if {average_rating}>3 %}
... markup for the review data ...
{% endif %}

Don't do this! Google may use the distribution of ratings across your site as an important parameter to judge the content quality of your site, and this may make Google think that your rating data is faked.

Background on Reviews Count vs. Votes/Ratings

We found out that there is a popular pitfall that might make Google not show stars for reviews in the rich snippets for your page.The reason is that there are now two properties for indicating the numbers of reviews / ratings for

The first property is

The second is

Now, historically, we always recommended to use v:count. However, recently Google added a tiny note

Note: Whenever you include count, the page must also contain review markup for each reviewed item.

This means that you can only use v:count if

  1. all people who rated the product have also '''left a textual comment for their rating AND
  2. you have review markup also on each individual review item so that Google can access it in textual form.

There are the following important consequences:

  1. Replace v:count by v:votes in your review markup, unless you can guarantee that conditions #1 and #2 from above are met for *all your product item pages*. This is rarely the case in a shop.
  2. If you can, expose the detailed reviews using respective markup, too. We suspect that if Google has easy access to your textual reviews, they trust the data to a much higher degree, since numeric data is easy to fake in an automated fashion.

An important consequence of this change is that the text

  • xyz reviews

with "xyz" being the number of ratings will disappear from the rich snippet shown in the Google testing tool. So instead of
***** 89 reviews - $899.00 - In stock
it will show
***** $899.00 - In stock
However, Google will, in our experience, no longer show any stars if you use v:count while not providing markup for the individual reviews. Do not trust the Google Rich Snippets Testing Tool in that respect; it will still tolerate both (this is a bug in the tool that we already reported back to Google).

Category:Todo Category:Developer