openapi: 3.0.0
info:
  title: Bing Product API
  description: |
    Bing Product API returns structured product page data from Bing Shopping, including product details, variations, rating breakdowns, customer review topic insights, buying options from multiple sellers, Bing's price history for the product, and related product suggestions.

    **Cross-linking**: This API is designed to be used with the Bing Shopping API. First call Bing Shopping to get shopping results, then pass any shopping_results[].product_token value to this API as the product_token parameter to fetch the full product page.
  version: 1.0.0
servers:
  - url: https://www.searchapi.io/api/v1
paths:
  /search:
    get:
      summary: Bing Product Page
      security:
        - ApiKeyAuth: []
        - ApiKeyQuery: []
      parameters:
        - name: engine
          in: query
          required: true
          description: Set to bing_product
          schema:
            type: string
            enum: ["bing_product"]
        - name: product_token
          in: query
          required: true
          description: Product token obtained from the product_token field of a Bing Shopping API response. Carries the product identifiers needed to reach the product page.
          schema:
            type: string
        - name: market_code
          in: query
          required: false
          description: Market code combining language and country (e.g., en-US, de-DE). Cannot be used together with country_code.
          schema:
            type: string
            enum: ["es-ar", "en-au", "de-at", "nl-be", "fr-be", "pt-br", "en-ca", "fr-ca", "es-cl", "da-dk", "fi-fi", "fr-fr", "de-de", "zh-hk", "en-in", "en-id", "it-it", "ja-jp", "ko-kr", "en-my", "es-mx", "nl-nl", "en-nz", "no-no", "zh-cn", "pl-pl", "en-ph", "ru-ru", "en-za", "es-es", "sv-se", "fr-ch", "de-ch", "zh-tw", "tr-tr", "en-gb", "en-us", "es-us"]
        - name: country_code
          in: query
          required: false
          description: Country code (ISO 3166-1 alpha-2). Defaults to US if market_code is not set. Cannot be used together with market_code.
          schema:
            type: string
            enum: ["AR", "AU", "AT", "BE", "BR", "CA", "CL", "DK", "FI", "FR", "DE", "HK", "IN", "ID", "IT", "JP", "KR", "MY", "MX", "NL", "NZ", "NO", "PL", "PT", "PH", "RU", "SA", "ZA", "ES", "SE", "CH", "TW", "TR", "GB", "US", "CN"]
            default: "US"
        - name: language
          in: query
          required: false
          description: Language code for user interface text
          schema:
            type: string
            enum: ["ar", "eu", "bn", "bg", "ca", "zh-hans", "zh-hant", "hr", "cs", "da", "nl", "en", "en-gb", "et", "fi", "fr", "gl", "de", "gu", "he", "hi", "hu", "is", "it", "ja", "jp", "kn", "ko", "lv", "lt", "ms", "ml", "mr", "nb", "pl", "pt-br", "pt-pt", "pa", "ro", "ru", "sr", "sk", "sl", "sv", "ta", "te", "th", "tr", "uk", "vi"]
      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.
          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'
        error:
          type: string
          description: Set on a successful response when the product page rendered no buying options (e.g., "Bing Product is not available in the selected country/market." or "Bing Product didn't return any product information."). When present, response blocks below are omitted.
        product:
          $ref: '#/components/schemas/Product'
        offers:
          type: array
          items:
            $ref: '#/components/schemas/Offer'
        price_history:
          $ref: '#/components/schemas/PriceHistory'
        top_insights:
          type: array
          items:
            $ref: '#/components/schemas/TopInsightGroup'
        review_summary:
          $ref: '#/components/schemas/ReviewSummary'
        popular_opinions:
          type: array
          items:
            $ref: '#/components/schemas/PopularOpinion'
        related_products:
          type: array
          items:
            $ref: '#/components/schemas/RelatedProduct'
        sponsored_related_products:
          type: array
          description: Paid placements rendered in the "Sponsored similar products" carousel; same shape as related_products
          items:
            $ref: '#/components/schemas/RelatedProduct'
        related_searches:
          type: array
          description: Suggested follow-up shopping queries shown by Bing for this product
          items:
            $ref: '#/components/schemas/RelatedSearch'
    RelatedSearch:
      type: object
      required: [query, link]
      properties:
        query:
          type: string
          description: Search term as displayed
        link:
          type: string
          description: Bing shop URL to run that search
    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: Bing Shopping product page 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
        product_token:
          type: string
          description: Product token used to identify the product
        country_code:
          type: string
          description: Country code used
        market_code:
          type: string
          description: Market code used
        language:
          type: string
          description: Language used
    Product:
      type: object
      required: [title]
      properties:
        product_id:
          type: string
          description: Bing's identifier for the product page
        title:
          type: string
          description: Product title
        description:
          type: string
          description: Product description text
        rating:
          type: number
          format: float
          description: Average customer rating (0 to 5)
        reviews:
          type: integer
          description: Total number of customer reviews
        thumbnail:
          type: string
          description: URL of the primary product thumbnail image
        images:
          type: array
          description: All product images from the carousel (URLs include the same image at higher resolution than `thumbnail`)
          items:
            type: string
        reviews_histogram:
          type: object
          description: Share of reviews per star level, as integer percentages keyed by star count ("1" through "5")
          additionalProperties:
            type: integer
        variations:
          type: array
          description: Product variation groups (e.g., Storage Capacity, Color)
          items:
            $ref: '#/components/schemas/Variation'
        specifications:
          type: array
          description: Product specification pairs as rendered by Bing (e.g., Processor, Camera Resolution, Battery Life). Both name and value are localized to the request market.
          items:
            $ref: '#/components/schemas/Specification'
    Specification:
      type: object
      required: [name, value]
      properties:
        name:
          type: string
          description: Specification label (e.g., "Storage Capacity")
        value:
          type: string
          description: Specification value (e.g., "128 GB")
    Variation:
      type: object
      description: |-
        Variation groups represent filters applicable to the parent product
        (e.g. Storage Capacity, Color). Bing handles variant selection via
        AJAX on the same product page rather than dedicated per-variant
        product pages, so individual options do not have their own product_token.
      required: [title, options]
      properties:
        title:
          type: string
          description: Variation group name (e.g., Storage Capacity, Color)
        options:
          type: array
          items:
            $ref: '#/components/schemas/VariationOption'
    VariationOption:
      type: object
      required: [title]
      properties:
        title:
          type: string
          description: Variation option name as rendered by Bing (e.g., "128 GB", "Black"; localized to the request market)
        image:
          type: string
          description: Thumbnail image URL for the option, when Bing renders one (typically color swatches; omitted for non-visual filters like Storage Capacity)
    Offer:
      type: object
      required: [position, merchant]
      properties:
        position:
          type: integer
          description: Position of the offer in the buying-options list
        is_sponsored:
          type: boolean
          description: Whether this offer is a sponsored placement
        title:
          type: string
          description: Offer-specific product title
        link:
          type: string
          description: Bing tracking URL that redirects to the merchant's product page
        price:
          type: string
          description: Current price as displayed
        extracted_price:
          type: number
          description: Numeric value extracted from price
        original_price:
          type: string
          description: List price, present only when discounted
        extracted_original_price:
          type: number
          description: Numeric value extracted from original_price
        currency:
          type: string
          description: Currency symbol used for price and original_price (e.g., "$", "€")
        delivery_price:
          type: string
          description: Delivery information (e.g., "Free shipping")
        installment:
          $ref: '#/components/schemas/Installment'
        merchant:
          $ref: '#/components/schemas/Merchant'
        advertiser:
          $ref: '#/components/schemas/Advertiser'
    Advertiser:
      type: object
      description: Microsoft Advertising disclosure block, present on sponsored offers
      properties:
        name:
          type: string
          description: Advertiser name (e.g., "T-Mobile")
        location:
          type: string
          description: Advertiser location (e.g., "United States")
    Merchant:
      type: object
      required: [name]
      properties:
        name:
          type: string
          description: Merchant name
        favicon:
          type: string
          description: URL of the merchant's favicon or seller logo
    Installment:
      type: object
      properties:
        down_payment:
          type: string
          description: Upfront payment as displayed
        extracted_down_payment:
          type: number
          description: Numeric value extracted from down_payment
        months:
          type: string
          description: Installment period as displayed (e.g., "x 24")
        extracted_months:
          type: integer
          description: Numeric value extracted from months
        cost_per_month:
          type: string
          description: Monthly cost as displayed (e.g., "$30.42/mo")
        extracted_cost_per_month:
          type: number
          description: Numeric value extracted from cost_per_month
    RelatedProductInstallment:
      type: object
      properties:
        months:
          type: string
          description: Installment period as displayed (e.g., "x 24")
        extracted_months:
          type: integer
          description: Numeric value extracted from months
        cost_per_month:
          type: string
          description: Monthly cost as displayed (e.g., "$30.42/mo")
        extracted_cost_per_month:
          type: number
          description: Numeric value extracted from cost_per_month
    PriceHistory:
      type: object
      properties:
        trend:
          type: string
          enum: ["stable", "drop", "increase"]
          description: Current price trend relative to the recent median (>=2% above = "increase", >=2% below = "drop", otherwise "stable")
        median_price:
          type: string
          description: Recent median price (computed over the last 30 data points in history), formatted with the product's currency symbol
        extracted_median_price:
          type: number
          description: Numeric value of median_price
        history:
          type: array
          description: Time series of median prices
          items:
            $ref: '#/components/schemas/PriceHistoryEntry'
    PriceHistoryEntry:
      type: object
      required: [date, extracted_price]
      properties:
        date:
          type: string
          description: ISO 8601 date (YYYY-MM-DD) of the data point
        extracted_price:
          type: number
          description: Median price on this date
    TopInsightGroup:
      type: object
      properties:
        title:
          type: string
          description: Insight group heading as rendered by Bing (localized; e.g., "Reviewed by customers" on en-US)
        items:
          type: array
          items:
            $ref: '#/components/schemas/TopInsightItem'
    TopInsightItem:
      type: object
      required: [title]
      properties:
        title:
          type: string
          description: Customer review topic name (e.g., "Great Audio Quality")
        snippet:
          type: string
          description: Customer sentiment summary for the topic
    ReviewSummary:
      type: object
      description: AI-generated summary of customer reviews, including a narrative paragraph and pros/cons lists. Only present on products where Bing renders the "Review summary" section; text content is localized to the request market.
      properties:
        summary:
          type: string
          description: AI-generated narrative summary of the customer reviews
        pros:
          type: array
          description: Short positive bullets drawn from reviews
          items:
            type: string
        cons:
          type: array
          description: Short negative bullets drawn from reviews
          items:
            type: string
    PopularOpinion:
      type: object
      description: Individual customer review as rendered in Bing's "Popular opinions" section.
      required: [position]
      properties:
        position:
          type: integer
          description: 1-indexed position of the review in the list
        rating:
          type: number
          format: float
          description: Reviewer's star rating (0 to 5)
        title:
          type: string
          description: Review title as rendered by the source site (often truncated by Bing with a trailing ellipsis)
        text:
          type: string
          description: Full review text
        username:
          type: string
          description: Reviewer display name
        source:
          type: string
          description: Domain of the site the review was syndicated from (e.g., "www.walmart.com")
        date:
          type: string
          description: Review date as formatted by Bing (localized; e.g., "Dec 08, 2025")
    RelatedProduct:
      type: object
      required: [position, product_id, title, link]
      properties:
        position:
          type: integer
          description: Position in the related products carousel
        product_id:
          type: string
          description: Bing offer identifier for the related product
        title:
          type: string
          description: Related product title
        link:
          type: string
          description: Bing tracking URL for the related product
        price:
          type: string
          description: Related product price as displayed
        extracted_price:
          type: number
          description: Numeric value extracted from price
        original_price:
          type: string
          description: Original (pre-discount) price as displayed, shown only when the related product is on sale
        extracted_original_price:
          type: number
          description: Numeric value extracted from original_price
        rating:
          type: number
          format: float
          description: Average customer rating for the related product (0 to 5)
        reviews:
          oneOf:
            - type: integer
            - type: string
          description: Number of customer reviews. Returns an integer when Bing renders an exact count (e.g. `316`) and a string when Bing renders an abbreviated count (e.g. `1K+`).
        seller:
          type: string
          description: Seller name for the related product
        thumbnail:
          type: string
          description: URL of the related product's thumbnail image
        installment:
          $ref: '#/components/schemas/RelatedProductInstallment'
    ErrorResponse:
      type: object
      required: [error]
      properties:
        error:
          type: string
          description: Error message describing what went wrong