Stars Rating and Social Reviews SEO

Integration of Stars Rating and Social Reviews SEO is done by website’s backend. Before rendering a recipe page, your website’s backend should call Spot.IM SEO service and receive HTML response. Append the received markup to a section of the page you want to show the Stars Rating widget.

Top

Endpoint

POST https://seo.spot.im/widgets/stars-and-reviews/:spotId/:postId

Top

Parameters

ParameterDescription
spotIdThis is your Spot ID. For convenience, you can find this by clicking Wordpress in the dropdown of the Setup tab in your Spot.IM account Settings.
postIdUnique ID of the conversation, usually the ID of the article or blog post.

JSON Params

{
    "url": "https://www.example.com/category/recipe"
}

Top

Response

<div style="display: none;" class="spot-im-social-reviews-widget" data-spot-id="sp_cNLt89un" data-post-id="1">
    <svg style="display:none;" xmlns:xlink="https://www.w3.org/1999/xlink">
        <symbol viewBox="0 0 18 18" id="star">
            <path d="M8.988 14.02L3.425 18l1.923-6.556L0 7.004l6.504-.055L8.988 0l2.414 7.005H18l-5.373 4.483L14.55 18l-5.562-3.98z"></path>
        </symbol>
        <symbol viewBox="0 0 18 18" id="half-star">
            <path d="M8.988 14.02L3.425 18l1.923-6.556L0 7.004l6.504-.055L8.988 0l2.414 7.005H18l-5.373 4.483L14.55 18l-5.562-3.98z" fill="#E5E6E6"></path>
            <path d="M3.425 18l1.923-6.556L0 7h6.504l2.484-7v14.02L3.425 18z"></path>
        </symbol>
    </svg>
    <div class="social-reviews-wrapper" data-conversation-id="sp_cNLt89un_1" data-average-rating="0" data-total-ratings="0" style="border-top: 2px solid #307FE2; border-bottom: 1px solid #e5e6e6; padding: 18px 0; overflow: hidden; direction: ltr">
        <div style="float: left">
            <div class="stars-rating hover-enabled" style="display: inline-block; vertical-align: middle">
                <div class="stars-rating-icons-container">
                    <svg class="icon">
                        <use xlink:href="#star"></use>
                    </svg>
                    <svg class="icon">
                        <use xlink:href="#star"></use>
                    </svg>
                    <svg class="icon">
                        <use xlink:href="#star"></use>
                    </svg>
                    <svg class="icon">
                        <use xlink:href="#star"></use>
                    </svg>
                    <svg class="icon">
                        <use xlink:href="#star"></use>
                    </svg>
                </div>
            </div>
            <div class="spot-im-social-reviews-widget-summary">
                <span class="info">0 Ratings</span>
                <span class="description" style="display: none"></span>
            </div>
        </div>
        <div class="total-comments-container" style="float: right;">
            <svg style="vertical-align: middle; padding: 0 5px; fill: #307FE2;" width="14" height="15" viewBox="0 0 14 15">
                <path d="M3.5 0C1.084 0 0 1.157 0 3.737v3.94C0 10.255 1 11 3.5 11h.668c.41.898.33 1.5.156 2.308-.035.16-.042.345.003.483.1.303.45.382 1.324-.487.257-.255.908-.982 1.607-2.303H10.5c2.5 0 3.5-.745 3.5-3.323v-3.94C14 1.157 12.916 0 10.5 0h-7z" />
            </svg>
            <span class="spot-im-social-reviews-widget-total-comments">3</span>
        </div>
    </div>
</div>
<script type="application/ld+json"> {   "@context": "https://schema.org/",   "@type": "Review",   "itemReviewed": {               "url": "https://www.spot.im/embed/standalone/index.html?spotId=sp_cNLt89un&postId=1",               "image": "https://images.spot.im/image/upload/f_auto,q_70,fl_lossy,dpr_1.0,h_180,w_180,c_thumb/v200/production/qiisyl2riruix7kui6ep",          "@type": ""   },      "datePublished": "2016-03-30",      "author": {     "@type": "Person",     "name": "Idan Mitrofanov"   },   "reviewBody": "First Commenter!!! :)" } </script>
<script type="application/ld+json"> {   "@context": "https://schema.org/",   "@type": "Review",   "itemReviewed": {               "url": "https://www.spot.im/embed/standalone/index.html?spotId=sp_cNLt89un&postId=1",               "image": "https://images.spot.im/image/upload/f_auto,q_70,fl_lossy,dpr_1.0,h_180,w_180,c_thumb/v200/production/qiisyl2riruix7kui6ep",          "@type": ""   },      "datePublished": "2016-03-30",      "author": {     "@type": "Person",     "name": "Idan Mitrofanov"   },   "reviewBody": "Hey everybody!  Now a bit of seriousness, this is a Spot for our Developers Center for you to try it out. Feel free to ask anything you want or just be goofy and play around as we do from time to time. ;)" } </script>

In the response you’ll get an HTML markup which implements the schema.org protocol, and holds SEO information for Google and other search engines. Appending this HTML markup to the page lets search engines to index the page, and the stars rating and its reviews.

The returned markup contains HTML for the stars widget, therefore it has to be appended in the place where you want the Stars Rating widget to appear. The rest of the JSON-LD script tags aren’t visible and don’t change the flow of the page.

Notice that you still have to include the implementation script of the stars rating widget for the client behaviour.

<script type="text/javascript" src="https://www.spot.im/embed/widgets/stars-rating/bundle.js"></script>

You can verify the integration using Google’s structured data testing tool both by url (if your url is accessible by the world) or by pasting an HTML code. More about that later.

Top

Additional Information

Spot.IM holds only page’s social rating, its reviews and their ratings. By providing additional information regarding the recipe to Spot.IM SEO service you can receive complete markup for the page SEO. Such information may include cooking time, recipe ingredients, etc… In order to provide the additional data, call the Spot.IM SEO service with the following body JSON:

{
    "url": "https://www.example.com/category/recipe", // MANDATORY: URL of the page that will be appended to each review
    "name": "name of the recipe (if not provided, extracted by us)", // will be appended to each review
    "image": "url of the recipe image (if not provided, extracted by us)" // will be appended to each review,
    "type": "Recipe", // Declares that you add additional information for recipe
    "recipe": { ... } // Recipe JSON-LD Object
}

The Recipe JSON-LD Object is full or partial JSON object that represents recipe. For example:

{
    "@context": "https://schema.org/",
    "@type": "Recipe",
    "author": {
        "@type": "Person",
        "name": "Carol Smith"
    }
}

You can find the full object structure here. Notice that Spot.IM provides the aggregateRating information and you don’t have to supply it.
By providing the above information to Spot.IM SEO Service, you’ll get in return SEO markup that represents the author.

Top

Testing Tool

Google provides a structured data testing tool which will validate your recipe and reviews page. Fill out the Fetch URL field, click on “Run Test” button and wait a second for the result to show up.