Edit

Share via

Image Search APIs v7 response objects

  • Article

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 /images/search, the top-level object in the response is the ImageAnswer object; and for /images/trending, it's TrendingImages. 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.

AggregateOffer

Defines a list of offers from merchants that are related to the image.

Element Description Type
offers A list of offers from merchants that have offerings related to the image. Offer[]

AggregateRating

Defines the metrics that indicate how well an item was rated by others.

Name Value Type
bestRating The highest rated review. The possible values are 1.0 through 5.0. float
ratingValue The mean (average) rating. The possible values are 1.0 through 5.0. float
reviewCount The number of times the recipe has been rated or reviewed. Unsigned Integer
text The mean (average) rating, in string form. String

Category

Defines the category of trending images.

Name Value Type
tiles A list of images that are trending in the category. Each tile contains an image and a URL that returns more images of the subject. For example, if the category is Popular People Searches, the image is of a popular person and the URL would return more images of that person. Tile[]
title The name of the image category. For example, Popular People Searches. String

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 an image that is relevant to the query.

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. The exception is those parameters and values discussed by Resize and crop thumbnail images.

Name Value Type
accentColor A three-byte hexadecimal number that represents the color that dominates the image. Use the color as the temporary background in your client until the image is loaded. String
contentSize The image's file size. The format of the string is {size} {units}. For example, 12345 B indicates that the size of the image is 12,345 bytes. String
contentUrl A URL to the image on the source website. String
creativeCommons The Creative Commons license under which you may use the image. Please read and apply the license accordingly. The following are the possible license values.To filter images by license type, see the license query parameter. String
datePublished The date and time, in UTC, that Bing discovered the image. The date is in the format, YYYY-MM-DDTHH:MM:SS. String
encodingFormat The image's mime type (for example, jpeg). String
height The height of the source image, in pixels. Unsigned Short
hostPageDisplayUrl The display URL of the webpage that hosts the image.

Use this URL in your user interface to identify the host webpage that contains the image. The URL is not a well-formed and should not be used to access the host webpage. To access the host webpage, use the hostPageUrl URL.		 String
hostPageDomainFriendlyName The friendly name of the domain that hosts the image. You should display the name over the image. Use the URL in hostPageUrl to make the name clickable. For example, Bing.com displays the clickable host name over the image when the user hovers over the image with the mouse. String
hostPageUrl The URL of the webpage that includes the image. This URL and contentUrl may be the same URL. String
id An ID that uniquely identifies this image in the list of images.

The object includes this field only in a Web Search API response. For information about how to use this field, see Ranking results in the Web Search API guide.		 String
imageId An ID that uniquely identifies this image. If you want the image to be the first image in the response, set the id query parameter to this ID in your request. String
imageInsightsToken The token that you use when calling the Visual Search API to get insights about the image. String
insightsMetadata A count of the number of websites where you can shop or perform other actions related to the image.

For example, if the image is of an apple pie, this object includes a count of the number of websites where you can buy an apple pie. To indicate the number of offers in your UX, include badging such as a shopping cart icon that contains the count. When the user clicks on the icon, use the imageInisghtsToken in a Visual Search API request to get the list of websites.		 InsightsMetadata
name A title of the image. String
thumbnail The width and height of the thumbnail image (see thumbnailUrl). MediaSize
thumbnailUrl A URL to a thumbnail of the image. For information about resizing the image, see Resize and crop thumbnail images. String
webSearchUrl A URL to the Bing search results for this image. String
width The width of the source image, in pixels. Unsigned Short

ImageAnswer

The top-level object that the response includes when an image request succeeds.

Name Value Type
_type A type hint, which is set to Images. String
currentOffset The offset that represents where the first image in value is relative to all images that Bing might return for this query. Also see nextOffset.
id An ID that uniquely identifies the image 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
isFamilyFriendly A Boolean value that determines whether one or more of the images contain adult content. If one or more of the images contain adult content, isFamilyFriendly is set to false; otherwise, true.

If false, the thumbnail images are pixelated (fuzzy).

NOTE: This field is included only in a Web Search API response.		 Boolean
nextOffset The offset that you set the offset query parameter to.

If you set offset to 0 and count to 30 in your first request, and then set offset to 30 in your second request, some of the results in the second response may be duplicates of the first response. To prevent duplicates, set offset to the value of nextOffset.

Only the Image Search API includes this field.		 Integer
pivotSuggestions A list of segments in the original query. For example, if the query was Red Flowers, Bing might segment the query into Red and Flowers.

The Flowers pivot may contain query suggestions such as Red Peonies and Red Daisies, and the Red pivot may contain query suggestions such as Green Flowers and Yellow Flowers.

Only the Image Search API includes this field.		 Pivot
queryExpansions A list of expanded queries that narrows the original query. For example, if the query was Microsoft Surface, the expanded queries might be: Microsoft Surface Pro 3, Microsoft Surface RT, Microsoft Surface Phone, and Microsoft Surface Hub.

Only the Image Search API includes this field.		 Query
queryContext The query string that Bing used for the request. QueryContext
readLink A partial URL that you'd use to request images from Image Search API using the search query string used for this response. The URL is not well formed; you need to prefix the URL with https://api.bing.microsoft.com/v7.0 to create a well-formed URL. Include other query parameters as needed. String
relatedSearches A list of related search queries made by others. Query[]
similarTerms A list of terms that are similar in meaning to the user's query term. Query
totalEstimatedMatches The estimated number of images that are relevant to the query. Use this number along with the count and offset query parameters to page the results.

Only the Image Search API includes this field.		 Long
value A list of images that are relevant to the query. If there are no results, the array is empty. Image[]
webSearchUrl A URL to the Bing search results for the requested images. String

ImageCaption

Defines an image's caption.

Name Value Type
caption A caption about the image. String
dataSourceUrl The URL to the website where the caption was found. You must attribute the caption to the source. For example, by displaying the domain name from the URL next to the caption and using the URL to link to the source website. String
relatedSearches A list of entities found in the caption. Use the contents of the Query object to find the entity in the caption and create a link. The link takes the user to images of the entity. Query

ImageGallery

Defines a link to a webpage that contains a collection of related images.

Name Value Type
creator The person that owns the collection. You must attribute the collection to the creator. Person
description A description of the collection. The description may be empty. String
followersCount The number of users on the social network that follow the creator. Unsigned Integer
imagesCount The number of related images found in the collection. Unsigned Integer
name The name of the gallery. String
source The publisher or social network where the images were found. You must attribute the publisher as the source where the collection was found. String
thumbnailUrl The URL to a thumbnail of one of the images found in the collection. String
url The URL to the webpage that contains the collection of related images. String

ImagesModule

Defines a list of images.

Element Description Type
value A list of images. Image[]

ImageTagsModule

Defines the characteristics of content found in an image.

Element Description Type
value A list of tags that describe the characteristics of the content found in the image. For example, if the image is of a musical artist, the list might include Female, Dress, and Music to indicate the person is female music artist that's wearing a dress. Tag[]

InsightsMetadata

Defines a count of the number of websites where you can shop or perform other actions related to the image.

Name Value Type
aggregateOffer A summary of the online offers of products found in the image. For example, if the image is of a dress, the offer might identify the lowest price and the number of offers found.

Only visually similar products insights include this field.

The offer includes the following fields: Name, AggregateRating, OfferCount, and LowPrice.		 Offer
availableSizesCount The number of different sizes of the image that Bing found on one or more websites. Unsigned Integer
pagesIncludingCount The number of webpages that include the image. Unsigned Integer
recipeSourcesCount The number of websites that offer recipes of the food seen in the image. Unsigned Integer
shoppingSourcesCount The number of websites that offer the products seen in the image. Unsigned Integer

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

NormalizedRectangle

Defines a region of an image. The region is defined by the coordinates of the top, left corner and bottom, right corner of the region. The coordinates are fractional values of the original image's width and height in the range 0.0 through 1.0.

Name Value Type
bottom The bottom coordinate. Float
left The left coordinate. Float
right The right coordinate Float
top The top coordinate Float

Offer

Defines a merchant's offer.

The ShoppingSources insights and SimilarProducts insights both use this object. To determine the insight that the field applies to, see the field's description.

Element Description Type
aggregateRating An aggregated rating that indicates how well the product has been rated by others.

Used by SimilarProducts.		 AggregateRating
availability The item's availability. The following are the possible values.
  • Discontinued
  • InStock
  • InStoreOnly
  • LimitedAvailability
  • OnlineOnly
  • OutOfStock
  • PreOrder
  • SoldOut

Used by ShoppingSources.		 String
description A description of the item. String
lastUpdated The last date that the offer was updated. The date is in the form YYYY-MM-DD. Sting
lowPrice The lowest price of the item that Bing found online.

Used by SimilarProducts.		 Float
name The name of the product. String
offerCount The number of offers that Bing found online.

Used by SimilarProducts.		 Unsigned Integer
price The item's price.

Used by ShoppingSources.		 Float
priceCurrency The monetary currency. For example, USD. String
seller The merchant's name.

Used by ShoppingSources.		 Organization
url The URL to the offer on the merchant's website.

Used by ShoppingSources.		 String

Organization

Defines information about a merchant.

Element Description Type
image The merchant's logo. The Image object includes only the url field. Image
name The merchant's name. String

Person

Defines a person.

Name Value Type
_type Type hint. String
description A short description of the person. String
image An image of the person. Image
jobTitle The person's job title. String
name The person's name. String
twitterProfile The URL of the person's twitter profile. String
url The URL to the person's social network home page, if applicable. String
webSearchUrl The URL to the Bing search results page that contains information about this person. String

Pivot

Defines the pivot segment.

Name Value Type
pivot The segment from the original query to pivot on. String
suggestions A list of suggested query strings for the pivot. Query

Query

Defines a search query.

Name Value Type
displayText The display version of the search query string. String
searchLink The Image Search API URL that you use to get image search results. The URL includes the q query parameter that's set the search string in text. Before using the URL, append other query parameters as appropriate.

Use this URL if you're displaying the results in your own user interface. Otherwise, use the URL in webSearchUrl.		 String
text The query string. Use this string as the query term in a new search request. String
thumbnail A URL to a thumbnail image that represents the search string. Thumbnail
webSearchUrl The URL that takes the user to the Bing search results page for the query. String

QueryContext

Defines the query string that Bing used for the request.

Name Value Type
adultIntent A Boolean value that indicates whether the specified query has adult intent. The value is true if the query has adult intent.

If true, and the request's safeSearch query parameter is set to Strict, the response contains only news results, if applicable.		 Boolean
alterationOverrideQuery The query string to use to force Bing to use the original string. For example, if the query string is sailing downwind, the override query string is +sailing downwind. Remember to encode the query string, which results in %2Bsailing+downwind.

The object includes this field only if the original query string contains a spelling mistake.		 String
alteredQuery The query string that Bing used to perform the query. Bing uses the altered query string if the original query string contained spelling mistakes. For example, if the query string is sailing downwind, the altered query string is sailing downwind.

The object includes this field only if the original query string contains a spelling mistake.		 String
askUserForLocation A Boolean value that indicates whether Bing requires the user's location to provide accurate results. If you specified the user's location by using the X-MSEdge-ClientIP and X-Search-Location headers, you can ignore this field.

For location aware queries, such as "today's weather" or "restaurants near me" that need the user's location to provide accurate results, this field is set to true.

For location aware queries that include the location (for example, "Seattle weather"), this field is set to false. This field is also set to false for queries that are not location aware, such as "best sellers."		 Boolean
originalQuery The query string as specified in the request. String

Recipe

Defines a cooking recipe.

Element Description Type
aggregateRating Aggregated ratings that indicate how well the recipe has been rated by others. AggregateRating
cookTime The amount of time the food takes to cook. For example, PT25M. For information about the time format, see https://en.wikipedia.org/wiki/ISO_8601#Durations. String
creator The recipe's author. Person
name The name of the recipe. String
prepTime The amount of time required to prepare the ingredients. For example, PT15M. For information about the time format, see https://en.wikipedia.org/wiki/ISO_8601#Durations. String
thumbnailUrl The URL to a thumbnail image of the prepared food. String
totalTime The total amount of time it takes to prepare and cook the recipe. For example, PT45M. For information about the time format, see https://en.wikipedia.org/wiki/ISO_8601#Durations. String
url The URL that takes the user to the webpage that contains the recipe. String

RecipesModule

Defines a list of recipes.

Element Description Type
value A list of recipes. Recipe[]

RecognizedEntitiesModule

Defines a list of previously recognized entities.

Element Description Type
value A list of recognized entities. RecognizedEnityGroup[]

RecognizedEntity

Defines a recognized entity.

Element Description Type
entity The entity that was recognized.

The following are the possible entity objects.		 Object
matchConfidence The confidence that Bing has that the entity in the image matches this entity. The confidence ranges from 0.0 through 1.0 with 1.0 being very confident. Float

RecognizedEntityGroup

Defines a group of previously recognized entities.

Element Description Type
name The name of the group where images of the entity were also found.

The following are possible groups.
  • CelebRecognitionAnnotations — Similar to CelebrityAnnotations but provides a higher probability of an accurate match.
  • CelebrityAnnotations — Contains celebrities such as actors, politicians, athletes, and historical figures.
 String
recognizedEntityRegions The regions of the image that contain entities. RecognizedEntityRegion[]

RecognizedEntityRegion

Defines a region of the image where an entity was found and a list of entities that might match it.

Element Description Type
matchingEntities A list of entities that Bing believes match the entity found in the region. The entities are in descending order of confidence (see the matchConfidence field of RecognizedEntity). RecognizedEntity[]
region A region of the image that contains an entity.

The values of the rectangle are relative to the width and height of the original image and are in the range 0.0 through 1.0.

For example, if the image is 300x200 and the region's top, left corner is at point (10, 20) and the bottom, right corner is at point (290, 150), then the normalized rectangle is:

Left = 0.0333333333333333
Top = 0.1
Right = 0.9666666666666667
Bottom = 0.75

For people, the region represents the person's face.		 NormalizedRectangle

RelatedCollectionsModule

Defines a list of webpages that contain related images.

Element Description Type
value A list of webpages that contain related images. ImageGallery[]

RelatedSearchesModule

Defines a list of related searches made by others.

Element Description Type
value A list of related searches made by others. Query[]

Tag

Defines a characteristic of the content found in the image.

Element Description Type
name The name of the characteristic. For example, cat, kitty, calico cat. String

Thumbnail

Defines the URL to a thumbnail of an image.

Name Value Type
url The URL to a thumbnail of an image. String

Tile

Defines a video tile.

Name Value Type
image A URL to the image's thumbnail. Image
query A query that returns a Bing search results page with images of the subject. For example, the thumbnail is of a popular person if the category is Popular People Searches. The query would return a Bing search results page with more images of that person. Query

TrendingImages

The top-level object that the response includes when a trending images request succeeds.

Name Value Type
categories A list that identifies categories of images and a list of trending images in those categories. Category[]