openapi: 3.0.0
info:
  title: Bing Videos API
  description: |
    The Bing Videos API allows you to search for video content across the web using the Bing search engine. This API provides access to video results with metadata including titles, durations, sources, view counts, and thumbnails.

    **Cross-linking**: The video IDs and URLs returned by this API can be used with other APIs to fetch additional information. Video links lead to the source platform where the video is hosted (YouTube, Vimeo, etc.).
  version: 1.0.0
servers:
  - url: https://www.searchapi.io/api/v1
paths:
  /search:
    get:
      summary: Bing Videos Search
      security:
        - ApiKeyAuth: []
        - ApiKeyQuery: []
      parameters:
        - name: engine
          in: query
          required: true
          description: Search engine to use. Must be set to bing_videos.
          schema:
            type: string
            enum: ["bing_videos"]
        - name: q
          in: query
          required: true
          description: Search query
          schema:
            type: string
        - name: device
          in: query
          required: false
          description: Device type for search results
          schema:
            type: string
            enum: ["desktop", "mobile"]
            default: "desktop"
        - name: market_code
          in: query
          required: false
          description: Market code for localized results
          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 for results localization
          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 interface and results
          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", "jp", "kn", "ko", "lv", "lt", "ms", "ml", "mr", "nb", "pl", "pt-br", "pt-pt", "pa", "ro", "ru", "sr", "sk", "sl", "es", "sv", "ta", "te", "th", "tr", "uk", "vi"]
        - name: safe_search
          in: query
          required: false
          description: Safe search filter level
          schema:
            type: string
            enum: ["off", "moderate", "strict"]
            default: "moderate"
        - name: duration
          in: query
          required: false
          description: Filter videos by duration
          schema:
            type: string
            enum: ["short", "medium", "long"]
        - name: time_period
          in: query
          required: false
          description: Filter videos by upload time
          schema:
            type: string
            enum: ["last_day", "last_week", "last_month", "last_year"]
        - name: quality
          in: query
          required: false
          description: Filter videos by quality/resolution
          schema:
            type: string
            enum: ["lower_than_360p", "360p_or_higher", "480p_or_higher", "720p_or_higher", "1080p_or_higher"]
        - name: source
          in: query
          required: false
          description: Filter videos by source platform
          schema:
            type: string
            enum: ["dailymotion", "vimeo", "metacafe", "hulu", "vevo", "myspace", "mtv", "cbs", "fox", "cnn", "msn"]
        - name: price
          in: query
          required: false
          description: Filter videos by price
          schema:
            type: string
            enum: ["free", "paid"]
        - name: page
          in: query
          required: false
          description: Page number for pagination
          schema:
            type: integer
      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'
        error:
          type: string
          description: Error message when no results found
        suggestions:
          type: array
          description: Search suggestions
          items:
            $ref: '#/components/schemas/Suggestion'
        shopping_ads:
          type: array
          description: Shopping advertisements
          items:
            $ref: '#/components/schemas/ShoppingAd'
        videos:
          type: array
          description: Main video results
          items:
            $ref: '#/components/schemas/Video'
        shorts:
          type: array
          description: Short-form video results
          items:
            $ref: '#/components/schemas/Video'
        related_searches:
          type: array
          description: Related search queries
          items:
            $ref: '#/components/schemas/RelatedSearch'
        ads:
          type: array
          description: Text advertisements
          items:
            $ref: '#/components/schemas/Ad'
        pagination:
          $ref: '#/components/schemas/Pagination'
    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 Videos 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
        device:
          type: string
          description: Device type used for search
        country_code:
          type: string
          description: Country code used
        market_code:
          type: string
          description: Market code used
        language:
          type: string
          description: Language code used
        safe_search:
          type: string
          description: Safe search setting used
        duration:
          type: string
          description: Duration filter used
        time_period:
          type: string
          description: Time period filter used
        quality:
          type: string
          description: Quality filter used
        source:
          type: string
          description: Source filter used
        price:
          type: string
          description: Price filter used
        page:
          type: integer
          description: Page number
    SearchInformation:
      type: object
      properties:
        query_displayed:
          type: string
          description: Query as displayed by Bing
        including_results_for:
          type: string
          description: Alternative query suggestion when showing results for a different query
        safe_search:
          type: string
          description: Safe search setting applied
    Video:
      type: object
      required: [position, title, link, source, date, thumbnail]
      properties:
        position:
          type: integer
          description: Position in search results
        title:
          type: string
          description: Video title
        link:
          type: string
          description: Direct link to video
        snippet:
          type: string
          description: Video description or snippet
        length:
          type: string
          description: Video duration
        source:
          type: string
          description: Source platform of the video
        date:
          type: string
          description: Publication date
        channel:
          type: string
          description: Channel or uploader name
        views:
          type: integer
          description: Number of views
        is_paid:
          type: boolean
          description: Whether the video is paid content
        thumbnail:
          type: string
          description: Video thumbnail URL
    Suggestion:
      type: object
      required: [title, link]
      properties:
        title:
          type: string
          description: Suggestion text
        link:
          type: string
          description: Link to execute the suggested search
        thumbnail:
          type: string
          description: Thumbnail image for the suggestion
    RelatedSearch:
      type: object
      required: [query, link]
      properties:
        query:
          type: string
          description: Related search query
        link:
          type: string
          description: Link to execute the related search
        thumbnail:
          type: string
          description: Thumbnail for the related search
    ShoppingAd:
      type: object
      required: [position, title, link, price, extracted_price, seller]
      properties:
        position:
          type: integer
          description: Position in shopping results
        title:
          type: string
          description: Product title
        seller:
          type: string
          description: Seller name
        link:
          type: string
          description: Product link
        deal:
          type: string
          description: Special deal or badge text
        price:
          type: string
          description: Product price as displayed
        extracted_price:
          type: number
          description: Numeric price value
        original_price:
          type: string
          description: Original price if on sale
        extracted_original_price:
          type: number
          description: Numeric original price
        installment:
          type: object
          description: Installment payment options
          properties:
            down_payment:
              type: string
              description: Down payment amount
            extracted_down_payment:
              type: number
              description: Numeric down payment
            months:
              type: string
              description: Payment term in months
            extracted_months:
              type: integer
              description: Numeric months value
            cost_per_month:
              type: string
              description: Monthly payment amount
            extracted_cost_per_month:
              type: number
              description: Numeric monthly cost
        rating:
          type: number
          description: Product rating
        reviews:
          type: integer
          description: Number of reviews
        reviews_link:
          type: string
          description: Link to product reviews
        delivery_price:
          type: string
          description: Delivery cost
        extracted_delivery_price:
          type: number
          description: Numeric delivery cost
        image:
          type: string
          description: Product image URL (when single image)
        images:
          type: array
          description: Product image URLs (when multiple images)
          items:
            type: string
    Ad:
      type: object
      required: [title, link, displayed_link, tracking_link]
      properties:
        position:
          type: integer
          description: Ad position
        block_position:
          type: string
          description: Block position (top, right, middle, bottom)
        title:
          type: string
          description: Ad title
        link:
          type: string
          description: Destination URL
        source:
          type: string
          description: Source domain
        displayed_link:
          type: string
          description: Display URL
        tracking_link:
          type: string
          description: Tracking URL
        snippet:
          type: string
          description: Ad description
        is_app:
          type: boolean
          description: Whether this is an app ad
        sitelinks:
          type: object
          description: Ad sitelinks
          properties:
            inline:
              type: array
              items:
                type: object
                required: [title, link]
                properties:
                  title:
                    type: string
                  link:
                    type: string
            expanded:
              type: array
              items:
                type: object
                properties:
                  title:
                    type: string
                  link:
                    type: string
                  snippet:
                    type: string
            list:
              type: array
              items:
                type: object
                required: [title, link]
                properties:
                  title:
                    type: string
                  link:
                    type: string
                  source:
                    type: string
        assets:
          type: object
          description: Ad extensions and assets
          properties:
            rating:
              type: number
              description: Rating score
            reviews:
              type: integer
              description: Number of reviews
            structured_snippet:
              type: object
              properties:
                title:
                  type: string
                text:
                  type: string
            action:
              type: object
              properties:
                text:
                  type: string
                link:
                  type: string
            prices:
              type: array
              items:
                type: object
                properties:
                  title:
                    type: string
                  price:
                    type: string
                  extracted_price:
                    type: number
                  description:
                    type: string
                  link:
                    type: string
            promotion:
              type: object
              properties:
                title:
                  type: string
                link:
                  type: string
            application:
              type: object
              properties:
                title:
                  type: string
                link:
                  type: string
                text:
                  type: string
            call_to_action:
              type: object
              properties:
                text:
                  type: string
                link:
                  type: string
            extensions:
              type: array
              items:
                type: string
        more_link:
          type: string
          description: Link to more results from this advertiser
        images:
          type: array
          description: Ad images
          items:
            type: string
        thumbnail:
          type: string
          description: Ad thumbnail
    Pagination:
      type: object
      required: [current]
      properties:
        current:
          type: integer
          description: Current page number
        previous:
          type: string
          description: URL for previous page
        next:
          type: string
          description: URL for next page
    ErrorResponse:
      type: object
      required: [error]
      properties:
        error:
          type: string
          description: Error message describing what went wrong