openapi: 3.0.3
info:
  title: Best Buy Recommendations API
  description: >-
    Leverage customer behavior data to surface relevant products through trending
    products, most viewed, also viewed, also bought, and viewed-ultimately-bought
    recommendation types. Supports queries by category ID or specific SKU.
  version: 1.0.0
  contact:
    url: https://developer.bestbuy.com
  x-generated-from: documentation
servers:
  - url: https://api.bestbuy.com/v1
    description: Best Buy API v1
security:
  - apiKey: []
tags:
  - name: Recommendations
    description: Customer behavior-based product recommendations
paths:
  /products/trendingViewed:
    get:
      operationId: getTrendingProducts
      summary: Best Buy Get Trending Products
      description: >-
        Returns the top 10 products with the highest view velocity over a rolling
        3-hour window. Requires a minimum of 50 page views per hour to qualify.
      tags:
        - Recommendations
      parameters:
        - name: apiKey
          in: query
          required: true
          description: Your Best Buy developer API key.
          schema:
            type: string
          example: YourAPIKey
        - name: categoryId
          in: query
          required: false
          description: Filter trending products to a specific category.
          schema:
            type: string
          example: abcat0500000
        - name: format
          in: query
          required: false
          description: Response format - json only for recommendations.
          schema:
            type: string
            default: json
          example: json
      responses:
        '200':
          description: Successful response with trending products.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RecommendationsResponse'
              examples:
                GetTrendingProducts200Example:
                  summary: Default getTrendingProducts 200 response
                  x-microcks-default: true
                  value:
                    metadata:
                      resultSet:
                        count: 10
                    results:
                      - sku: 1234567
                        names:
                          title: Sample Laptop 15" 16GB RAM
                        images:
                          standard: https://pisces.bbystatic.com/image2/BestBuy_US/images/products/1234/1234567_sd.jpg
                        prices:
                          regular: 999.99
                          current: 849.99
                        links:
                          product: https://api.bestbuy.com/v1/products/1234567.json
                          web: https://www.bestbuy.com/site/sample-laptop/1234567.p
                          addToCart: https://www.bestbuy.com/cart/api/v1/addToCart
                        rank: 1
        '401':
          description: Unauthorized - missing or invalid API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK

  /products/mostViewed:
    get:
      operationId: getMostViewedProducts
      summary: Best Buy Get Most Viewed Products
      description: >-
        Returns the top 10 most frequently viewed products. Data is refreshed every
        2 hours using a 48-hour accumulation window.
      tags:
        - Recommendations
      parameters:
        - name: apiKey
          in: query
          required: true
          description: Your Best Buy developer API key.
          schema:
            type: string
          example: YourAPIKey
        - name: categoryId
          in: query
          required: false
          description: Filter most viewed products to a specific category.
          schema:
            type: string
          example: abcat0500000
        - name: format
          in: query
          required: false
          description: Response format - json only.
          schema:
            type: string
            default: json
          example: json
      responses:
        '200':
          description: Successful response with most viewed products.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RecommendationsResponse'
              examples:
                GetMostViewedProducts200Example:
                  summary: Default getMostViewedProducts 200 response
                  x-microcks-default: true
                  value:
                    metadata:
                      resultSet:
                        count: 10
                    results:
                      - sku: 2345678
                        names:
                          title: Sample Smartphone 128GB
                        images:
                          standard: https://pisces.bbystatic.com/image2/BestBuy_US/images/products/2345/2345678_sd.jpg
                        prices:
                          regular: 799.99
                          current: 699.99
                        links:
                          product: https://api.bestbuy.com/v1/products/2345678.json
                          web: https://www.bestbuy.com/site/sample-smartphone/2345678.p
                          addToCart: https://www.bestbuy.com/cart/api/v1/addToCart
                        rank: 1
        '401':
          description: Unauthorized - missing or invalid API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK

  /products/{sku}/alsoViewed:
    get:
      operationId: getAlsoViewedProducts
      summary: Best Buy Get Also Viewed Products
      description: >-
        Returns products browsed alongside a specific SKU, based on a 30-day
        behavioral window of co-viewing patterns.
      tags:
        - Recommendations
      parameters:
        - name: sku
          in: path
          required: true
          description: The SKU number to get also-viewed recommendations for.
          schema:
            type: integer
          example: 1234567
        - name: apiKey
          in: query
          required: true
          description: Your Best Buy developer API key.
          schema:
            type: string
          example: YourAPIKey
        - name: format
          in: query
          required: false
          description: Response format - json only.
          schema:
            type: string
            default: json
          example: json
      responses:
        '200':
          description: Successful response with also-viewed products.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RecommendationsResponse'
              examples:
                GetAlsoViewedProducts200Example:
                  summary: Default getAlsoViewedProducts 200 response
                  x-microcks-default: true
                  value:
                    metadata:
                      resultSet:
                        count: 5
                    results:
                      - sku: 3456789
                        names:
                          title: Sample Laptop Bag 15"
                        prices:
                          regular: 49.99
                          current: 39.99
                        rank: 1
        '404':
          description: No recommendations found for the given SKU.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized - missing or invalid API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK

  /products/{sku}/alsoBought:
    get:
      operationId: getAlsoBoughtProducts
      summary: Best Buy Get Also Bought Products
      description: >-
        Returns products purchased together with a specific SKU, based on a 30-day
        purchase history window.
      tags:
        - Recommendations
      parameters:
        - name: sku
          in: path
          required: true
          description: The SKU number to get also-bought recommendations for.
          schema:
            type: integer
          example: 1234567
        - name: apiKey
          in: query
          required: true
          description: Your Best Buy developer API key.
          schema:
            type: string
          example: YourAPIKey
        - name: format
          in: query
          required: false
          description: Response format - json only.
          schema:
            type: string
            default: json
          example: json
      responses:
        '200':
          description: Successful response with also-bought products.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RecommendationsResponse'
              examples:
                GetAlsoBoughtProducts200Example:
                  summary: Default getAlsoBoughtProducts 200 response
                  x-microcks-default: true
                  value:
                    metadata:
                      resultSet:
                        count: 5
                    results:
                      - sku: 4567890
                        names:
                          title: Sample Laptop Charger
                        prices:
                          regular: 79.99
                          current: 59.99
                        rank: 1
        '404':
          description: No recommendations found for the given SKU.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized - missing or invalid API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK

components:
  securitySchemes:
    apiKey:
      type: apiKey
      in: query
      name: apiKey
      description: API key obtained by registering at developer.bestbuy.com.

  schemas:
    RecommendationsResponse:
      title: RecommendationsResponse
      type: object
      description: Response containing recommended product list.
      properties:
        metadata:
          type: object
          description: Metadata about the result set.
          properties:
            resultSet:
              type: object
              properties:
                count:
                  type: integer
                  description: Number of results returned.
                  example: 10
        results:
          type: array
          description: Array of recommended product objects.
          items:
            $ref: '#/components/schemas/RecommendedProduct'

    RecommendedProduct:
      title: RecommendedProduct
      type: object
      description: A recommended product with essential display attributes.
      properties:
        sku:
          type: integer
          description: Product SKU number.
          example: 1234567
        names:
          type: object
          description: Product name variations.
          properties:
            title:
              type: string
              description: Product display title.
              example: Sample Laptop 15" 16GB RAM
        images:
          type: object
          description: Product image URLs.
          properties:
            standard:
              type: string
              description: Standard product image URL.
              example: https://pisces.bbystatic.com/image2/BestBuy_US/images/products/1234/1234567_sd.jpg
        prices:
          type: object
          description: Product pricing information.
          properties:
            regular:
              type: number
              format: double
              description: Regular price in USD.
              example: 999.99
            current:
              type: number
              format: double
              description: Current (sale) price in USD.
              example: 849.99
        links:
          type: object
          description: Related URLs for the product.
          properties:
            product:
              type: string
              description: API URL for full product data.
              example: https://api.bestbuy.com/v1/products/1234567.json
            web:
              type: string
              description: URL of the product page on bestbuy.com.
              example: https://www.bestbuy.com/site/sample-laptop/1234567.p
            addToCart:
              type: string
              description: URL for adding to cart.
              example: https://www.bestbuy.com/cart/api/v1/addToCart
        rank:
          type: integer
          description: Rank position in the recommendation list.
          example: 1

    ErrorResponse:
      title: ErrorResponse
      type: object
      description: Error response returned when a request fails.
      properties:
        status:
          type: integer
          description: HTTP status code.
          example: 400
        error:
          type: string
          description: Error type or code.
          example: Bad Request
        message:
          type: string
          description: Human-readable description of the error.
          example: Invalid query parameter provided.