News Search APIs v7 response objects
For a list of possible objects, see In this article in the right pane.
The top-level object in the response depends on the endpoint you call. If you call /news/search or /news, the top-level object in the response is the NewsAnswer object; and for /news/trendingtopics, it's TrendingTopicAnswer. If the request fails, the top-level object is the ErrorResponse object.
Note
Because URL formats and parameters are subject to change without notice, use all URLs as-is. You should not take dependencies on the URL format or parameters except where noted.
Error
Defines the error that occurred.
| Name | Value | Type |
|---|---|---|
| code | The error code that identifies the category of error. For a list of possible codes, see Error codes. | String |
| message | A description of the error. | String |
| moreDetails | A description that provides additional information about the error. | String |
| parameter | The query parameter in the request that caused the error. | String |
| subCode | The error code that identifies the error. For example, if code is InvalidRequest, subCode may be ParameterInvalid or ParameterInvalidValue. |
String |
| value | The query parameter's value that was not valid. | String |
ErrorResponse
The top-level object that the response includes when the request fails.
| Name | Value | Type |
|---|---|---|
| _type | Type hint, which is set to ErrorResponse. | String |
| errors | A list of errors that describe the reasons why the request failed. | Error[] |
Image
Defines a thumbnail image.
Note
Because URL formats and parameters are subject to change without notice, all image URLs should be used as-is; you should not take dependencies on the URL format or parameters. The exception is those parameters and values discussed by Resize and crop thumbnail images.
| Name | Value | Type |
|---|---|---|
| provider | A list of owners of the image. | Organization |
| thumbnail | A link to a thumbnail of the image. | Thumbnail |
| url | A URL to the image. | String |
MediaSize
Defines the size of the media content.
| Name | Value | Type |
|---|---|---|
| height | The height of the media content, in pixels. | Integer |
| width | The width of the media content, in pixels. | Integer |
NewsAnswer
Defines the top-level object that the response includes when the news request succeeds.
If the service suspects a denial of service attack, the request succeeds (HTTP status code is 200 OK), but the body of the response is empty.
| Name | Value | Type |
|---|---|---|
| _type | Type hint. | String |
| id | An ID that uniquely identifies the news answer. Only Web Search API responses include this field. For information about how to use this field, see Ranking results in the Web Search API guide. | String |
| readLink | A URL to request news from News Search API. Include other query parameters as needed. Only Web Search API responses include this field. | String |
| relatedTopics | A list of news articles that are related to the search term. Only the News Search API includes this field. |
RelatedTopic[] |
| sort | A list of options for sorting the news articles. For example, sort by relevance (default) or date. To determine which sort order the request used, see the isSelected field.Only the News Search API includes this field. |
SortValue[] |
| totalEstimatedMatches | The estimated number of news articles that are relevant to the query. Use this number along with the count and offset query parameters to page the results. Only the News Search API includes this field. |
Long |
| value | A list of news articles that are relevant to the query term. If there are no results to return for the request, the array is empty. |
NewsArticle[] |
| webSearchUrl | A URL to the top news stories on Bing. Included only for /news requests. |
String |
NewsArticle
Defines a news article.
| Name | Value | Type |
|---|---|---|
| about | For internal use only. | Object[] |
| category | 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. For a list of possible categories, see News Categories by Market. If your request specifies the Sports-Tennis category, the category property may contain Sports-Tennis or Sports. |
String |
| clusteredArticles | A list of related news articles. | NewsArticle[] |
| contractualRules | A list of rules that you must adhere to if you display the article. The following contractual rules may apply:If the article provides contractual rules, you must abide by them. NOTE: Only articles returned by Web Search API include contractual rules. Articles returned by the News endpoints do not include contractual rules. |
Object[] |
| datePublished | The date and time that Bing discovered the article. The date is in the format, YYYY-MM-DDTHH:MM:SS. | String |
| description | A short description of the news article. | String |
| headline | A Boolean value that indicates whether the news article is a headline. If true, the article is a headline. NOTE: The article includes this field only for news categories requests that do not specify the category query parameter. |
Boolean |
| id | An ID that uniquely identifies this article in the list of articles. For information about how to use this field, see Using Ranking to Display Results in the Web Search API guide. |
String |
| image | An image related to the new article. The Image object in this context contains only the thumbnail field. |
Image |
| mentions | A list of entities (places or persons) mentioned in the article. | Thing[] |
| name | The name of the article. Use this name along with the URL to create a hyperlink that when clicked takes the user to the news article. |
String |
| provider | A list of providers that ran the article. | Organization[] |
| url | A URL to the news article. Use this URL along with name to create a hyperlink that when clicked takes the user to the news article. |
String |
| video | A video that's related to the news article. | Video |
Organization
Defines the provider that ran the article.
| Name | Value | Type |
|---|---|---|
| _type | Type hint. | String |
| name | The name of the provider that ran the article. | String |
Query
Defines the search query string.
| Name | Value | Type |
|---|---|---|
| text | A query string that returns the trending topic. | String |
RelatedTopic
Defines a list of news articles that are related to the search query.
| Name | Value | Type |
|---|---|---|
| relatedNews | A list of related news articles. | NewsArticle |
| name | The query term that returned the related news articles. | String |
| webSearchUrl | A URL that takes the user to the Bing search results for the related query. | String |
SortValue
Defines a sort order to use for the request.
| Name | Value | Type |
|---|---|---|
| id | An identifier that identifies the articles sort order. The following are the possible values:
|
String |
| isSelected | A Boolean value that determines whether the response used this sort order. If true, the response used this sort order. | Boolean |
| name | The display name of the sort order. | String |
| url | A URL that you can use to make the same request using this sort order. | String |
TextAttribution
Defines a contractual rule for plain text attribution.
Thing
Defines an entity that the article mentions.
| Name | Value | Type |
|---|---|---|
| name | The name of the entity that the article mentions. | String |
Thumbnail
Defines a link to the related image.
| Name | Value | Type |
|---|---|---|
| contentUrl | The URL to the image. | String |
| height | The height of the image in pixels. | Unsigned Short |
| width | The width of the image in pixels. | Unsigned Short |
Topic
Defines a trending news topic.
| Name | Value | Type |
|---|---|---|
| image | A link to a related image. The Image object in this context contains only the url and provider fields. The provider field is an array of Organization objects that identify the image providers. |
Image |
| isBreakingNews | A Boolean value that indicates whether the topic is considered breaking news. If the topic is considered breaking news, the value is true. | Boolean |
| name | The title of the trending topic. | String |
| newsSearchUrl | A URL to the Bing News search results for the search query term (see the query field). |
String |
| query | A search query term that returns this trending topic. | Query |
| webSearchUrl | A URL to the Bing search results for the search query term (see the query field). |
String |
TrendingTopics
Defines the top-level object that the response includes when the trending topics request succeeds.
| Name | Value | Type |
|---|---|---|
| value | A list of trending news topics on Bing. If there are no results to return for the request, the array is empty. |
Topic[] |
Video
Defines a video that's related to the news article.
Note
Because the URL format and parameters are subject to change without notice, use all URLs as-is. You should not take dependencies on the URL format or parameters.
| Name | Value | Type |
|---|---|---|
| allowHttpsEmbed | A Boolean value that determines whether you may embed the video (see the embedHtml field) on pages that use the HTTPS protocol. |
Boolean |
| embedHtml | An iFrame that lets you embed and run the video in your webpage. | String |
| motionThumbnailUrl | A URL to an animated thumbnail that shows a preview of the video. Typically, you use this URL to play a preview of the video when the user mouses over the thumbnail of the video on your results page. | String |
| name | The name of the video. | String |
| thumbnail | The width and height of the thumbnail image or motion thumbnail. | MediaSize |
| thumbnailUrl | A URL to a thumbnail image of the video. For information about resizing the image, see Resize and crop thumbnail images. | String |
Feedback
Coming soon: Throughout 2024 we will be phasing out GitHub Issues as the feedback mechanism for content and replacing it with a new feedback system. For more information see: https://aka.ms/ContentUserFeedback.
Submit and view feedback for