Bazaarvoice Authentic Discovery API

openapi: 3.0.3
info:
  title: SEO
  version: 1.0.0
  description: The Authentic Discovery API for serving structured data (JSONLD, Microdata). Serves JSON-LD by default,
    and Microdata.
  x-audience: external-public
  x-api-id: f08f5ba3-1eee-4cfe-bca5-9320ea83ffbf
  contact:
    name: SWAT
    email: swat-display@bazaarvoice.com
    url: https://docs.bazaarvoice.com/articles/#!ratings-reviews/display_integration
servers:
- url: https://seo-stg.bazaarvoice.com/structured-data/v1
  description: Staging Server
- url: https://seo.bazaarvoice.com/structured-data/v1
  description: Production Server
paths:
  /clients/{clientId}/ugc:
    get:
      summary: Fetch Structured Data (JSON-LD or Microdata)
      description: Retrieves structured data for a specific product. This is the recommended endpoint that accepts
        productId as a query parameter.
      operationId: getStructuredDataV2
      security:
      - Bv-passkey: []
      parameters:
      - name: clientId
        in: path
        description: The name of the client. Can contain special characters.
        required: true
        schema:
          type: string
        example: yourclientid
      - name: productId
        in: query
        description: The ID of the product. Can contain special characters.
        required: true
        schema:
          type: string
        example: product1
      - name: Bv-Forwarded-User-Agent
        in: header
        description: Clients will need to send User-Agent of consumers accessing the PDP page
        required: false
        schema:
          type: string
          pattern: ^[a-zA-Z0-9\s\(\)\[\]\{\}\/\.\-_;:,+]+$
          minLength: 10
          maxLength: 500
          example: Mozilla/5.0 AppleWebKit/537.36 (KHTML, like Gecko); compatible; ChatGPT-User/1.0; +https://openai.com/bot
      - name: User-Agent
        in: header
        description: Clients will need to send User-Agent of their backend http client
        required: false
        schema:
          type: string
          pattern: ^[a-zA-Z0-9\s\(\)\[\]\{\}\/\.\-_;:,+]+$
          minLength: 10
          maxLength: 500
          example: Apache-HttpClient/4.5.8 (Java/1.8.0_191)
      - name: Accept
        in: header
        description: Accept header must be empty or omitted. The API will return the default content type (text/javascript)
          for now, in future this might change.
        required: false
        schema:
          type: string
          maxLength: 0
          example: ''
      - name: q
        in: query
        description: 'A JSON-encoded query object containing parameters for various content types. Refer to Bazaarvoice
          CV2 documentation for specific filter and sort values.

          '
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                reviews:
                  type: object
                  additionalProperties: true
                  properties:
                    filter:
                      type: array
                      description: Filter criteria for primary content of the query. Multiple filter criteria are
                        supported.
                      items:
                        type: string
                    limit:
                      type: string
                      description: Max number of records returned. An error is returned if the value passed exceeds
                        100.
                    offset:
                      type: string
                      description: 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.
                    sort:
                      type: string
                      description: Sort criteria for primary content of the query. Multiple sort criteria are supported.
                    excludeFamily:
                      type: boolean
                      description: Boolean flag indicating whether to exclude content from other products in the
                        same family as the requested product.
                ratings:
                  type: object
                  properties:
                    filter:
                      type: array
                      description: Filter criteria for primary content of the query. Multiple filter criteria are
                        supported.
                      items:
                        type: string
                questions:
                  type: object
                  nullable: true
                  properties:
                    filter:
                      type: array
                      description: Filter criteria for primary content of the query. Multiple filter criteria are
                        supported.
                      items:
                        type: string
                    include:
                      type: string
                      description: Additional content to include in the query response. Mostly used to include answers
                        with questions.
                    sort:
                      type: string
                      description: Sort criteria for primary content type of the query. Sort order is required (asc
                        or desc).
                    limit:
                      type: integer
                      description: Max number of records returned. An error is returned if the value passed exceeds
                        100.
                    offset:
                      type: integer
                      description: 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.
                reviewSummary:
                  type: object
                  nullable: true
                galleries:
                  type: array
                  description: Gets media items for a data source
                  items:
                    type: object
                    required:
                    - dataSourceId
                    properties:
                      dataSourceId:
                        type: string
                        description: Unique gallery ID.
                        example: DKQGLerBTQCDXwNS
                      filter:
                        type: string
                        description: Filters the requested content.
                        example: productId:leather-jacket
                      sort:
                        type: string
                        enum:
                        - Latest
                        - Likes
                        - Moderation
                        - Optimized
                        - LastUpdated
                      limit:
                        type: integer
                        format: int64
                        example: 10
                      before:
                        type: string
                        description: Cursor for pagination.
                      after:
                        type: string
                        description: Cursor for pagination.
                      offset:
                        type: integer
                        format: int64
                        example: 10
                      requireProduct:
                        type: boolean
                        description: Only return items with products.
                        example: true
                      networkSource:
                        type: string
                        enum:
                        - Pinterest
                        - Facebook
                        - Instagram
                        - Twitter
                        - Tumblr
                        - Snapchat
                        - TikTok
                        - YouTube
                        - MediaImport
                        example: Instagram
                      noExpired:
                        type: boolean
                        default: false
            example:
              reviews:
                filter:
                - productid:eq:product1,contentLocale:eq:en_US
                limit: '1'
                offset: '0'
                sort: submissiontime:desc
                excludeFamily: true
              ratings:
                filter:
                - id:eq:product1
              questions:
                filter:
                - productid:eq:product1
                include: answers
                sort: submissiontime:desc
                limit: 1
                offset: 0
              reviewSummary:
                language: ar
              galleries:
              - dataSourceId: DKQGLerBTQCDXwNS
                limit: 10
                sort: Latest
      - name: canonical
        in: query
        required: false
        schema:
          type: string
          format: uri
        description: The exact identifier string used in your Product Schema's `@id` field. **CRITICAL REQUIREMENT:**
          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.
          **Recommended Format:** Product Canonical URL + `#product` fragment.
        example: https://www.example.com/running-shoe#product
      - name: locale
        in: query
        description: Locale to display Labels, Configuration, Product Attributes and Category Attributes in. The
          default value is the locale defined in the display associated with the API key.
        required: true
        schema:
          type: string
          example: en_US
      - name: siteId
        in: query
        description: Site ID of the implementation, default will be main_site
        required: false
        schema:
          type: string
          example: main_site
      responses:
        '200':
          description: 'Returns JSONLD by default for reviews and ratings.

            '
          headers:
            Vary:
              description: Indicates which request headers affect the response
              schema:
                type: string
                example: Origin, Accept-Encoding, Accept
            Cache-Control:
              description: Caching directives (default 55 minutes)
              schema:
                type: string
                example: public, max-age=3300
          content:
            application/ld+json:
              schema:
                $ref: '#/components/schemas/JsonLdResponseJSONFormat'
            text/javascript:
              schema:
                $ref: '#/components/schemas/JsonLdResponseScript'
            text/html:
              schema:
                $ref: '#/components/schemas/MicrodataResponse'
        '400':
          description: Bad Request, Validation failed for the request
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                type: /problems/bad-request
                title: Bad Request
                status: 400
                detail: Bv-passkey is required
                instance: /clients/{clientId}/ugc
            text/html:
              schema:
                type: string
              example: "<html>\n  <head><title>400 Bad Request</title></head>\n  <body>\n    <h1>Bad Request</h1>\n\
                \    <p><strong>Status:</strong> 400</p>\n    <p><strong>Detail:</strong> Bv-passkey is required</p>\n\
                \    <p><strong>Type:</strong> /problems/bad-request </p>\n    <p><strong>Instance:</strong> /clients/{clientId}/ugc</p>\n\
                \  </body>\n</html>\n"
            text/javascript:
              schema:
                type: string
              example: "<script type=\"application/json\" id=\"bv-error-data\">\n{\n  \"type\": \"/problems/bad-request\"\
                ,\n  \"status\": 400,\n  \"title\": \"Bad Request\",\n  \"detail\": \"Bv-passkey is required\",\n\
                \  \"instance\": \"/clients/{clientId}/ugc\"\n}\n</script>\n"
        '401':
          description: Unauthorized
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                type: /problems/unauthorized
                title: Unauthorized
                status: 401
                detail: Invalid Bv-passkey
                instance: /clients/{clientId}/ugc
            text/html:
              schema:
                type: string
              example: "<html>\n  <head><title>401 Unauthorized</title></head>\n  <body>\n    <h1>Unauthorized</h1>\n\
                \    <p><strong>Status:</strong> 401</p>\n    <p><strong>Detail:</strong> Invalid Bv-passkey</p>\n\
                \    <p><strong>Type:</strong> /problems/unauthorized</p>\n    <p><strong>Instance:</strong> /clients/{clientId}/ugc</p>\n\
                \  </body>\n</html>\n"
            text/javascript:
              schema:
                type: string
              example: "<script type=\"application/json\" id=\"bv-error-data\">\n{\n  \"type\": \"/problems/unauthorized\"\
                ,\n  \"status\": 401,\n  \"title\": \"Unauthorized\",\n  \"detail\": \"Invalid Bv-passkey\",\n \
                \ \"instance\": \"/clients/{clientId}/ugc\"\n}\n</script>\n"
        default:
          description: Internal Server Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                type: /problems/unexpected-error
                title: Internal Server Error
                status: 500
                detail: Internal Server Error
                instance: /clients/{clientId}/ugc
            text/html:
              schema:
                type: string
              example: "<html>\n  <head><title>500 Internal Server Error</title></head>\n  <body>\n    <h1>Internal\
                \ Server Error</h1>\n    <p><strong>Status:</strong> 500</p>\n    <p><strong>Detail:</strong> Internal\
                \ Server Error</p>\n    <p><strong>Type:</strong>/problems/unexpected-error</p>\n    <p><strong>Instance:</strong>\
                \ /clients/{clientId}/ugc</p>\n  </body>\n</html>\n"
            text/javascript:
              schema:
                type: string
              example: "<script type=\"application/json\" id=\"bv-error-data\">\n  {\n    \"type\": \"/problems/unexpected-error\"\
                ,\n    \"status\": 500,\n    \"title\": \"Internal Server Error\",\n    \"detail\": \"Internal Server\
                \ Error\",\n    \"instance\": \"/clients/{clientId}/ugc\"\n  }\n</script>\n"
components:
  securitySchemes:
    Bv-passkey:
      type: apiKey
      in: header
      name: Bv-passkey
      description: Authentic discovery API key for authentication
  schemas:
    JsonLdResponseScript:
      type: string
      description: JSON-LD structured data object inside script tag which abides to google defined schema.org. Our
        Review schema - https://developers.bazaarvoice.com/v1.0-AuthenticDiscoveryAPI/docs/retreive-data-in-json-ld#review-schema-type-review,
        Aggregate Rating schema - https://developers.bazaarvoice.com/v1.0-AuthenticDiscoveryAPI/docs/retreive-data-in-json-ld#aggregaterating-schema-type-aggregaterating
      example: "<script type=\"application/ld+json\">\n{\n  \"@context\": \"https://schema.org/\",\n  \"@id\": \"\
        https://example.com/product\",\n  \"aggregateRating\": {\n    \"@type\": \"AggregateRating\",\n    \"ratingValue\"\
        : \"4.7\",\n    \"reviewCount\": 873,\n    \"bestRating\": 5\n  }\n}\n</script>\n"
    JsonLdResponseJSONFormat:
      type: object
      description: JSON-LD structured data object inside script tag
      properties:
        reviews:
          type: object
          description: contains schema outlined at https://developers.bazaarvoice.com/v1.0-AuthenticDiscoveryAPI/docs/retreive-data-in-json-ld#review-schema-type-review
        questions:
          type: object
          description: contains schema outlined at https://developers.bazaarvoice.com/v1.0-AuthenticDiscoveryAPI/docs/retreive-data-in-json-ld#question-properties
        ratings:
          type: object
          description: contains schema outlined at https://developers.bazaarvoice.com/v1.0-AuthenticDiscoveryAPI/docs/retreive-data-in-json-ld#aggregaterating-schema-type-aggregaterating
        reviewSummary:
          type: object
          description: contains schema outlined at https://developers.bazaarvoice.com/v1.0-AuthenticDiscoveryAPI/docs/retreive-data-in-json-ld#ai-summary-schema
        galleries:
          type: array
          description: Gallery structured data appended to the response based on the requested Accept format.
          items:
            type: object
            description: Schema.org structured data object for a single gallery, produced by the Media API.
      example:
        ratings:
          '@context': https://schema.org/
          '@id': https://example.com/product
          aggregateRating:
            '@type': AggregateRating
            ratingValue: '4.7'
            reviewCount: 873
            bestRating: 5
        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
    MicrodataResponse:
      type: string
      description: HTML containing Microdata tags. Review schema - https://developers.bazaarvoice.com/v1.0-AuthenticDiscoveryAPI/docs/retreive-data-in-json-ld#review-schema-type-review
        , Aggregate Rating schema - https://developers.bazaarvoice.com/v1.0-AuthenticDiscoveryAPI/docs/retreive-data-in-json-ld#aggregaterating-schema-type-aggregaterating
      example: "<div itemscope itemtype=\"https://developers.bazaarvoice.com/v1.0-AuthenticDiscoveryAPI/docs/retreive-data-in-json-ld#review-schema-type-review\"\
        \ itemid=\"https://example.com/product\">\n  <h1 itemprop=\"name\">Acne Patches</h1>\n  <div itemprop=\"\
        aggregateRating\" itemscope itemtype=\"https://developers.bazaarvoice.com/v1.0-AuthenticDiscoveryAPI/docs/retreive-data-in-json-ld#aggregaterating-schema-type-aggregaterating\"\
        >\n    Rated \n    <span itemprop=\"ratingValue\">4.7</span> out of \n    <span itemprop=\"bestRating\"\
        >5</span> based on \n    <span itemprop=\"reviewCount\">873</span> reviews.\n  </div>\n</div>\n"
    ErrorResponse:
      type: object
      required:
      - type
      - title
      - status
      - detail
      - instance
      properties:
        type:
          type: string
          format: uri-reference
        title:
          type: string
        status:
          type: integer
          format: int32
        detail:
          type: string
        instance:
          type: string