News Search API upgrade guide
Warning
On October 30, 2020, the Bing Search APIs moved from Azure AI services to Bing Search Services. This documentation is provided for reference only. For updated documentation, see the Bing search API documentation. For instructions on creating new Azure resources for Bing search, see Create a Bing Search resource through the Azure Marketplace.
This upgrade guide identifies the changes between version 5 and version 7 of the Bing News Search API. Use this guide to help you identify the parts of your application that you need to update to use version 7.
Breaking changes
Endpoints
- The endpoint's version number changed from v5 to v7. For example,
https://api.cognitive.microsoft.com/bing/v7.0/news/search
.
Error response objects and error codes
All failed requests should now include an
ErrorResponse
object in the response body.Added the following fields to the
Error
object.subCode
—Partitions the error code into discrete buckets, if possiblemoreDetails
—Additional information about the error described in themessage
field
Replaced the v5 error codes with the following possible
code
andsubCode
values.
Code | SubCode | Description |
---|---|---|
ServerError | UnexpectedError ResourceError NotImplemented |
Bing returns ServerError whenever any of the sub-code conditions occur. The response includes these errors if the HTTP status code is 500. |
InvalidRequest | ParameterMissing ParameterInvalidValue HttpNotAllowed Blocked |
Bing returns InvalidRequest whenever any part of the request is not valid. For example, a required parameter is missing or a parameter value is not valid. If the error is ParameterMissing or ParameterInvalidValue, the HTTP status code is 400. If the error is HttpNotAllowed, the HTTP status code 410. |
RateLimitExceeded | Bing returns RateLimitExceeded whenever you exceed your queries per second (QPS) or queries per month (QPM) quota. Bing returns HTTP status code 429 if you exceeded QPS and 403 if you exceeded QPM. |
|
InvalidAuthorization | AuthorizationMissing AuthorizationRedundancy |
Bing returns InvalidAuthorization when Bing cannot authenticate the caller. For example, the Ocp-Apim-Subscription-Key header is missing or the subscription key is not valid.Redundancy occurs if you specify more than one authentication method. If the error is InvalidAuthorization, the HTTP status code is 401. |
InsufficientAuthorization | AuthorizationDisabled AuthorizationExpired |
Bing returns InsufficientAuthorization when the caller does not have permissions to access the resource. This can occur if the subscription key has been disabled or has expired. If the error is InsufficientAuthorization, the HTTP status code is 403. |
- The following maps the previous error codes to the new codes. If you've taken a dependency on v5 error codes, update your code accordingly.
Version 5 code | Version 7 code.subCode |
---|---|
RequestParameterMissing | InvalidRequest.ParameterMissing |
RequestParameterInvalidValue | InvalidRequest.ParameterInvalidValue |
ResourceAccessDenied | InsufficientAuthorization |
ExceededVolume | RateLimitExceeded |
ExceededQpsLimit | RateLimitExceeded |
Disabled | InsufficientAuthorization.AuthorizationDisabled |
UnexpectedError | ServerError.UnexpectedError |
DataSourceErrors | ServerError.ResourceError |
AuthorizationMissing | InvalidAuthorization.AuthorizationMissing |
HttpNotAllowed | InvalidRequest.HttpNotAllowed |
UserAgentMissing | InvalidRequest.ParameterMissing |
NotImplemented | ServerError.NotImplemented |
InvalidAuthorization | InvalidAuthorization |
InvalidAuthorizationMethod | InvalidAuthorization |
MultipleAuthorizationMethod | InvalidAuthorization.AuthorizationRedundancy |
ExpiredAuthorizationToken | InsufficientAuthorization.AuthorizationExpired |
InsufficientScope | InsufficientAuthorization |
Blocked | InvalidRequest.Blocked |
Object changes
- Added the
contractualRules
field to the NewsArticle object. ThecontractualRules
field contains a list of rules that you must follow (for example, article attribution). You must apply the attribution provided incontractualRules
instead of usingprovider
. The article includescontractualRules
only when the Web Search API response contains a News answer.
Non-breaking Changes
Query parameters
Added Products as a possible value that you may set the category query parameter to. See Categories By Markets.
Added the SortBy query parameter, which returns trending topics sorted by date with the most recent first.
Added the Since query parameter, which returns trending topics that were discovered by Bing on or after the specified Unix epoch timestamp.
Object changes
Added the
mentions
field to the NewsArticle object. Thementions
field contains a list of entities (persons or places) that were found in the article.Added the
video
field to the NewsArticle object. Thevideo
field contains a video that's related to the news article. The video is either an <iframe> that you can embed or a motion thumbnail.Added the
sort
field to the News object. Thesort
field shows the sort order of the articles. For example, the articles are sorted by relevance (default) or date.Added the SortValue object, which defines a sort order. The
isSelected
field indicates whether the response used the sort order. If true, the response used the sort order. IfisSelected
is false, you can use the URL in theurl
field to request a different sort order.