openapi: 3.0.3
info:
  title: Bing News Search API v7 News Category API
  description: The Bing News Search REST API enables developers to retrieve relevant news articles, trending topics, and category-filtered news with image thumbnails and publisher metadata. The API provides search queries against Bing's news index, returning results with titles, descriptions, URLs, publication dates, and related media content.
  version: '7.0'
  contact:
    name: Microsoft Bing Support
    url: https://learn.microsoft.com/en-us/answers/tags/142/bing-category-bing-search-apis-azure-bing-news
  termsOfService: https://www.microsoft.com/en-us/bing/apis/legal
  license:
    name: Microsoft Bing APIs Terms of Use
    url: https://www.microsoft.com/en-us/bing/apis/legal
  x-api-id: bing-news
  x-retired: true
  x-retirement-note: Bing Search APIs are retired as a standalone Azure Cognitive Service. Existing subscriptions were honored through October 2023.
servers:
- url: https://api.bing.microsoft.com/v7.0
  description: Bing News Search API v7
security:
- ApiKeyAuth: []
tags:
- name: News Category
  description: Get top news articles by category
paths:
  /news:
    get:
      operationId: NewsByCategory
      summary: Get Top News by Category
      description: Returns top news articles filtered by category (e.g., Business, Entertainment, Sports, Health, ScienceAndTechnology, Politics, World). Supports multiple markets with locale-specific category taxonomies. No search query is required; results reflect top headlines for the chosen category in the specified market.
      tags:
      - News Category
      parameters:
      - $ref: '#/components/parameters/OcpApimSubscriptionKey'
      - name: category
        in: query
        required: false
        description: The category of news articles to return. Use this parameter only with the /news endpoint. If not specified, the response includes up to 10 headline news articles typically published in the last 24 hours from any category.
        schema:
          type: string
          example: Sports
      - $ref: '#/components/parameters/mkt'
      - $ref: '#/components/parameters/cc'
      - $ref: '#/components/parameters/setLang'
      - $ref: '#/components/parameters/safeSearch'
      - $ref: '#/components/parameters/textDecorations'
      - $ref: '#/components/parameters/textFormat'
      responses:
        '200':
          description: Successful category news response
          headers:
            BingAPIs-Market:
              $ref: '#/components/headers/BingAPIs-Market'
            BingAPIs-TraceId:
              $ref: '#/components/headers/BingAPIs-TraceId'
            X-MSEdge-ClientID:
              $ref: '#/components/headers/X-MSEdge-ClientID'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NewsAnswer'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Too Many Requests
          headers:
            Retry-After:
              description: Number of seconds to wait before sending another request
              schema:
                type: integer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  headers:
    BingAPIs-Market:
      description: The market used by the request. The form is <languageCode>-<countryCode>. For example, en-US.
      schema:
        type: string
    X-MSEdge-ClientID:
      description: Bing uses this header to provide users with consistent behavior across Bing API calls. Persist and reuse across sessions for a given user on a given device.
      schema:
        type: string
    BingAPIs-TraceId:
      description: The ID of the log entry that contains the details of the request. Capture this ID when an error occurs.
      schema:
        type: string
  parameters:
    OcpApimSubscriptionKey:
      name: Ocp-Apim-Subscription-Key
      in: header
      required: true
      description: The subscription key that you received when you signed up for this service in Azure Portal.
      schema:
        type: string
    mkt:
      name: mkt
      in: query
      required: false
      description: The market where the results come from. Typically the country where the user is making the request from. The market must be in the form <language>-<country/region>. For example, en-US. This parameter and the cc query parameter are mutually exclusive.
      schema:
        type: string
        example: en-US
    safeSearch:
      name: safeSearch
      in: query
      required: false
      description: Used to filter news articles for adult content. The default is Moderate.
      schema:
        type: string
        enum:
        - 'Off'
        - Moderate
        - Strict
        default: Moderate
    textDecorations:
      name: textDecorations
      in: query
      required: false
      description: A Boolean value that determines whether display strings in the results should contain decoration markers such as hit highlighting characters. The default is false.
      schema:
        type: boolean
        default: false
    setLang:
      name: setLang
      in: query
      required: false
      description: The language to use for user interface strings. You may specify the language using either a 2-letter or 4-letter code. This parameter and the Accept-Language header are mutually exclusive.
      schema:
        type: string
        example: en
    cc:
      name: cc
      in: query
      required: false
      description: A 2-character country code of the country where the results come from. If you set this parameter, you must also specify the Accept-Language header. This parameter and the mkt query parameter are mutually exclusive.
      schema:
        type: string
        minLength: 2
        maxLength: 2
        example: US
    textFormat:
      name: textFormat
      in: query
      required: false
      description: The type of markers to use for text decorations (see the textDecorations query parameter). Raw uses Unicode characters; HTML uses HTML tags.
      schema:
        type: string
        enum:
        - Raw
        - HTML
        default: Raw
  schemas:
    Error:
      type: object
      description: Defines the error that occurred.
      properties:
        code:
          type: string
          description: The error code that identifies the category of error.
        message:
          type: string
          description: A description of the error.
        moreDetails:
          type: string
          description: A description that provides additional information about the error.
        parameter:
          type: string
          description: The query parameter in the request that caused the error.
        subCode:
          type: string
          description: The error code that identifies the error.
        value:
          type: string
          description: The query parameter's value that was not valid.
    SortValue:
      type: object
      description: Defines a sort order to use for the request.
      properties:
        id:
          type: string
          description: An identifier that identifies the articles sort order.
          enum:
          - date
          - relevance
        isSelected:
          type: boolean
          description: A Boolean value that determines whether the response used this sort order.
        name:
          type: string
          description: The display name of the sort order.
        url:
          type: string
          description: A URL that you can use to make the same request using this sort order.
    RelatedTopic:
      type: object
      description: Defines a list of news articles that are related to the search query.
      properties:
        relatedNews:
          $ref: '#/components/schemas/NewsArticle'
          description: A list of related news articles.
        name:
          type: string
          description: The query term that returned the related news articles.
        webSearchUrl:
          type: string
          description: A URL that takes the user to the Bing search results for the related query.
    MediaSize:
      type: object
      description: Defines the size of the media content.
      properties:
        height:
          type: integer
          description: The height of the media content, in pixels.
        width:
          type: integer
          description: The width of the media content, in pixels.
    Thumbnail:
      type: object
      description: Defines a link to the related image.
      properties:
        contentUrl:
          type: string
          description: The URL to the image.
        height:
          type: integer
          description: The height of the image in pixels.
        width:
          type: integer
          description: The width of the image in pixels.
    ErrorResponse:
      type: object
      description: The top-level object that the response includes when the request fails.
      properties:
        _type:
          type: string
          description: Type hint, which is set to ErrorResponse.
        errors:
          type: array
          description: A list of errors that describe the reasons why the request failed.
          items:
            $ref: '#/components/schemas/Error'
    NewsArticle:
      type: object
      description: Defines a news article.
      properties:
        about:
          type: array
          description: For internal use only.
          items:
            type: object
        category:
          type: string
          description: The news category that the article belongs to. For example, Sports. If the news category cannot be determined, the article does not include this field.
        clusteredArticles:
          type: array
          description: A list of related news articles.
          items:
            $ref: '#/components/schemas/NewsArticle'
        contractualRules:
          type: array
          description: A list of rules that you must adhere to if you display the article.
          items:
            type: object
        datePublished:
          type: string
          description: The date and time that Bing discovered the article. The date is in the format YYYY-MM-DDTHH:MM:SS.
          example: '2024-01-15T14:30:00'
        description:
          type: string
          description: A short description of the news article.
        headline:
          type: boolean
          description: A Boolean value that indicates whether the news article is a headline. Included only for news categories requests that do not specify the category query parameter.
        id:
          type: string
          description: An ID that uniquely identifies this article in the list of articles.
        image:
          $ref: '#/components/schemas/Image'
          description: An image related to the news article. The Image object in this context contains only the thumbnail field.
        mentions:
          type: array
          description: A list of entities (places or persons) mentioned in the article.
          items:
            $ref: '#/components/schemas/Thing'
        name:
          type: string
          description: The name of the article. Use this name along with the URL to create a hyperlink.
        provider:
          type: array
          description: A list of providers that ran the article.
          items:
            $ref: '#/components/schemas/Organization'
        url:
          type: string
          description: A URL to the news article. Use this URL along with name to create a hyperlink.
        video:
          $ref: '#/components/schemas/Video'
          description: A video that's related to the news article.
    NewsAnswer:
      type: object
      description: The top-level object that the response includes when the news request succeeds.
      properties:
        _type:
          type: string
          description: Type hint.
        id:
          type: string
          description: An ID that uniquely identifies the news answer. Only Web Search API responses include this field.
        readLink:
          type: string
          description: A URL to request news from News Search API. Only Web Search API responses include this field.
        relatedTopics:
          type: array
          description: A list of news articles that are related to the search term. Only the News Search API includes this field.
          items:
            $ref: '#/components/schemas/RelatedTopic'
        sort:
          type: array
          description: A list of options for sorting the news articles. Only the News Search API includes this field.
          items:
            $ref: '#/components/schemas/SortValue'
        totalEstimatedMatches:
          type: integer
          format: int64
          description: The estimated number of news articles that are relevant to the query. Only the News Search API includes this field.
        value:
          type: array
          description: A list of news articles that are relevant to the query term. If there are no results to return, the array is empty.
          items:
            $ref: '#/components/schemas/NewsArticle'
        webSearchUrl:
          type: string
          description: A URL to the top news stories on Bing. Included only for /news requests.
    Image:
      type: object
      description: Defines a thumbnail image.
      properties:
        provider:
          type: array
          description: A list of owners of the image.
          items:
            $ref: '#/components/schemas/Organization'
        thumbnail:
          $ref: '#/components/schemas/Thumbnail'
          description: A link to a thumbnail of the image.
        url:
          type: string
          description: A URL to the image.
    Thing:
      type: object
      description: Defines an entity that the article mentions.
      properties:
        name:
          type: string
          description: The name of the entity that the article mentions.
    Organization:
      type: object
      description: Defines the provider that ran the article.
      properties:
        _type:
          type: string
          description: Type hint.
        name:
          type: string
          description: The name of the provider that ran the article.
    Video:
      type: object
      description: Defines a video that's related to the news article.
      properties:
        allowHttpsEmbed:
          type: boolean
          description: A Boolean value that determines whether you may embed the video on pages that use the HTTPS protocol.
        embedHtml:
          type: string
          description: An iFrame that lets you embed and run the video in your webpage.
        motionThumbnailUrl:
          type: string
          description: A URL to an animated thumbnail that shows a preview of the video.
        name:
          type: string
          description: The name of the video.
        thumbnail:
          $ref: '#/components/schemas/MediaSize'
          description: The width and height of the thumbnail image or motion thumbnail.
        thumbnailUrl:
          type: string
          description: A URL to a thumbnail image of the video.
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: Ocp-Apim-Subscription-Key
      description: The subscription key received when signing up for the Bing News Search service in the Azure Portal.
externalDocs:
  description: Bing News Search API Documentation
  url: https://learn.microsoft.com/en-us/previous-versions/bing/search-apis/bing-news-search/overview