Image 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 /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.
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.
|
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.
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.
|
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[] |