openapi: 3.0.0
info:
  title: BestBuy Search API
  description: |
    The BestBuy Search API allows you to search for products on Best Buy's website.

    **Cross-linking**: Use the `product_id` field from search results with the BestBuy Product API to fetch detailed product information.
  version: 1.0.0
servers:
  - url: https://www.searchapi.io/api/v1
paths:
  /search:
    get:
      summary: BestBuy Search
      security:
        - ApiKeyAuth: []
        - ApiKeyQuery: []
      parameters:
        - name: engine
          in: query
          required: true
          description: The search engine to use
          schema:
            type: string
            enum: ["bestbuy_search"]
            default: "bestbuy_search"
        - name: q
          in: query
          required: true
          description: The search query
          schema:
            type: string
        - name: category_id
          in: query
          required: false
          description: Filter results by BestBuy category ID
          schema:
            type: string
        - name: page
          in: query
          required: false
          description: Page number for pagination
          schema:
            type: integer
            minimum: 1
        - name: sort_by
          in: query
          required: false
          description: Sort order for results
          schema:
            type: string
            enum: ["best_match", "best_selling", "best_discount", "price_low_to_high", "price_high_to_low", "customer_rating", "new_arrivals"]
            default: "best_match"
        - name: filters
          in: query
          required: false
          description: Apply facet filters using the format `facet_type=DisplayName~Value`. Combine multiple with `,`. Copy `filter_value` from the filters response.
          schema:
            type: string
          example: "brand_facet=Brand~HP,condition_facet=Condition~New"
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResponse'
        '400':
          description: Validation Error. There is an issue with query parameters, such as missing required parameters or invalid values.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Authentication Error. The API key is missing or invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate Limit Exceeded. The number of allowed requests has been exceeded. Consider upgrading your plan or waiting for the limit to reset.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Server Error. Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Timeout. We could not retrieve results in 90 seconds.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: Authorization
      description: 'Use Bearer authentication. Format: "Bearer YOUR_API_KEY"'
    ApiKeyQuery:
      type: apiKey
      in: query
      name: api_key
      description: Pass API key as query parameter
  schemas:
    SearchResponse:
      type: object
      properties:
        search_metadata:
          $ref: '#/components/schemas/SearchMetadata'
        search_parameters:
          $ref: '#/components/schemas/SearchParameters'
        search_information:
          $ref: '#/components/schemas/SearchInformation'
        organic_results:
          type: array
          items:
            $ref: '#/components/schemas/OrganicResult'
        filters:
          type: array
          items:
            $ref: '#/components/schemas/Filter'
        related_searches:
          type: array
          items:
            $ref: '#/components/schemas/RelatedSearch'
        pagination:
          $ref: '#/components/schemas/Pagination'
        error:
          type: string
          description: Error message when no results are found
    SearchMetadata:
      type: object
      required: [id, status, created_at]
      properties:
        id:
          type: string
          description: Unique identifier for the search request
        status:
          type: string
          description: Status of the search request
        created_at:
          type: string
          format: date-time
          description: Timestamp when the search was created
        request_time_taken:
          type: number
          description: Time taken to make the request in seconds
        parsing_time_taken:
          type: number
          description: Time taken to parse the results in seconds
        total_time_taken:
          type: number
          description: Total time taken for the search in seconds
        request_url:
          type: string
          description: BestBuy URL for this search
        html_url:
          type: string
          description: URL to view HTML results
        json_url:
          type: string
          description: URL to view JSON results
    SearchParameters:
      type: object
      properties:
        engine:
          type: string
          description: Search engine used
        q:
          type: string
          description: Search query
        category_id:
          type: string
          description: Category ID filter
        page:
          type: integer
          description: Page number
        sort_by:
          type: string
          description: Sort order
        filters:
          type: string
          description: Applied facet filters
    SearchInformation:
      type: object
      required: [total_results]
      properties:
        total_results:
          type: integer
          description: Total number of results found
        query_displayed:
          type: string
          description: The query BestBuy is showing results for (may differ from original query)
        did_you_mean:
          type: string
          description: Corrected query suggested by BestBuy
    OrganicResult:
      type: object
      required: [position, product_id, title, link]
      properties:
        position:
          type: integer
          description: Position of the result in the search results
        product_id:
          type: string
          description: BestBuy SKU ID
        title:
          type: string
          description: Full product title including brand and variant
        short_title:
          type: string
          description: Shorter product title without brand prefix
        link:
          type: string
          description: URL to the product page
        brand:
          type: string
          description: Product brand
        model_number:
          type: string
          description: Manufacturer model number
        what_it_is:
          type: array
          items:
            type: string
          description: Short product category descriptions
        classification:
          $ref: '#/components/schemas/Classification'
        condition:
          type: string
          description: Product condition type
        is_new:
          type: boolean
          description: Present and `true` only when the product is new
        is_recalled:
          type: boolean
          description: Present and `true` only when the product has been recalled
        is_low_stock:
          type: boolean
          description: Present and `true` only when BestBuy flags the product as supply-constrained (e.g. just-launched flagship GPUs, console releases). Most products omit this field.
        release_date:
          type: string
          description: BestBuy release date (ISO8601). Present when BestBuy marks it as public (`streetDateDisplay == "show"`).
        rating:
          type: number
          description: Average product rating
        reviews:
          type: integer
          description: Number of reviews
        syndicated_reviews:
          type: array
          items:
            $ref: '#/components/schemas/SyndicatedReview'
          description: Cross-site review summaries (e.g. bestbuy-ca, manufacturer sites)
        price:
          type: string
          description: Formatted display price
        extracted_price:
          type: number
          description: Extracted numeric price
        original_price:
          type: string
          description: Formatted original price before discount
        extracted_original_price:
          type: number
          description: Extracted numeric original price
        discount:
          type: number
          description: Total discount amount
        discount_percentage:
          type: number
          description: Discount as a percentage of original price
        installment:
          $ref: '#/components/schemas/Installment'
        thumbnail:
          type: string
          description: URL to product thumbnail image
        images:
          type: array
          items:
            $ref: '#/components/schemas/ProductImage'
          description: Additional product images (up to 10)
        badges:
          type: array
          items:
            type: string
          description: Product badge labels
        seller:
          $ref: '#/components/schemas/Seller'
        is_sponsored:
          type: boolean
          description: Present and `true` when BestBuy promotes this listing
        member_savings:
          $ref: '#/components/schemas/MemberSavings'
        finance_option:
          $ref: '#/components/schemas/FinanceOption'
        free_gifts:
          type: array
          items:
            $ref: '#/components/schemas/FreeGift'
          description: Free-with-purchase SKUs bundled with this product
        buying_options:
          type: array
          items:
            $ref: '#/components/schemas/BuyingOption'
          description: Alternate purchase paths for this SKU (New, Open-Box tiers, etc.)
        open_box_options:
          type: array
          items:
            $ref: '#/components/schemas/OpenBoxOption'
          description: Open-box tiers offered for this SKU
        variants:
          type: array
          items:
            $ref: '#/components/schemas/Variant'
          description: Sibling SKUs representing different color, storage, or other variants
    Seller:
      type: object
      properties:
        id:
          type: string
          description: Seller ID
        name:
          type: string
          description: Seller display name (e.g. "Best Buy", "Marketplace")
    MemberSavings:
      type: object
      description: Pricing tiers for paid and non-paid Best Buy members
      properties:
        paid:
          type: number
          description: Savings available to paid members (My Best Buy Plus / Total)
        non_paid:
          type: number
          description: Savings available without a paid membership
        displayable_price:
          type: number
          description: BestBuy's headline price (may differ from extracted_price)
    FinanceOption:
      type: object
      description: Long-term financing offer (mirrors `installment` shape; this covers BestBuy's multi-month finance plans, while `installment` covers BNPL paymentOptions)
      properties:
        months:
          type: string
          description: Financing duration (e.g. "12 months")
        extracted_months:
          type: integer
          description: Number of months in the financing term
        cost_per_month:
          type: string
          description: Formatted monthly payment
        extracted_cost_per_month:
          type: number
          description: Extracted numeric monthly payment
        rate:
          type: number
          description: Annual percentage rate (0 for deferred-interest plans)
        plan_type:
          type: string
          description: Financing plan type (e.g. "Deferred")
        total_cost:
          type: number
          description: Total cost over the financing term
    FreeGift:
      type: object
      properties:
        product_id:
          type: string
        offer_id:
          type: string
        quantity:
          type: integer
        savings:
          type: number
    BuyingOption:
      type: object
      properties:
        type:
          type: string
          description: Purchase path label (e.g. "New", "Excellent", "Good", "Fair")
        link:
          type: string
          description: BestBuy URL for this purchase path
    OpenBoxOption:
      type: object
      properties:
        condition:
          type: string
          description: Open-box tier (e.g. "Excellent", "Good", "Fair")
        price:
          type: string
          description: Formatted open-box price
        extracted_price:
          type: number
          description: Extracted numeric open-box price
        savings:
          type: string
          description: Formatted savings vs. new price
        extracted_savings:
          type: number
          description: Extracted numeric savings vs. new price
        link:
          type: string
          description: BestBuy URL for the open-box listing
    Variant:
      type: object
      description: Sibling SKU representing a different color, storage, or other variant
      properties:
        value:
          type: string
          description: Variant value (e.g. "Frost Blue", "256GB")
        image:
          type: string
          description: Image URL for the variant
    Installment:
      type: object
      properties:
        months:
          type: string
          description: Installment duration (e.g. "4 months")
        extracted_months:
          type: integer
          description: Number of installments
        cost_per_month:
          type: string
          description: Formatted monthly payment
        extracted_cost_per_month:
          type: number
          description: Extracted numeric monthly payment
    Classification:
      type: object
      description: BestBuy merchandising taxonomy for the product
      properties:
        department:
          type: string
        department_id:
          type: string
        class:
          type: string
        class_id:
          type: string
        subclass:
          type: string
        subclass_id:
          type: string
    SyndicatedReview:
      type: object
      properties:
        source:
          type: string
          description: Client display name (e.g. "bestbuy-ca", "Apple Inc.")
        rating:
          type: number
          description: Overall rating from the syndicated source
        reviews:
          type: integer
          description: Total review count from the syndicated source
    ProductImage:
      type: object
      required: [link]
      properties:
        title:
          type: string
          description: Titleized image role (e.g. "Front Standard", "Angle Zoom")
        link:
          type: string
          description: URL of the image
        alt_text:
          type: string
          description: Alt text describing the image
    Filter:
      type: object
      required: [type]
      properties:
        type:
          type: string
          description: Filter display name (e.g. "Brand", "Condition", "Category")
        options:
          type: array
          items:
            $ref: '#/components/schemas/FilterOption'
    FilterOption:
      type: object
      properties:
        text:
          type: string
          description: Option display name
        items:
          type: integer
          description: Number of items matching this option
        filter_value:
          type: string
          description: Token to pass to the `filters` parameter. Combine multiple with `,`.
        link:
          type: string
          description: BestBuy URL with this option applied
        category_id:
          type: string
          description: Category ID (only on Category filters). Can be passed to `category_id` parameter.
        subcategories:
          type: array
          items:
            type: object
            properties:
              text:
                type: string
              category_id:
                type: string
          description: Nested subcategories (only on Category filters)
    RelatedSearch:
      type: object
      properties:
        query:
          type: string
          description: Related search query
        link:
          type: string
          description: URL to related search results
    Pagination:
      type: object
      properties:
        current:
          type: integer
          description: Current page number
        next:
          type: string
          description: URL to next page
        previous:
          type: string
          description: URL to previous page
        other_pages:
          type: object
          additionalProperties:
            type: string
          description: Map of page numbers to URLs
    ErrorResponse:
      type: object
      required: [error]
      properties:
        error:
          type: string
          description: Error message describing what went wrong