Retrieve data in JSON-LD

Retrieve ratings, reviews, AI generated review summaries and galleries in JSON-LD

To retrieve ratings, reviews, AI-generated review summary schema markups, include q={"reviews":{}, "ratings":{}, "reviewSummary": {}, "galleries" : [{dataSourceId:"DATA-SOURCE-ID"}]} in the request as shown below.

If you do not include any schema markups in the request, the default API response includes ratings, reviews, and aggregated ratings.

Sample Request

curl -g \
  --location \
  --header 'Accept: text/javascript' \
  --header 'User-Agent: Java-http-client/17.0.7' \
  --header 'Bv-Forwarded-User-Agent: Mozilla/5.0 AppleWebKit/537.36 (KHTML, like Gecko); compatible; GPTBot/1.1; +https://openai.com/gptbot' \
  --header 'bv-passkey: <PASSKEY>' \
  'https://seo.bazaarvoice.com/structured-data/v1/clients/testcustomer-fast-prs/ugc?locale=en_US&productId=product1&q={"reviews":{},"ratings":{},"reviewSummary":{},"galleries":[{dataSourceId:"<DATA-SOURCE-ID>"}]}'

Sample Response


<script type="application/ld+json" id="bv-geo-jsonld-reviews-data">
{
  "reviews": {
    "@context": "https://schema.org/",
    "review": [
      {
        "@type": "Review",
        "dateCreated": "2026-07-30T10:42:52.000+00:00",
        "datePublished": "2026-07-30T10:45:14.000+00:00",
        "reviewBody": "Example review description",
        "name": "Example Review title",
        "reviewRating": {
          "@type": "Rating",
          "ratingValue": 1,
          "bestRating": 5,
          "worstRating": 1
        },
        "author": {
          "@type": "Person",
          "name": "Billy Jean2"
        },
        "@id": "https://example.com/productId/product1#2784681771",
        "additionalProperty": [
          {
            "@type": "PropertyValue",
            "name": "Best Uses - Telecom",
            "value": "Office Use"
          },
          {
            "@type": "PropertyValue",
            "name": "Quality of Product",
            "value": "4",
            "maxValue": "5"
          },
          {
            "@type": "PropertyValue",
            "name": "Value of Product",
            "value": "5",
            "maxValue": "5"
          },
          {
            "@type": "PropertyValue",
            "name": "Comfort",
            "value": "5",
            "maxValue": "5"
          },
          {
            "@type": "PropertyValue",
            "name": "Length of ownership",
            "value": "3 months"
          }
        ],
        "image": [
          {
            "@type": "ImageObject",
            "contentUrl": "https://photos-us.bazaarvoice.com/photo/2/cGhvdG86zdGN1c3RvbWVyLWZhc3QtcHJz/f70282db-e961-5232-bddd-adc4133a7de3",
            "name": "Example Review title",
            "description": "Example review description",
            "caption": "image caption"
          }
        ],
        "video": [
          {
            "@type": "VideoObject",
            "thumbnailUrl": "https://video.api.bazaarvoice.com/e6bef6e8-1777-4d6/thumbnail/image-00001.png",
            "contentUrl": "https://video.api.bazaarvoice.com/e6bef6e8-1777-4d698/video/movie.mp4",
            "uploadDate": "2026-07-30T09:25:23.000+00:00",
            "thumbnail": {
              "@type": "ImageObject",
              "name": "BAZAARVOICE"
            },
            "name": "Example Review title",
            "description": "Example review description",
            "caption": "image caption"
          }
        ],
        "positiveNotes": {
          "@type": "ItemList",
          "itemListElement": [
            {
              "@type": "ListItem",
              "position": 1,
              "name": "Example Pros 1"
            },
            {
              "@type": "ListItem",
              "position": 2,
              "name": "Example Pros 2"
            },
            {
              "@type": "ListItem",
              "position": 3,
              "name": "Example Pros 3"
            }
          ]
        },
        "negativeNotes": {
          "@type": "ItemList",
          "itemListElement": [
            {
              "@type": "ListItem",
              "position": 1,
              "name": "Example Cons 1"
            },
            {
              "@type": "ListItem",
              "position": 2,
              "name": "Example Cons 2"
            }
          ]
        }
      }
    ]
  }
}
</script><script type="application/ld+json" id="bv-geo-jsonld-ratings-data">
{
  "@context": "https://schema.org/",
  "aggregateRating": {
    "@type": "AggregateRating",
    "bestRating": 5,
    "ratingValue": 3.4320546163849155,
    "reviewCount": 3076
  }
}
</script><script type="application/ld+json" id="bv-geo-jsonld-reviewSummary-data">
{
  "@context": "https://schema.org/",
  "review": {
    "@type": "Review",
    "datePublished": "2025-10-09T19:18:37.064000+00:00",
    "reviewBody": "The product is highly regarded by customers, with many praising its excellent features, quality, and value. Positive reviews highlight the impressive battery life and camera performance. However, some mixed opinions mention the camera quality in low light conditions. The summary should be curated to remove irrelevant or low-quality submissions.",
    "author": {
      "@type": "Organization",
      "name": "AI Review Summary",
      "description": "This summary is generated by artificial intelligence based on customer reviews"
    }
  }
}
</script>
<script type="application/ld+json" id="bv-geo-jsonld-gallery-1-data">
{
      "@context": "https://schema.org",
      "@type": "ItemList",
      "name": "Visual Gallery",
      "numberOfItems": 97,
      "itemListElement": [
        {
          "@type": "ListItem",
          "position": 1,
          "item": {
            "@type": "ImageObject",
            "name": "Featuring Sandals",
            "contentUrl": "https://example.com/image1.jpg"
          }
        },
        {
          "@type": "ListItem",
          "position": 2,
          "item": {
            "@type": "ImageObject",
            "name": "Featuring Boots",
            "contentUrl": "https://example.com/image2.jpg"
          }
        }
      ]
}
</script>

Retrieve ratings, reviews, and questions and answers

To retrieve ratings, reviews, and questions and answers schema markups, include q={"reviews":{}, "ratings":{}, "questions": {}} in the request body as shown below

Sample Request

curl -g \
  --location \
  --header 'Accept: text/javascript' \
  --header 'User-Agent: Java-http-client/17.0.7' \
  --header 'Bv-Forwarded-User-Agent: Mozilla/5.0 AppleWebKit/537.36 (KHTML, like Gecko); compatible; GPTBot/1.1; +https://openai.com/gptbot' \
  --header 'bv-passkey: <PASSKEY>' \
  'https://seo.bazaarvoice.com/structured-data/v1/clients/testcustomer-fast-prs/ugc?locale=en_US&productId=product1&q={"reviews":{},"ratings":{},"questions":{}}'

Sample Response

<script type="application/ld+json" id="bv-geo-jsonld-reviews-data">
{
  "reviews": {
    "@context": "https://schema.org/",
    "review": [
      {
        "@type": "Review",
        "dateCreated": "2026-07-30T10:42:52.000+00:00",
        "datePublished": "2026-07-30T10:45:14.000+00:00",
        "reviewBody": "Example review description",
        "name": "Example Review title",
        "reviewRating": {
          "@type": "Rating",
          "ratingValue": 1,
          "bestRating": 5,
          "worstRating": 1
        },
        "author": {
          "@type": "Person",
          "name": "Billy Jean2"
        },
        "@id": "https://example.com/productId/product1#2784681771",
        "additionalProperty": [
          {
            "@type": "PropertyValue",
            "name": "Best Uses - Telecom",
            "value": "Office Use"
          },
          {
            "@type": "PropertyValue",
            "name": "Quality of Product",
            "value": "4",
            "maxValue": "5"
          },
          {
            "@type": "PropertyValue",
            "name": "Value of Product",
            "value": "5",
            "maxValue": "5"
          },
          {
            "@type": "PropertyValue",
            "name": "Comfort",
            "value": "5",
            "maxValue": "5"
          },
          {
            "@type": "PropertyValue",
            "name": "Length of ownership",
            "value": "3 months"
          }
        ],
        "image": [
          {
            "@type": "ImageObject",
            "contentUrl": "https://photos-us.bazaarvoice.com/photo/2/cGhvdG86zdGN1c3RvbWVyLWZhc3QtcHJz/f70282db-e961-5232-bddd-adc4133a7de3",
            "name": "Example Review title",
            "description": "Example review description",
            "caption": "image caption"
          }
        ],
        "video": [
          {
            "@type": "VideoObject",
            "thumbnailUrl": "https://video.api.bazaarvoice.com/e6bef6e8-1777-4d6/thumbnail/image-00001.png",
            "contentUrl": "https://video.api.bazaarvoice.com/e6bef6e8-1777-4d698/video/movie.mp4",
            "uploadDate": "2026-07-30T09:25:23.000+00:00",
            "thumbnail": {
              "@type": "ImageObject",
              "name": "BAZAARVOICE"
            },
            "name": "Example Review title",
            "description": "Example review description",
            "caption": "image caption"
          }
        ],
        "positiveNotes": {
          "@type": "ItemList",
          "itemListElement": [
            {
              "@type": "ListItem",
              "position": 1,
              "name": "Example Pros 1"
            },
            {
              "@type": "ListItem",
              "position": 2,
              "name": "Example Pros 2"
            },
            {
              "@type": "ListItem",
              "position": 3,
              "name": "Example Pros 3"
            }
          ]
        },
        "negativeNotes": {
          "@type": "ItemList",
          "itemListElement": [
            {
              "@type": "ListItem",
              "position": 1,
              "name": "Example Cons 1"
            },
            {
              "@type": "ListItem",
              "position": 2,
              "name": "Example Cons 2"
            }
          ]
        }
      }
    ]
  }
}
</script><script type="application/ld+json" id="bv-geo-jsonld-ratings-data">
{
  "@context": "https://schema.org/",
  "aggregateRating": {
    "@type": "AggregateRating",
    "bestRating": 5,
    "ratingValue": 3.4320546163849155,
    "reviewCount": 3076
  }
}
</script><script type="application/ld+json" id="bv-geo-jsonld-questions-data">
{
  "@type": "FAQPage",
  "mainEntity": [
    {
      "@type": "Question",
      "name": "Question 27?",
      "dateCreated": "2019-04-15T13:54:06.000+00:00",
      "author": {
        "@type": "Person",
        "name": "stgtest27"
      },
      "acceptedAnswer": {
        "@type": "Answer",
        "text": "This is my answer for this question.",
        "dateCreated": "2026-03-20T10:38:06.000+00:00",
        "author": {
          "@type": "Person",
          "name": "Billy Jean2"
        },
        "upvoteCount": 0
      },
      "answerCount": 582
    },
    {
      "@type": "Question",
      "name": "question8",
      "dateCreated": "2026-02-17T04:41:37.000+00:00",
      "author": {
        "@type": "Person",
        "name": "Anonymous"
      },
      "acceptedAnswer": {
        "@type": "Answer",
        "text": "test  test test test test test test test test test",
        "dateCreated": "2026-03-16T06:43:50.000+00:00",
        "author": {
          "@type": "Person",
          "name": "Anonymous"
        },
        "upvoteCount": 0
      },
      "answerCount": 1
    },
    {
      "@type": "Question",
      "name": "Question test",
      "dateCreated": "2020-01-13T10:22:50.000+00:00",
      "author": {
        "@type": "Person",
        "name": "testqa"
      },
      "acceptedAnswer": {
        "@type": "Answer",
        "text": "answer is here",
        "dateCreated": "2024-01-17T07:37:49.000+00:00",
        "author": {
          "@type": "Person",
          "name": "bobishere"
        },
        "upvoteCount": 0
      },
      "answerCount": 5
    },
    {
      "@type": "Question",
      "name": "What is use of this product.",
      "dateCreated": "2025-03-05T20:04:58.000+00:00",
      "author": {
        "@type": "Person",
        "name": "Anonymous"
      },
      "acceptedAnswer": {
        "@type": "Answer",
        "text": "asdfnkll",
        "dateCreated": "2025-03-18T18:35:38.000+00:00",
        "author": {
          "@type": "Person",
          "name": "Anonymous"
        },
        "upvoteCount": 3001
      },
      "answerCount": 10
    },
    {
      "@type": "Question",
      "name": "Testing bv-loader-frame work change in lodash.template ?",
      "dateCreated": "2025-07-10T05:53:50.000+00:00",
      "author": {
        "@type": "Person",
        "name": "Anonymous"
      },
      "acceptedAnswer": {
        "@type": "Answer",
        "text": "test answer for bfd",
        "dateCreated": "2025-07-10T07:56:00.000+00:00",
        "author": {
          "@type": "Person",
          "name": "Anonymous"
        },
        "upvoteCount": 0
      },
      "answerCount": 2
    },
    {
      "@type": "Question",
      "name": "ADDING native question 2 for demo",
      "dateCreated": "2025-02-04T17:24:48.000+00:00",
      "author": {
        "@type": "Person",
        "name": "Anonymous"
      },
      "acceptedAnswer": {
        "@type": "Answer",
        "text": "testing new native answer",
        "dateCreated": "2025-02-05T06:26:40.000+00:00",
        "author": {
          "@type": "Person",
          "name": "Anonymous"
        },
        "upvoteCount": 0
      },
      "answerCount": 9
    },
    {
      "@type": "Question",
      "name": "aaa",
      "dateCreated": "2025-04-25T06:32:24.000+00:00",
      "author": {
        "@type": "Person",
        "name": "wowmy"
      },
      "acceptedAnswer": {
        "@type": "Answer",
        "text": "wjkedwkdkwdkwedjwedwjed",
        "dateCreated": "2025-06-30T07:59:52.000+00:00",
        "author": {
          "@type": "Person",
          "name": "testing123"
        },
        "upvoteCount": 0
      },
      "answerCount": 1
    },
    {
      "@type": "Question",
      "name": "This is my question about this product.",
      "dateCreated": "2023-12-17T18:40:43.000+00:00",
      "author": {
        "@type": "Person",
        "name": "Billy Jean2"
      },
      "acceptedAnswer": {
        "@type": "Answer",
        "text": "qf23rq2r22",
        "dateCreated": "2023-12-18T12:30:21.000+00:00",
        "author": {
          "@type": "Person",
          "name": "Vignesh!f"
        },
        "upvoteCount": 0
      },
      "answerCount": 9
    },
    {
      "@type": "Question",
      "name": "aa",
      "dateCreated": "2025-04-10T10:41:54.000+00:00",
      "author": {
        "@type": "Person",
        "name": "Anonymous"
      },
      "acceptedAnswer": {
        "@type": "Answer",
        "text": "AI_GENERATEDThis is a mock generated answer",
        "dateCreated": "2025-04-15T09:18:37.000+00:00",
        "author": {
          "@type": "Person",
          "name": "Anonymous"
        },
        "upvoteCount": 507
      },
      "answerCount": 2
    },
    {
      "@type": "Question",
      "name": "Native question 3 addition for demo",
      "dateCreated": "2025-02-04T17:38:11.000+00:00",
      "author": {
        "@type": "Person",
        "name": "Anonymous"
      },
      "acceptedAnswer": {
        "@type": "Answer",
        "text": "adding answer to native question",
        "dateCreated": "2025-02-04T18:18:20.000+00:00",
        "author": {
          "@type": "Person",
          "name": "Anonymous"
        },
        "upvoteCount": 0
      },
      "answerCount": 6
    }
  ],
  "@context": "https://schema.org/"
}
</script>

Supported Markup Schema

Supported markup schema:

Review
AggregateRating
Q&A (included as FAQPage)
AI Summary (included as a review)
Galleries

Review Schema (`@type: Review`)

This schema is used for individual customer reviews and for the AI review summary.

Attribute	Description	Example
`@type`	Specifies the schema type.	`"Review"`
`dateCreated`	When the review was created (date and time).	`"2026-03-30T10:42:36.000+00:00"`
`datePublished`	When the review was published (date and time).	`"2026-03-30T10:45:44.000+00:00"`
`reviewBody`	The review's main content.	`"This is my positive review about this poor product"`
`name`	The review's title.	`"Review title"`
`reviewRating`	The rating given in the review.	See properties below.
`author`	The reviewer (person or organization).	See properties below.
`additionalProperty`	An array containing Bazaarvoice-configured contextual attributes, including trust badges (Verified Purchaser, Incentivized, Staff, Expert, Top Contributor tiers), secondary ratings (Quality, Value, Fit, Comfort, Appearance), and product questions (Best Uses, Length of Ownership).	See example below.
`video`	Nested properties: - `@type: VideoObject` - `description` - `name` - `thumbnailUrl` - `contentUrl` - `uploadDate` - `thumbnail` (nests `@type: ImageObject`, `name`) An array of videos associated with the review.	See example below.
`image`	Nested properties: - `@type: ImageObject` - `description` - `contentUrl` An array of images associated with the review.	See example below.

`reviewRating` properties

@type: Rating
ratingValue
bestRating
worstRating

Example

{"@type":"Rating","ratingValue":4,"bestRating":5,"worstRating":1}

`author` properties

Person
- @type: Person
- name
Organization
- @type: Organization
- name
- description

Examples

Person: {"@type":"Person","name":"Billy Jean2"}
Organization: {"@type":"Organization","name":"AI Review Summary","description":"This summary is generated by artificial intelligence based on customer reviews"}

Review video example

"video": [
  {
    "@type": "VideoObject",
    "description": "",
    "name": "YWhxSsj1upg",
    "thumbnailUrl": "https://www.youtube.com/watch?v=YWhxSsj1upg",
    "contentUrl": "https://www.youtube.com/watch?v=YWhxSsj1upg",
    "uploadDate": "2021-04-25T16:32:07.000+00:00",
    "thumbnail": {
      "@type": "ImageObject",
      "name": "www.youtube.com"
    }
  }
]

Review image example

"image": [
  {
    "@type": "ImageObject",
    "description": "normal",
    "contentUrl": "https://photos-cert-eu.bazaarvoice.com/photo/2/cGhvdG86dGVzdGN1c3RvbWVyLWZhc3QtcHJz/c4f2df63-64db-5ef2-8673-33ab2a4302e4"
  }
]

Review additionalProperty example

  "additionalProperty": [
          {
            "@type": "PropertyValue",
            "name": "Best Uses - Telecom",
            "value": "Office Use"
          },
          {
            "@type": "PropertyValue",
            "name": "Quality of Product",
            "value": "4",
            "maxValue": "5"
          },
          {
            "@type": "PropertyValue",
            "name": "Value of Product",
            "value": "5",
            "maxValue": "5"
          },
          {
            "@type": "PropertyValue",
            "name": "Comfort",
            "value": "5",
            "maxValue": "5"
          },
          {
            "@type": "PropertyValue",
            "name": "Length of ownership",
            "value": "3 months"
          }
        ]

AggregateRating Schema (`@type: AggregateRating`)

This schema is used to represent ratings summary.

Attribute	Description	Example
`@type`	Defines the schema type.	`"AggregateRating"`
`bestRating`	The highest value possible in the rating scale.	`5`
`ratingValue`	The overall average rating score.	`3.4320546163849155`
`reviewCount`	The total number of reviews contributing to the aggregate rating.	`3076`

FAQPage Schema

These schemas are used for Q&A mapped as Frequently Asked Questions content.

Attribute	Description	Example
`@type`	Defines the schema type.	`"FAQPage"`
`mainEntity`	An array of questions on the FAQ page.	See Question properties below.

Question properties

Attribute	Description	Example
`@type`	Defines the schema type.	`"Question"`
`name`	The text of the question.	`"Question 27?"`
`dateCreated`	The date and time the question was created.	`"2019-04-15T13:54:06.000+00:00"`
`author`	The person who asked the question.	`{"@type":"Person","name":"stgtest27"}`
`answerCount`	The number of answers provided for the question.	`582`
`acceptedAnswer`	The accepted or primary answer to the question.	See selection rules below.

`acceptedAnswer` selection rules

Only one answer is chosen in this order of priority:

Pick an answer given by the client or brand.
Pick an answer with maximum positive feedback.
Pick the latest answer.

Example

{"@type":"Answer","text":"This is my answer for this question."}

Answer properties

Attribute	Description	Example
`@type`	Defines the schema type.	`"Answer"`
`text`	The main body of the answer.	`"This is my answer for this question."`
`dateCreated`	The date and time the answer was created.	`"2026-03-20T10:38:06.000+00:00"`
`author`	The person who provided the answer.	`{"@type":"Person","name":"Billy Jean2"}`
`upvoteCount`	The number of upvotes the answer has received.	`0`

AI Summary Schema

This schema is included as a review and contains the AI-generated review summary.

Attribute	Description	Example
`@type`	Defines the schema type.	`"Review"`
`datePublished`	The date and time the AI summary was published.	`"2025-10-09T19:18:37.064000+00:00"`
`reviewBody`	The AI-generated review summary text.	`"The product is highly regarded by customers, with many praising its excellent features, quality, and value."`
`author`	The organization that generated the summary.	See properties below.

AI Summary `author` properties

@type: Organization
name
description

Example

{"@type":"Organization","name":"AI Review Summary","description":"This summary is generated by artificial intelligence based on customer reviews"}

Galleries Schema `@type : ItemList`

This schema represents a Bazaarvoice media gallery. The gallery is returned as an ItemList; each media item is a ListItem whose item is an ImageObject. Gallery structured data is produced by the Media API.

Attribute	Description	Example
`@type`	Specifies the schema type.	`"ItemList"`
`name`	The display name of the gallery.	`"Visual Gallery"`
`numberOfItems`	Total number of items in the gallery.	`97`
`itemListElement`	An array of `ListItem` entries.	See properties below.

`listItem` Properties

Attribute	Description	Example
`@type`	Specifies the schema type.	`"ListItem"`
`position`	The 1-based position of the item in the list.	`1`
`item`	The media object (an `ImageObject`).	See properties below.

`item` (`@type = ImageObject` ) Properties

Attribute	Description	Example
`@type`	Specifies the schema type.	`"ImageObject"`
`name`	The name/caption of the media item.	`"Featuring Sandals"`
`contentUrl`	The URL of the media asset.	`"https://example.com/image1.jpg"`

Example

curl --request GET \
     --url 'https://seo-stg.bazaarvoice.com/structured-data/v1/clients/yourclientid/ugc?productId=product1&q=%7B%22galleries%22%3A%5B%7B%22noExpired%22%3Afalse%2C%22dataSourceId%22%3A%22DKQGLerBTQCDXwNS%22%2C%22filter%22%3A%22productId%3Aleather-jacket%22%2C%22sort%22%3A%22Latest%22%2C%22limit%22%3A10%2C%22requireProduct%22%3Atrue%2C%22networkSource%22%3A%22Instagram%22%7D%5D%7D&locale=en_US' \
     --header 'Accept: application/ld+json' \
     --header 'Bv-passkey: Your-passkey'

Sample

"galleries": [
    {
      "@context": "https://schema.org",
      "@type": "ItemList",
      "name": "Visual Gallery",
      "numberOfItems": 97,
      "itemListElement": [
        {
          "@type": "ListItem",
          "position": 1,
          "item": {
            "@type": "ImageObject",
            "name": "Featuring Sandals",
            "contentUrl": "https://example.com/image1.jpg"
          }
        },
        {
          "@type": "ListItem",
          "position": 2,
          "item": {
            "@type": "ImageObject",
            "name": "Featuring Boots",
            "contentUrl": "https://example.com/image2.jpg"
          }
        }
      ]

Retrieve ratings, reviews, AI generated review summaries and galleries in JSON-LD

Sample Request

Sample Response

Retrieve ratings, reviews, and questions and answers

Supported Markup Schema

Review Schema (@type: Review)

reviewRating properties

author properties

Review video example

Review image example

Review additionalProperty example

AggregateRating Schema (@type: AggregateRating)

FAQPage Schema

Question properties

acceptedAnswer selection rules

Answer properties

AI Summary Schema

AI Summary author properties

Galleries Schema @type : ItemList

listItem Properties

item (@type = ImageObject ) Properties

Example

Sample

Review Schema (`@type: Review`)

`reviewRating` properties

`author` properties

AggregateRating Schema (`@type: AggregateRating`)

`acceptedAnswer` selection rules

AI Summary `author` properties

Galleries Schema `@type : ItemList`

`listItem` Properties

`item` (`@type = ImageObject` ) Properties