Modifier

Partager via


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:

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