Custom Web 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:
- SearchResponse for Custom Web Search
- Suggestions for Custom Autosuggest
- Images for Custom Image Search
- Videos for Custom Video Search
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.
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 |
| 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 |
| imageId | An ID that uniquely identifies this image. | String |
| 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 |
| nextOffset | The offset value 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. |
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. |
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. | Query |
| readLink | A URL that returns this answer. To use the URL, append query parameters as appropriate. This field is included only in a Web Search API response. Typically, you'd use the URL if you want to query the Image Search API directly. |
String |
| 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 |
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 |
MetaTag
Defines a webpage's metadata.
| Name | Value | Type |
|---|---|---|
| content | The metadata. | String |
| name | The name of the metadata. | String |
OpenGraphImage
Defines the location and dimensions of an image relevant to a webpage.
| Name | Value | Type |
|---|---|---|
| contentUrl | The image's location. | String |
| width | The width of the image. May be zero (0). | UInt32 |
| height | The height of the image. May be zero (0). | UInt32 |
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 |
Publisher
Defines a publisher or creator.
| Name | Value | Type |
|---|---|---|
| name | The name of the publisher or creator. | String |
Query
Defines a search query.
| Name | Value | Type |
|---|---|---|
| displayText | The display version of the query term. This version of the query term may contain special characters that highlight the search term found in the query string. The string contains the highlighting characters only if the request enabled hit highlighting (see the textDecorations query parameter). For details about hit highlighting, see Hit highlighting. | 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 object includes this field only for pivot suggestions and related searches. |
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 saling downwind, the override query string is +saling downwind. Remember to encode the query string, which results in %2Bsaling+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 saling 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 |
SearchAction
Defines a query search suggestion.
SuggestionGroup
Defines a group of suggestions of the same type.
| Name | Value | Type |
|---|---|---|
| name | The name of the group. The name identifies the type of suggestions that the group contains. For example, web search suggestions. The following are the possible group names:
|
String |
| searchSuggestions | A list of up to 8 suggestions. If there are no suggestions, the array is empty. You must display all suggestions in the order provided. The list is in order of decreasing relevance. The first suggestion is the most relevant and the last suggestion is the least relevant. The size of the list is subject to change. |
SearchAction[] |
Suggestions
The top-level object that the response includes when the request succeeds.
If the service suspects a denial of service attack, the request succeeds (HTTP status code is 200 OK). However, the body of the response is empty.
| Name | Value | Type |
|---|---|---|
| _type | The type hint, which is set to Suggestions. | String |
| suggestionGroups | A list of suggested query strings grouped by type. For example, web search suggestions. | SuggestionGroup[] |
SearchResponse
The response's top-level object for search requests that succeed.
If the service suspects a denial of service attack, the request succeeds (HTTP status code is 200 OK), but the body of the response is empty.
| Name | Value | Type |
|---|---|---|
| _type | Type hint, which is set to SearchResponse. | String |
| queryContext | The query string that Bing used for the request. | QueryContext |
| images | A list of images that are relevant to the search query. | ImageAnswer |
| videos | A list of videos that are relevant to the search query. | VideoAnswer |
| webPages | A list of webpages that are relevant to the search query. | WebAnswer |
Thing
Defines the main entity shown in the video.
| Name | Value | Type |
|---|---|---|
| name | The name of the main entity shown in the video. | String |
Thumbnail
Defines the URL to a thumbnail of an image.
| Name | Value | Type |
|---|---|---|
| url | The URL to a thumbnail of an image. | String |
Video
Defines a video 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.
| Name | Value | Type |
|---|---|---|
| allowHttpsEmbed | A Boolean value that determines whether you may embed the video in the embedHtml field on pages that use the HTTPS protocol. |
Boolean |
| allowMobileEmbed | A Boolean value that determines whether you may embed the video in the embedHtml field on a mobile device. If true, you may use the HTML on a mobile device. |
Boolean |
| creator | The name of the video's creator. Only Video Search API responses include this field. |
Publisher |
| contentUrl | The URL to the video on the host website. | String |
| datePublished | The date and time that Bing discovered the video. The date is in the format, YYYY-MM-DDTHH:MM:SS. | String |
| description | A short description of the video. | String |
| duration | The video's duration or length. For example, PT2M50S. For information about the format, see ISO 8601 Durations on Wikipedia. | String |
| embedHtml | An iFrame that lets you embed and run the video on your webpage. | String |
| encodingFormat | The video's mime type (for example, mp4). | String |
| height | The height of the video, in pixels. | Integer |
| hostPageDisplayUrl | The display URL of the webpage that hosts the video. Use this URL in your user interface to identify the host webpage that contains the video. The URL is not a well-formed and should not be used to access the host webpage. To access the host webpage, use the URL in hostPageUrl. |
String |
| hostPageUrl | The URL to the webpage that hosts the video. This URL and contentUrl URL may be the same URL. |
String |
| id | An ID that uniquely identifies this video in the list of videos. 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 |
| isAccessibleForFree | A Boolean value that indicates whether the video requires payment or a paid subscription to view. If true, the video is free to watch. Otherwise, if false, a payment or subscription is required. NOTE: If Bing is unable to determine whether payment is required, the object may not include this field. To ensure that Bing returns only free videos, set the pricing query parameter to Free. |
Boolean |
| isSuperfresh | A Boolean value that indicates whether the video was recently discovered by Bing. If true, the video was recently discovered. To get videos discovered within the last 24 hours or the last week, use the freshness query parameter. |
Boolean |
| mainEntity | The name of the main entity shown in the video. The object includes this field only when the scenario field in the VideoAnswer object is set to SingleDominantVideo. |
Thing |
| motionThumbnailUrl | The URL to an animated thumbnail that shows a preview of the video. Typically, you use this URL to play a preview of the video when the user mouses over the thumbnail image of the video on your results page. | String |
| name | The name of the video. | String |
| publisher | A list of the publishers that published the video. | Publisher |
| thumbnail | The width and height of the thumbnail image (see thumbnailUrl). |
MediaSize |
| thumbnailUrl | The URL to a thumbnail image of the video. For information about resizing the image, see Resize and crop thumbnail images. | String |
| videoId | An ID that uniquely identifies this video in the list of videos. | String |
| viewCount | The number of times that the video has been watched at the source site. | Integer |
| webSearchUrl | The URL that takes the user to the Bing video search results and plays the video. | String |
| width | The width of the video, in pixels. | Integer |
VideoAnswer
The top-level object that the response includes when the Video Search API request succeeds.
If the service suspects a denial of service attack, the request succeeds (HTTP status code is 200 OK), but the body of the response is empty.
| Name | Value | Type |
|---|---|---|
| _type | Type hint, which is set to Videos. | String |
| nextOffset | The offset value that you set the offset query parameter to. If you set offset to 0 and count to 30 on your first request, and then set offset to 30 on 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. |
Integer |
| pivotSuggestions | A list of pivots that segment the original query. For example, if the query was Cleaning Gutters, Bing might segment the query into Cleaning and Gutters. The Cleaning pivot may contain query suggestions such as Gutter Installation and Gutter Repair, and the Gutters pivot may contain query suggestions such as Roof Cleaning and Window Cleaning. |
Pivot[] |
| queryExpansions | A list of expanded queries that narrows the original query. For example, if the query was Cleaning+Gutters, the expanded queries might be: Gutter Cleaning Tools, Cleaning Gutters From the Ground, Gutter Cleaning Machine, and Easy Gutter Cleaning. | Query[] |
| totalEstimatedMatches | The estimated number of videos that match the query. Use this number along with the count and offset query parameters to page the results. Only Video Search API responses include this field. |
Long |
| value | The list of videos that are relevant to the user's query. | Video[] |
| webSearchUrl | The URL to the Bing search results for the requested videos. | String |
WebAnswer
Defines a list of relevant webpage links.
| Name | Value | Type |
|---|---|---|
| totalEstimatedMatches | The estimated number of webpages that are relevant to the query. Use this number along with the count and offset query parameters to page the results. | Long |
| value | A list of webpages that are relevant to the query. | WebPage[] |
| webSearchUrl | The URL to the Bing search results for the requested webpages. | String |
Webpage
Defines a webpage that is relevant to the query.
| Name | Value | Type |
|---|---|---|
| dateLastCrawled | The last time that Bing crawled the webpage. The date is in the form, YYYY-MM-DDTHH:MM:SS. For example, 2015-04-13T05:23:39. | String |
| deepLinks | A list of links to related content that Bing found in the website that contains this webpage. The Webpage object in this context includes only the name, url, urlPingSuffix, and snippet fields. |
Webpage[] |
| displayUrl | The display URL of the webpage. The URL is meant for display purposes only and is not well formed. | String |
| id | An ID that uniquely identifies this webpage in the list of web results. The object includes this field only if the Ranking answer specifies that you mix the webpages with the other search results. Each webpage contains an ID that matches an ID in the Ranking answer. For more information, see Ranking results. |
String |
| name | The name of the webpage. Use this name along with url to create a hyperlink that when clicked takes the user to the webpage. |
String |
| openGraphImage | A URL to the image that the webpage owner chose to represent the page content. Included only if available. | OpenGraphImage |
| searchTags | A list of search tags that the webpage owner specified on the webpage. The API returns only indexed search tags. The name field of the MetaTag object contains the indexed search tag. Search tags begin with search.* (for example, search.assetId). The content field contains the tag's value. |
MetaTag[] |
| snippet | A snippet of text from the webpage that describes its contents. | String |
| url | The URL to the webpage. Use this URL along with name to create a hyperlink that when clicked takes the user to the webpage. |
String |
Feedback
Coming soon: Throughout 2024 we will be phasing out GitHub Issues as the feedback mechanism for content and replacing it with a new feedback system. For more information see: https://aka.ms/ContentUserFeedback.
Submit and view feedback for