API technical specifications
This section outlines the technical specifications of the Authentic Discovery API.
The technical specifications are as follows:
| Environment | URL |
|---|---|
| Staging | https://seo-stg.bazaarvoice.com/structured-data/v1/clients/{client-id}/ugc |
| Production | https://seo.bazaarvoice.com/structured-data/v1/clients/{client-id}/ugc |
Endpoint
[GET]/structured=data/v1/clients/{client-id}/ugc
HTTPS method
GET
Parameters
Note:Parameters marked with an asterisk (*) are mandatory.
| Parameter | Placement | Description | Example |
|---|---|---|---|
client-id* | Path | Bazaarvoice client instance name as registered in the Bazaarvoice Portal. If not passed, the API returns a result for the client instance associated with the API Passkey passed in the header. | |
productId* | Query | Use the Note: Ensure the product-Id matches the one saved in the Bazaarvoice product catalog. | P-7777-MSD |
Bv-Passkey* | Header | A Conversations API passkey for authentication. This is a query parameter, which is a part of the request URL | |
User-Agent (Recommended) | Header | Ensure the User-Agent header reflects the actual entity (browser or crawler) requesting the PDP. This implementation is critical for clients who need to track and verify how different AI bots are crawling their content. | Java-http-client/17.0.7' |
Accept | Header | To ensure the API returns the correct response, the By default, the API returns text/javascript. If no header is provided, the API will fall back to the default text/javascript format. | text/javascript Other available types: |
canonical | Query | The exact identifier string used in your Product Schema's @id field. Important: This value is used to populate itemReviewed @id. For search engines to associate these reviews with your product, the string you send here must be identical (character-for-character) to the @id you assign to the Product object in your own schema generation. | https://www.example.com/products/running-shoe#product Recommended format: Product Canonical URL + #product fragment. |
locale* | Query | Locale to display Labels, Configuration, Product Attributes and Category Attributes. The default value is the locale associated with the API key. | en_US Format: languageCode_countryCode Any other format will return a bad request response. |
siteId(Recommended) | Query | Site ID of the implementation. The default value is the main_site | main_site |
q | Query | The q parameter accepts a JSON object specifying which markup schemas should be included in the response. The API supports four schema types: reviews, ratings, questions, and reviewSummary. Default behavior: If q is omitted, the API returns reviews and ratings by default. Customization: You can pass filters within each schema object to refine and control the specific data returned for that schema | { "reviews": { "limit": 110, "offset": 100, "sort": "latestSubmissionTime", "filter": [ "contentLocale:eq:en_US" ] }, "ratings": { "filter": [ "contentLocale:eq:en_US" ] } } |
Bv-Forwarded-User-Agent | Header | The original User-Agent from the AI crawler's request | Mozilla/5.0 AppleWebKit/537.36 (KHTML, like Gecko); compatible; GPTBot/1.1; +https://openai.com/gptbot |
Request query parameters (q)
| Parameter | Input schema | Description |
|---|---|---|
Filter | ratings reviews questions | Filter criteria for primary content of the query. Multiple filter criteria are supported. |
ExcludeFamily | ratings reviews questions | Boolean flag indicating whether to exclude content (reviews, questions, etc.) from other products in the same family as the requested product. This setting only affects any nested content that is returned. For example, &filter=productid:eq:1101&include=reviews&excludeFamily=true limits returned review content to just that of product 1101 and not any of the products in the same family. If a value is not defined, content on all products in the family is returned. |
Sort | reviews questions | Sort criteria for the primary content type of the query. Sort order is required (ascending or descending). Multi-attribute sorting for each content/subject type is supported. |
Limit | reviews questions | Maximum number of records returned. An error is returned if the value passed exceeds 100. |
Offset | reviews questions | Index at which to return results. By default, indexing begins at 0. When you issue a query. Using Limit=100, Offset=0 returns results 0-99. When changing this to Offset=1, results 1-100 are returned. The maximum supported value is 300000. |
Locale | reviews questions | Locale in which display labels, configuration, product attributes, and category attributes are displayed. The default value is the locale defined in the display associated with the API key. |
language | reviewSummary | Language of the AI-generated review summary (en, de, es, or fr) |
Updated about 8 hours ago