Bing Image Search API v7 upgrade guide

  • Article

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 Image 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**/images/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 possible
    • moreDetails—Additional information about the error described in the message field

  • Replaced the v5 error codes with the following possible code and subCode 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

Query parameters

  • Renamed the modulesRequested query parameter to modules.

  • Renamed the Annotations to Tags. See modules query parameter to Tags.

  • Changed the list of supported markets of the ShoppingSources filter value to en-US only. See imageType.

Image insights changes

  • Renamed the annotations field of ImagesInsights to imageTags.

  • Renamed the AnnotationModule object to ImageTagsModule.

  • Renamed the Annotation object to Tag, and removed the confidence field.

  • Renamed the insightsSourcesSummary field of the Image object to insightsMetadata.

  • Renamed the InsightsSourcesSummary object to InsightsMetadata.

  • Added the https://api.cognitive.microsoft.com/bing/v7.0/images/details endpoint. Use this endpoint to request image insights instead of the /images/search endpoint. See Image Insights.

  • The following query parameters are now valid only with the /images/details endpoint.

  • Renamed the ImageInsightsResponse object to ImageInsights.

  • Changed the data types of the following fields in the ImageInsights object.

    • Changed the type of the relatedCollections field from ImageGallery[] to RelatedCollectionsModule.

    • Changed the type of the pagesIncluding field from Image[] to ImagesModule.

    • Changed the type of the relatedSearches field from Query[] to RelatedSearchesModule.

    • Changed the type of the recipes field from Recipe[] to RecipesModule.

    • Changed the type of the visuallySimilarImages field from Image[] to ImagesModule.

    • Changed the type of the visuallySimilarProducts field from ProductSummaryImage[] to ImagesModule.

    • Removed the ProductSummaryImage object and moved the product-related fields into the Image object. The Image object includes the product-related fields only when the image is included as part of visually similar products in an image insight response.

    • Changed the type of the recognizedEntityGroups field from RecognizedEntityGroup[] to RecognizedEntitiesModule.

  • Renamed the categoryClassification field of ImageInsights to annotations, and changed its type to AnnotationsModule.

Images answer

  • Removed the displayShoppingSourcesBadges and displayRecipeSourcesBadges fields from Images.

  • Renamed the nextOffsetAddCount field of Images to nextOffset. The way you use the offset has also changed. Previously, you set the offset query parameter to the nextOffsetAddCount value plus the previous offset value plus the number of images in the result. Now, you set offset to the nextOffset value.

Non-breaking changes

Query parameters

  • Added Transparent as a possible imageType filter value. The Transparent filter returns only images with a transparent background.

  • Added the Any as a possible license filter value. The Any filter returns only images that are under license.

  • Added the maxFileSize and minFileSize query parameters. Use these filters to return images within a range of file sizes.

  • Added the maxHeight, minHeight, maxWidth, minWidth query parameters. Use these filters to return images within a range of heights and widths.

Object changes

  • Added the description and lastUpdated fields to the Offer object.

  • Added the name field to the ImageGallery object.

  • Added similarTerms to the Images object. This field contains a list of terms that are similar in meaning to the user's query string.