Visual Search API v7 response objects
For a list of possible objects, see In this article in the right pane.
If the request succeeds, the top-level object in the response is the ImageKnowledge object. And if the request fails, the top-level object in the response 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.
| Name | Value | Type |
|---|---|---|
| aggregateRating | An aggregated rating that indicates how well the product has been rated by others. | AggregateRating |
| availability | The item's availability. The following are the possible values:
|
String |
| lastUpdated | The last date that the offer was updated. The date is in the form YYYY-MM-DD. | String |
| offers | A list of offers from merchants that have offerings related to the image. | Offer |
| price | The item's price. | Double |
| priceCurrency | The three-letter ISO 4217 currency code that price is specified in. For example, USD. |
String |
| seller | The seller for this offer. | Organization |
AggregateRating
Defines metrics that indicate how well an item was rated by others.
| Name | Value | Type |
|---|---|---|
| _type | A type hint, which is set to Properties/Item | String |
| bestRating | The highest rated review. The possible values are 1.0 through 5.0. | Double |
| ratingValue | The mean (average) rating. The possible values are 1.0 through 5.0. | Double |
| reviewCount | The number of times the item was rated or reviewed. | Integer |
| text | Text representation of an item. | String |
Entity
Defines an entity such as a person, place, or thing.
| Name | Value | Type |
|---|---|---|
| bingId | An ID that uniquely identifies this entity. | String |
| contractualRules | A list of rules that you must adhere to if you display the entity. For example, the rules may govern attribution of the entity's description. The following contractual rules may apply:Not all entities include rules. If the entity provides contractual rules, you must abide by them. For more information about using contractual rules, see Attributing Data. |
Object[] |
| description | A short description of the entity. | String |
| image | An image of the entity. | Image |
| name | The entity's name. | String |
| webSearchUrl | The URL that takes the user to the Bing search results page for this entity. | 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.
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 |
|---|---|---|
| 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 |
| 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 |
| 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. | 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 imageInsightsToken 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 |
ImageEntityAction
Defines an entity action.
| Name | Value | Type |
|---|---|---|
| _type | A type hint, which is set to ImageEntityAction. | String |
| actionType | A string representing the type of action. Set to Entity. | String |
| data | The entity that Bing recognized in the image. | Entity |
| datePublished | The date on which the CreativeWork was published. | String |
| displayName | The name of the entity. | String |
| isTopAction | A Boolean representing whether this result is the top action. | Boolean |
| provider | The source of the creative work. | Thing[] |
| result | The result produced in the action. | Thing[] |
| serviceUrl | Use this URL to get additional data to determine how to take the appropriate action. For example, the serviceUrl might return JSON along with an image URL. |
String |
| text | Text content of this creative work. | String |
| thumbnailUrl | A URL to a thumbnail of the item. | String |
ImageKnowledge
Defines the top-level object in the API response.
| Name | Value | Type |
|---|---|---|
| _type | A type hint, which is set to ImageKnowledge | String |
| id | A String identifier. | String |
| image | The image used in this insights request. The object includes the imageInsightsToken field only. |
Image |
| tags | A list of visual search tags. | ImageTag[] |
ImageModuleAction
Defines an image list action.
| Name | Value | Type |
|---|---|---|
| _type | A type hint, which is set to ImageModuleAction. | String |
| actionType | A string representing the type of action. | String |
| data | A list of images. | ImagesModule |
| datePublished | The date on which the CreativeWork was published. | String |
| displayName | A display name for the action. | String |
| isTopAction | A Boolean representing whether this result is the top action. | Boolean |
| provider | The source of the creative work. | Thing[] |
| result | The result produced in the action. | Thing[] |
| serviceUrl | Use this URL to get additional data to determine how to take the appropriate action. For example, the serviceUrl might return JSON along with an image URL. |
String |
| text | Text content of this creative work. | String |
| thumbnailUrl | A URL to a thumbnail of the item. | String |
| url | The URI used to perform the action. The object includes this field if actionType is Uri, which is typically returned as part of text recognition. The URI can use the:
|
String |
ImageRelatedSearchesAction
Defines a related search action.
| Name | Value | Type |
|---|---|---|
| _type | A type hint, which is set to ImageRelatedSearchesAction. | String |
| actionType | A string representing the type of action. | String |
| data | A list of searches that are related to the image. | RelatedSearchesModule |
| datePublished | The date on which the CreativeWork was published. | String |
| displayName | A display name for the action. | String |
| isTopAction | A Boolean representing whether this result is the top action. | Boolean |
| provider | The source of the creative work. | Thing[] |
| result | The result produced in the action. | Thing[] |
| serviceUrl | Use this URL to get additional data to determine how to take the appropriate action. For example, the serviceUrl might return JSON along with an image URL. |
String |
| text | Text content of this creative work. | String |
| thumbnailUrl | A URL to a thumbnail of the item. | String |
ImageShoppingSourcesAction
Defines a shopping sources action.
| Name | Value | Type |
|---|---|---|
| _type | A type hint, which is set to ImageShoppingSourcesAction. | String |
| actionType | A string representing the type of action. | String |
| data | A list of merchants that offer items seen in the image. | AggregateOffer |
| datePublished | The date on which the CreativeWork was published. | String |
| displayName | A display name for the action. | String |
| isTopAction | A Boolean representing whether this result is the top action. | Boolean |
| provider | The source of the creative work. | Thing[] |
| result | The result produced in the action. | Thing[] |
| serviceUrl | Use this URL to get additional data to determine how to take the appropriate action. For example, the serviceUrl might return JSON along with an image URL. |
String |
| text | Text content of this creative work. | String |
| thumbnailUrl | A URL to a thumbnail of the item. | String |
ImagesModule
Defines a list of images.
| Name | Value | Type |
|---|---|---|
| currentOffset | The offset that represents where the first image in value is relative to all images that Bing might return for this query. The object includes this field only for the VisualSearch and ProductVisualSearch action types. |
|
| nextOffset | The offset value that you set the offset field to in the KnowledgeRequest request object. For information about paging, see Paging VisualSearch and ProductVisualSearch action types. The object includes this field only for the VisualSearch and ProductVisualSearch action types. |
Integer |
| totalEstimatedMatches | The estimated number of images that match the query. Use this number along with count and offset to page the results. The object includes this field only for the VisualSearch and ProductVisualSearch action types. |
Long |
| value | List of images. | Image[] |
ImageTag
Defines an image tag.
| Name | Value | Type |
|---|---|---|
| actions | Actions within this tag. The following are the possible actions: | Object[] |
| alternateName | An alias for the item. | String |
| bingId | An ID that uniquely identifies this item. | String |
| boundingBox | The bounding box for this tag. The bounding box identifies the area of interest in the image. There is no bounding box for the default tag. | ImageTagRegion |
| description | A short description of the item. | String |
| displayName | The display name for this tag. The tag with the empty display name represents the default tag. The default tag contains all insights except for the entity insight. The entity insight is in another tag and its actionType is Entity. |
String |
| id | A string identifier. | String |
| image | An image of the item. The object includes the thumbnailUrl field only. |
Image |
| name | The name of the thing represented by this object. | String |
| readlink | The URL that returns this resource. To use the URL, append query parameters as appropriate and include the Ocp-Apim-Subscription-Key header. | String |
| sources | A list of sources used to recognize text in the image. For example, OCR (optical character recognition). | String[] |
| url | The URL to get more information about the thing represented by this object. | String |
| webSearchUrl | The URL to Bing's search result for this item. | String |
ImageTagRegion
Defines an image region relevant to the ImageTag.
| Name | Value | Type |
|---|---|---|
| displayRectangle | A recommended rectangle to show to the user. | NormalizedQuadrilateral |
| queryRectangle | A rectangle that outlines the area of interest for this tag. | NormalizedQuadrilateral |
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. The offer includes the following fields: name, aggregateRating, offerCount, and lowPrice. |
AggregateOffer |
| 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 |
ItemRegion
Defines a word within a line of text.
| Name | Value | Type |
|---|---|---|
| boundingBox | The bounding box of the word. | NormalizedQuadrilateral |
| text | The word within a line of text. | String |
License
Defines the license under which the text or photo may be used.
| Name | Value | Type |
|---|---|---|
| name | The name of the license. | String |
| url | A URL to a website where the user can get more information about the license. Use the name and URL to create a hyperlink. |
String |
LicenseAttribution
Defines a contractual rule for license attribution.
| Name | Value | Type |
|---|---|---|
| _type | A type hint, which is set to LicenseAttribution. | String |
| license | The license under which the content may be used. | License |
| licenseNotice | The license to display next to the targeted field. For example, "Text under CC-BY-SA license". Use the license's name and URL in the license field to create a hyperlink to the website that describes the details of the license. Then, replace the license name in the licenseNotice string (for example, CC-BY-SA) with the hyperlink you just created. |
String |
| mustBeCloseToContent | A Boolean value that determines whether the contents of the rule must be placed in close proximity to the field that the rule applies to. If true, the contents must be placed in close proximity. If false, or this field does not exist, the contents may be placed at the caller's discretion. | Boolean |
| targetPropertyName | The name of the field that the rule applies to. | String |
LinkAttribution
Defines a contractual rule for link attribution.
| Name | Value | Type |
|---|---|---|
| _type | A type hint, which is set to LinkAttribution. | String |
| mustBeCloseToContent | A Boolean value that determines whether the contents of the rule must be placed in close proximity to the field that the rule applies to. If true, the contents must be placed in close proximity. If false, or this field does not exist, the contents may be placed at the caller's discretion. | Boolean |
| targetPropertyName | The name of the field that the rule applies to. If a target is not specified, the attribution applies to the entity as a whole and should be displayed immediately following the entity presentation. If there are multiple text and link attribution rules that do not specify a target, you should concatenate them and display them using a "Data from: " label. For example, “Data from <provider name1> | <provider name2>". |
String |
| text | The attribution text. | String |
| url | The URL to the provider's website. Use text and URL to create of hyperlink. |
String |
MediaAttribution
Defines a contractual rule for media attribution.
| Name | Value | Type |
|---|---|---|
| _type | A type hint, which is set to MediaAttribution. | String |
| mustBeCloseToContent | A Boolean value that determines whether the contents of the rule must be placed in close proximity to the field that the rule applies to. If true, the contents must be placed in close proximity. If false, or this field does not exist, the contents may be placed at the caller's discretion. | Boolean |
| targetPropertyName | The name of the field that the rule applies to. | String |
| url | The URL that you use to create of hyperlink of the media content. For example, if the target is an image, you would use the URL to make the image clickable. | 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 |
NormalizedQuadrilateral
Defines a region of an image. The region is a convex quadrilateral defined by coordinates of its top left, top right, bottom left, and bottom right points. The coordinates are fractional values of the original image's width and height in the range 0.0 through 1.0.
| Name | Value | Type |
|---|---|---|
| _type | A type hint. | String |
| alternateName | An alias for the item. | String |
| bingId | An ID that uniquely identifies this item. | String |
| bottomLeft | The bottom left corner coordinate. | Point2D |
| bottomRight | The bottom right corner coordinate. | Point2D |
| description | A short description of the item. | String |
| id | A String identifier. | String |
| image | An image of the item. | Image |
| name | The name of the thing represented by this object. | String |
| readLink | The URL that returns this resource. To use the URL, append query parameters as appropriate and include the Ocp-Apim-Subscription-Key header. | String |
| topLeft | The top left corner coordinate. | Point2D |
| topRight | The top right corner coordinate. | Point2D |
| url | The URL to get more information about the thing represented by this object. | String |
| webSearchUrl | The URL to Bing's search result for this item. | String |
Offer
Defines a merchant's offer.
| Name | Value | Type |
|---|---|---|
| aggregateRating | An aggregated rating that indicates how well the product has been rated by others. | AggregateRating |
| alternateName | An alias for the item. | String |
| availability | The item's availability. The following are the possible values:
|
String |
| bingId | An ID that uniquely identifies this item. | String |
| description | A short description of the item. | String |
| id | A String identifier. | String |
| image | An image of the item. | Image |
| lastUpdated | The last date that the offer was updated. The date is in the form YYYY-MM-DD. | String |
| name | The name of the thing represented by this object. | String |
| price | The item's price. | Double |
| priceCurrency | The three-letter ISO 4217 currency code that price is specified in. For example, USD. |
String |
| readLink | The URL that returns this resource. To use the URL, append query parameters as appropriate and include the Ocp-Apim-Subscription-Key header. | String |
| seller | The seller for this offer. | Organization |
| url | The URL to get more information about the thing represented by this object. | String |
| webSearchUrl | The URL to Bing's search result for this item. | String |
Organization
Defines an organization.
| Name | Value | Type |
|---|---|---|
| _type | A type hint. | String |
| alternateName | An alias for the item. | String |
| bingId | An ID that uniquely identifies this item. | String |
| description | A short description of the item. | String |
| id | A String identifier. | String |
| image | An image of the item. | Image |
| name | The name of the thing represented by this object. | String |
| readLink | The URL that returns this resource. To use the URL, append query parameters as appropriate and include the Ocp-Apim-Subscription-Key header. | String |
| url | The URL to get more information about the thing represented by this object. | String |
| webSearchUrl | The URL to Bing's search result for this item. | String |
Point2D
Defines a 2-dimensional point with X and Y coordinates.
| Name | Value | Type |
|---|---|---|
| _type | A type hint. | String |
| alternateName | An alias for the item. | String |
| bingId | An ID that uniquely identifies this item. | String |
| description | A short description of the item. | String |
| id | A String identifier. | String |
| image | An image of the item. | Image |
| name | The name of the thing represented by this object. | String |
| readLink | The URL that returns this resource. To use the URL, append query parameters as appropriate and include the Ocp-Apim-Subscription-Key header. | String |
| url | The URL to get more information about the thing represented by this object. | String |
| webSearchUrl | The URL to Bing's search result for this item. | String |
| x | The point's x-coordinate. | Integer |
| y | The point's y-coordinate. | Integer |
Query
Defines a search query.
| Name | Value | Type |
|---|---|---|
| displayText | A display version of the query term. | String |
| searchUrl | The URL that you use to get the results of the related search. Before using the URL, append 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 | The URL to a thumbnail of a related image. The Image object includes only the url field. |
Image |
| webSearchUrl | The URL that takes the user to the Bing search results page for the query. | String |
RelatedSearchesModule
Defines a list of related searches.
| Name | Value | Type |
|---|---|---|
| value | A list of related searches. | Query[] |
TextAttribution
Defines a contractual rule for plain text attribution.
| Name | Value | Type |
|---|---|---|
| _type | A type hint, which is set to TextAttribution. | String |
| text | The attribution text. Text attribution applies to the entity as a whole and should be displayed immediately following the entity presentation. If there are multiple text or link attribution rules that do not specify a target, you should concatenate them and display them using a "Data from: " label. |
String |
TextRecognitionAction
Defines a text recognition action.
| Name | Value | Type |
|---|---|---|
| _type | A type hint, which is set to ImageKnowledge/TextRecognitionAction. | String |
| actionType | A string representing the type of action, which is set to TextRecognition. | String |
| data | The recognized text found in the image. | TextRegionsModule |
TextLine
Defines a line of text that was found in the image.
| Name | Value | Type |
|---|---|---|
| boundingBox | The bounding box within which the line of text was found. | NormalizedQuadrilateral |
| text | The line of text. | String |
| words | A list of words within the line of text. | ItemRegion[] |
TextRegion
Defines an area where text was found in the image.
| Name | Value | Type |
|---|---|---|
| boundingBox | The bounding box within which the lines of text was found. | NormalizedQuadrilateral |
| lines | A list of areas within the bounding box where lines of text was found. | TextLine[] |
TextRegionsModule
Defines the list of areas where text was found in the image.
| Name | Value | Type |
|---|---|---|
| boundingBox | The bounding box within which all text in the image was found. | NormalizedQuadrilateral |
| regions | A list of areas within the bounding box where text was found. | TextRegion[] |
Thing
Defines a thing.
| Name | Value | Type |
|---|---|---|
| alternateName | An alias for the item. | String |
| bingId | An ID that uniquely identifies this item. | String |
| description | A short description of the item. | String |
| id | A String identifier. | String |
| image | An image of the item. | Image |
| name | The name of the thing represented by this object. | String |
| readLink | The URL that returns this resource. To use the URL, append query parameters as appropriate and include the Ocp-Apim-Subscription-Key header. | String |
| url | The URL to get more information about the thing represented by this object. | String |
| webSearchUrl | The URL to Bing's search result for this item. | String |