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.

Name	Value	Type
displayText	The suggested query term to display in a user interface.	String
query	The suggested query term. If the user selects the query term from the list of suggestions, use the term in a Bing API request and display the search results yourself.	String
searchKind	The type of suggestion. The following are the possible values: CustomSearch — The suggestion is from a non-web search suggestion data source. WebSearch — The suggestion is from a web search suggestion data source.	String

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: Custom — The group contains suggestions from a non-web search suggestions data source. Web — The group contains web search suggestions.	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