1. Skeepers
  2. Google visibility
  3. Product Reviews

Integration Guide for JSON-LD Structured Data for Rich Snippets

Updated

Thanks to the integration of our product widget, Verified Reviews allows you to natively include the structured data required for displaying Rich Snippets in organic search results.

However, you may have temporarily noticed a decrease in the number of valid review snippets in your Search Console, or even a drop—or complete disappearance—of the stars displayed below your product page links in search results (SERP)?

Our widget is based on a JavaScript script. Google processes this technology in a specific way, requiring it to be executed by a rendering engine in order to read its content.

It can happen that Google does not consistently execute the JavaScript of our product widget and therefore does not see the structured data it contains, which can prevent Rich Snippets (stars, number of reviews, review excerpts) from being displayed.

This behavior is random and has not been officially addressed by Google.

Therefore, to ensure permanent visibility of structured data, we recommend that you manually implement structured data in JSON-LD format directly into the HTML code of your product pages.

This integration relies on our Product Reviews API, and this guide walks you through enriching your product pages with JSON-LD structured data that complies with Google’s requirements.

As stated in the official Google documentation, having correct and well-formatted structured data on your page does not guarantee 100% that enhanced results will be displayed. This display is algorithmic and based on rules known only to the search engine.

Prerequisites

  • A valid OAuth2 client_id / client_secret (available in your Avis Vérifiés account)
  • A product variation ID (product_variation_id) for each product on your site. (The product reference for which you collect reviews)

Full API documentation

Disable Rich Snippets for the product widget

  1. From the left-hand side menu, click on Display Reviews, then Integrate my widgets.
  2. Click on the pencil icon associated with the product widget of your choice.
  3. In the advanced settings, uncheck Rich Snippets activation.

API Endpoints overview

The Ratings endpoint of the API allows you to retrieve the average rating and the number of reviews for a product.

URL

https://api.skeepers.io/verified-reviews/v1/published/products

API call example

https://api.skeepers.io/verified-reviews/v1/published/products?product_variation_id=6938012334889
--header 'Authorization: ••••••'

Concrete example of the returned result


[
  {
    "product_variation_id": "6938012334889",
    "ratings": {
      "average": 4.5,
      "count_total": 127,
      ...
    },
    ...
  }
]

Click here to view the API documentation

Reviews API Endpoints (optional)

This API endpoint allows you to retrieve all reviews for a product.

URL

https://api.skeepers.io/verified-reviews/v1/published/products/reviews?product_variation_id=6938012334889
--header 'Authorization: ••••••'

Concrete example of the returned result

A list of user reviews including the author, content, rating, and publication date.

[
  {
    "review_id": "67d7b591-40a2-7ab4-1925-0b2db7753c90",
    "author_firstname": "John",
    "author_lastname": "Doe",
    "review_date": "2024-06-24T15:12:31Z",
    "review_content": "Great product!",
    "review_rate": 5,
    ...
  },
  ...
]

Click here to view the API documentation

Step-by-step integration guide

Step 1: Retrieve Ratings data

You need to use the Products endpoint to obtain the average rating and the number of reviews for a product.

API response example:

{
    "product_variation_id": "6938012334889",
    "ratings": {
      "average": 4.5,
      "count_total": 127,
      ...
    },
    ...
  }

Step 2: Create the JSON code

It’s time to create the JSON-LD structured data.

To do so, insert this JSON-LD snippet into the <head> or just before the closing </body> tag of your product page:

  1. Generate the block below:

    <script type="application/ld+json">
{  
  "@context": "https://schema.org",
  "@id": "https://www.example.com/product/6938012334889",
  "@type": "Product",
  "aggregateRating": { 
    "@type": "AggregateRating", 
    "ratingValue": "4.5", 
    "ratingCount": 127, 
    "bestRating": 5, 
    "worstRating": 1
  }
}
</script>Replace:
  2. Replace @id with the canonical URL of your product.
  3. Replace ratingValue and ratingCount with the values returned by the API.
  4. Leave everything else as is!

Step 3: Add individual reviews (optional)

To go further and display real reviews (Google may decide to display them or not), you can also integrate review data:

  1. Retrieve reviews using the Product Reviews Endpoint
  2. Convert each review to the following format:

"review": [
  { 
    "@type": "Review",
    "author": { 
      "@type": "Person", 
      "name": "R Sophie", 
      "givenName": "Sophie", 
      "familyName": "R"
    }, 
    "datePublished": "2025-03-14T14:12:00.000Z",
    "reviewBody": "I love these headphones! They block background noise and are very lightweight.", 
    "reviewRating": { 
      "@type": "Rating", 
      "bestRating": 5, 
      "worstRating": 1, 
      "ratingValue": 5 
    }
  }
]

  • You can include multiple objects inside "review": [ ... ].

  • Google recommends including: reviewRating, datePublished and author.

Complete example including reviews:

<script type="application/ld+json">
{  
  "@context": "https://schema.org",
  "@id": "https://www.example.com/product/57713",
  "@type": "Product",
  "aggregateRating": { 
    "@type": "AggregateRating", 
    "ratingValue": "4.5", 
    "ratingCount": 12, 
    "bestRating": 5, 
    "worstRating": 1
  },
  "review": [
    { 
      "@type": "Review",
      "author": { 
        "@type": "Person", 
        "name": "R Sophie", 
        "givenName": "Sophie", 
        "familyName": "R"
      }, 
      "datePublished": "2025-03-14T14:12:00.000Z",
      "reviewBody": "I love these headphones! They block background noise and are very lightweight.", 
      "reviewRating": { 
        "@type": "Rating", 
        "bestRating": 5, 
        "worstRating": 1, 
        "ratingValue": 5 
      }
    }
  ] 
}
</script>

Where should structured data be loaded?

Strongly recommended 

We strongly recommend generating and integrating structured data server-side, directly into the HTML, before the page is sent to the browser.

This way, when Googlebot or other search engine crawlers access your page, structured data is already present in the raw HTML — making it easy and reliable to index.

Example: Include the <script type="application/ld+json"> block in the HTML template rendered by your backend, for example in PHP, Node.js, Python (Django, Flask), Ruby, etc.

To avoid 

JavaScript injection on your site, as Google may not see or may poorly index this data.

Although it is technically possible to inject structured data via frontend JavaScript (for example with React, Vue, or other frameworks), this approach is less reliable because:

  • Google may not fully execute your JavaScript, or may not execute it at all, depending on page load speed and crawl budget.
  • Asynchronously loaded structured data may be missed or delayed during indexing.
  • You may get inconsistent results depending on products or updates.

Best practices

  • Structured data must match the visible content on the page.
  • Dates must follow the ISO 8601 format: "2025-03-14T14:12:00.000Z".
  • Use only real customer reviews (submitted by users).
  • Regularly update structured data with new reviews and ratings.
  • Only one "Product" tag per page is allowed for Rich Snippets to work properly.

Test data validation

Use the Google Rich Results Test tool to check that structured data is correct and properly detected

Was this article helpful?
0 out of 0 found this helpful

Related articles

Menu icon In this page