openapi: 3.0.3 info: title: Bing API v7 News Category News Search 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 Search description: Search for news articles by keyword query paths: /news/search: get: operationId: NewsSearch summary: Search News Articles description: Returns news articles relevant to a user's search query. Supports filtering by freshness, market, safe search level, and category. Results include article titles, descriptions, URLs, publication times, image thumbnails, and publisher metadata. If the search query is empty, the call returns the top news articles. tags: - News Search parameters: - $ref: '#/components/parameters/OcpApimSubscriptionKey' - name: q in: query required: true description: The user's search query term. If the term is empty (e.g., q=), the response includes the top news stories. The term may contain Bing Advanced Operators. schema: type: string - $ref: '#/components/parameters/count' - $ref: '#/components/parameters/offset' - $ref: '#/components/parameters/mkt' - $ref: '#/components/parameters/cc' - $ref: '#/components/parameters/setLang' - $ref: '#/components/parameters/safeSearch' - name: freshness in: query required: false description: Filter news articles by age. Use this parameter only when calling the /news/search endpoint. schema: type: string enum: - Day - Week - Month - name: originalImg in: query required: false description: If true, the Image object includes the contentUrl field pointing to the original image on the publisher's website. Otherwise, only the thumbnail field is included. Use this parameter only with /news/search. schema: type: boolean default: false - $ref: '#/components/parameters/textDecorations' - $ref: '#/components/parameters/textFormat' requestBody: null responses: '200': description: Successful news search 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 - invalid query parameters content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Unauthorized - invalid or missing subscription key content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: Forbidden - quota exceeded or access denied content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '429': description: Too Many Requests - rate limit exceeded 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 -. 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 offset: name: offset in: query required: false description: The zero-based offset that indicates the number of news articles to skip before returning results. The default is 0. Use this parameter only when calling the /news/search endpoint. schema: type: integer minimum: 0 default: 0 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 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 -. For example, en-US. This parameter and the cc query parameter are mutually exclusive. schema: type: string example: en-US 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 count: name: count in: query required: false description: The number of news articles to return in the response. The actual number delivered may be less than requested. The default is 10 and the maximum is 100. Use this parameter only when calling the /news/search endpoint. schema: type: integer minimum: 1 maximum: 100 default: 10 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