openapi: 3.0.0
info:
  title: Bing News API
  description: |
    Search for news articles using Microsoft Bing News. Get the latest news from various sources with advanced filtering options.

    **Cross-linking**: The links returned in organic_results, trending, and related_topics point to external news sources.
  version: 1.0.0
servers:
  - url: https://www.searchapi.io/api/v1
paths:
  /search:
    get:
      summary: Bing News Search
      security:
        - ApiKeyAuth: []
        - ApiKeyQuery: []
      parameters:
        - name: engine
          in: query
          required: true
          description: Engine to use for the search
          schema:
            type: string
            enum: ["bing_news"]
        - name: q
          in: query
          required: false
          description: Search query. Required unless category parameter is provided.
          schema:
            type: string
        - name: device
          in: query
          required: false
          description: Device type for search results
          schema:
            type: string
        - 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", "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"]
            default: "en-us"
        - name: country_code
          in: query
          required: false
          description: Country code for filtering results
          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"]
        - name: language
          in: query
          required: false
          description: Language code for 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 filtering level
          schema:
            type: string
            enum: ["off", "moderate", "strict"]
        - name: category
          in: query
          required: false
          description: News category to filter by. Can be used instead of q parameter.
          schema:
            type: string
        - name: time_period
          in: query
          required: false
          description: Time period for filtering news articles
          schema:
            type: string
            enum: ["last_minute", "last_5_minutes", "last_15_minutes", "last_30_minutes", "last_hour", "last_4_hours", "last_6_hours", "last_24_hours", "last_7_days", "last_30_days"]
        - name: sort_by
          in: query
          required: false
          description: Sort order for results
          schema:
            type: string
            enum: ["most_recent"]
        - name: page
          in: query
          required: false
          description: Page number for pagination
          schema:
            type: integer
            minimum: 1
        - name: num
          in: query
          required: false
          description: Number of results per page
          schema:
            type: integer
            minimum: 1
      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'
        organic_results:
          type: array
          items:
            $ref: '#/components/schemas/OrganicResult'
          description: Array of news articles from the search results
        trending:
          type: array
          items:
            $ref: '#/components/schemas/TrendingItem'
          description: Array of trending news topics
        related_topics:
          type: array
          items:
            $ref: '#/components/schemas/RelatedTopic'
          description: Array of related search topics
        error:
          type: string
          description: Error message if no results 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: Bing News 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:
        q:
          type: string
          description: Search query used
        category:
          type: string
          description: News category used
        device:
          type: string
          description: Device type used
        market_code:
          type: string
          description: Market code used
        country_code:
          type: string
          description: Country code used
        language:
          type: string
          description: Language code used
        time_period:
          type: string
          description: Time period filter used
        sort_by:
          type: string
          description: Sort order used
        safe_search:
          type: string
          description: Safe search setting used
        page:
          type: integer
          description: Page number used
        num:
          type: integer
          description: Number of results per page used
    OrganicResult:
      type: object
      required: [position, title, link, source, date, snippet, favicon]
      properties:
        position:
          type: integer
          description: Position of the result in the search results
        title:
          type: string
          description: Title of the news article
        link:
          type: string
          description: URL to the news article
        source:
          type: string
          description: Source publication of the article
        date:
          type: string
          description: Publication date of the article
        snippet:
          type: string
          description: Brief excerpt from the article
        favicon:
          type: string
          description: URL to the favicon of the source
        thumbnail:
          type: string
          description: URL to the thumbnail image for the article
    TrendingItem:
      type: object
      required: [topic, link, thumbnail]
      properties:
        topic:
          type: string
          description: Trending topic title
        link:
          type: string
          description: URL to the trending topic
        thumbnail:
          type: string
          description: URL to the thumbnail image for the trending topic
    RelatedTopic:
      type: object
      required: [query, link]
      properties:
        query:
          type: string
          description: Related search query
        link:
          type: string
          description: URL to perform the related search
    ErrorResponse:
      type: object
      required: [error]
      properties:
        error:
          type: string
          description: Error message describing what went wrong