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 the SearchResponse object. And if the request fails, the top-level object in the response is the ErrorResponse object.

The JSON objects in this section are specific to the web answer. For details about the JSON objects for other answer types that the search results may include, see the API-specific reference documentation. For example, if the search results contain the images and news answers, see the Image Search API reference and News Search API reference.

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.

Attribution

Defines the publisher that the content is attributed to.

Name Value Type
providerDisplayName The publisher's name that you use to attribute the content to. String
seeMoreUrl The URL to the publisher's website. Use providerDisplayName and this URL to create a hyperlink that you display in the UX following the translation. String

Computation

Defines an expression and its answer.

Name Value Type
expression The math or conversion expression.

If the query contains a request to convert units of measure (for example, meters to feet), this field contains the from units and value contains the to units.

If the query contains a mathematical expression such as 2+2, this field contains the expression and value contains the answer.

Note that mathematical expressions may be normalized. For example, if the query was sqrt(4^2+8^2), the normalized expression may be sqrt((4^2)+(8^2)).

If the user's query is a math question and the textDecorations query parameter is set to true, the expression string may include formatting markers. For example, if the user's query is log(2), the normalized expression includes the subscript markers. For more information, see Hit highlighting.
String
value The expression's answer. 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[]

Identifiable

Defines the identity of a resource.

Name Value Type
id An identifier. String

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
height The height of the source image, in pixels. Unsigned Short
hostPageUrl The URL of the webpage that includes the image.

This URL and contentUrl may be the same URL.
String
name An optional text string that contains random information about the image. String
provider The source of the image. The array will contain a single item.

You must attribute the image to the provider. For example, you may display the provider's name as the cursor hovers over the image or make the image a click-through link to the provider's website where the image is found.

If the image object is part of a larger object, and the larger object contains a contractual rule that applies to this object, you must use the contractual rule for attribution instead of this field.
Organization[]
thumbnailUrl The URL to a thumbnail of the image. For information about resizing the image, see Resize and crop thumbnail images. String
width The width of the source image, in pixels. Unsigned Short

License

Defines the license under which you may use the content.

Name Value Type
name The name of the license. String
url A URL to the website that describes the license. Use 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

Malware

Defines a notice that the webpage may cause a potential issue if the user clicks the url link.

Name Value Type
beSafeRxUrl A URL to a webpage where the user may get more information about safely buying prescription medicine online. String
malwareWarningType The type of malware notice. Possible values are:
  • NABP — Warns that the National Association of Boards of Pharmacy includes this pharmacy on its Not Recommended list.
  • Malware — Warns that the site may download malicious software that may harm the user’s device.
  • MaliciousPageLink — Warns that the site may contain links that could download malicious software that may harm the user’s device.
  • Phishing — Warns that the site could trick the user into disclosing financial, personal, or other sensitive information.
String
warningExplanationUrl A URL to a webpage where the user can get an explanation of the issue. For NABP notices, users can use this link to verify a pharmacy. String
warningLetterUrl A URL to a webpage where the user can get more information about the notice. For NABP notices, users can use this link to see the list of online sites that the board doesn’t recommend. 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

MetaTag

Defines a webpage's metadata.

Name Value Type
content The metadata. String
name The name of the metadata. String

Organization

Defines a publisher.

Note that a publisher may provide their name or their website or both.

Name Value Type
name The publisher's name. String
url The URL to the publisher's website.

Note that the publisher may not provide a website.
String

Query

Defines a search query.

The SpellSuggestions object uses this object to suggest a query string that likely represents the user's intent. It's also used by RelatedSearchAnswer to return a related query that other users have made.

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 query enabled hit highlighting (see the textDecorations query parameter). For details about hit highlighting, see Hit highlighting. String
text The query string. Use this string as the query term in a new search request. String
webSearchUrl The URL that takes the user to the Bing search results page for the query.

Only related search results include this field.
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

RankingGroup

Defines a search results group, such as mainline.

Name Value Type
items A list of search result items to display in the group. RankingItem[]

RankingItem

Defines a search result item to display. For more information about how to use the IDs, see Ranking results.

Name Value Type
answerType The answer that contains the item to display. For example, News.

Use the type to find the answer in the SearchResponse object. The type is the name of a field in the SearchResponse object.
String
resultIndex A zero-based index of the item in the answer.

If the item does not include this field, display all items in the answer. For example, display all news articles in the News answer.
Integer
value The ID that identifies either an answer to display or an item of an answer to display. If the ID identifies an answer, display all items of the answer. Identifiable

RankingResponse

Defines where on the search results page content should be placed and in what order.

Name Value Type
mainline The search results to display in the mainline section of the search results page. RankingGroup
pole The search results that should be afforded the most visible treatment (for example, displayed above the mainline and sidebar). RankingGroup
sidebar The search results to display in the sidebar section of the search results page. RankingGroup

RelatedSearchAnswer

Defines a list of related queries made by others.

Name Value Type
id An ID that uniquely identifies the related search answer.

The object includes this field only if the Ranking answer specifies that you should display all related searches in a group. For more information about how to use the ID, see Ranking results.
String
value A list of related queries that were made by others. Query[]

SearchResponse

The response's top-level object for search requests that succeed.

By default, the Search API includes all relevant answers unless:

  • The query specifies the responseFilter query parameter to limit the answers it returns.
  • One or more of the search components does not return results (for example, no news results are relevant to the query).
  • The subscription key does not have access to the search component.

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
computation The answer to a math expression or unit conversion expression. Computation
entities A list of entities that are relevant to the search query. EntityAnswer
images A list of images that are relevant to the search query. ImageAnswer
news A list of news articles that are relevant to the search query. NewsAnswer
places A list of places that are relevant to the search query. LocalEntityAnswer
queryContext The query string that Bing used for the request. QueryContext
rankingResponse The order that Bing suggests that you display the search results in. RankingResponse
relatedSearches A list of related queries made by others. RelatedSearchAnswer
spellSuggestions The query string that likely represents the user's intent. SpellSuggestions
timeZone The date and time of one or more geographic locations. TimeZone
translations The translation of a word or phrase in the query string to another language. TranslationAnswer
videos A list of videos that are relevant to the search query. VideosAnswer
webPages A list of webpages that are relevant to the search query. WebAnswer

SpellSuggestions

Defines a suggested query string that likely represents the user's intent.

The search results include this response if Bing determines that the user may have intended to search for something different. For example, if the user searches for alon brown, Bing may determine that the user likely intended to search for Alton Brown instead (based on past searches by others of alon brown).

Name Value Type
id An ID that uniquely identifies the spelling suggestion answer.

You use this field when you use ranking response to display the spelling suggestions. For more information about how to use the ID, see Ranking results.
String
value A list of suggested query strings that may represent the user's intention.

The list contains only one Query object.
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

TimeZone

Defines the date and time of one or more geographic locations.

Name Value Type
date A date in string form. For example, Thursday, June 5, 2019. The answer may include this field if the user’s query asks Bing to compute a date. For example, 90 days from today. String
description A description of the response. The answer may include this field if the query asks Bing how many days or weeks in a period (for example, weeks in a year or days in a month), or converts time to a different time zone (for example, pst to est). String
otherCityTimes A list of dates and times in a geographical location. The answer includes this field for queries like US time zones or Arizona time zones. The list is ordered by UTC offset. TimeZoneInformation[]
primaryCityTime The data and time, in UTC, of the geographic location specified in the query.

If the query specified a specific geographic location (for example, a city), this object contains the name of the geographic location and the current date and time of the location.

If the query specified a general geographic location, such as a state or country, this object contains the date and time of the primary city or state found within the specified state or country. If the location contains additional time zones, the otherCityTimes field contains the date and time of cities or states located in the other time zones.
TimeZoneInformation
primaryResponse The primary data that satisfies the request. If the query string is how many weeks in 2019, this field contains, 52 weeks and 1 day. Other query examples: how many days in this month and what’s the date. String
primaryTimeZone The object contains the primary time zone in a geographical location. If a location contains more than one time zone, Bing determines which time zone is the primary time zone. The answer includes this field for queries like, time zone, time zones in Arizona, us time zones. TimeZoneInformation
timeZoneDifference The difference in time, in hours, between time zones. For example, there's a three hour difference between PST and EST. TimeZoneDifference

TimeZoneDifference

Defines the difference in time, in hours, between time zone 1 and time zone 2.

Name Value Type
location1 the date and time of the first time zone. For example, if the query is, pst to est, this field contains the date and time of the Pacific time zone. TimeZoneInformation
location2 the date and time of the second time zone. For example, if the query is, pst to est, this field contains the date and time of the Eastern time zone. TimeZoneInformation
text A string that represents the difference in time between time zones. String

TimeZoneInformation

Defines a date and time for a geographical location.

Name Value Type
location The type of the geographical location.

For example, County; City; City, State; City, State, Country; or Time Zone.
String
time The UTC date and time specified in the form, YYYY-MM-DDThh;mm:ss.ssssssZ. String
timeZoneName The name of the time zone that the location is in. This string may be empty if the query is not related to time zones. String
utcOffset The offset from UTC. For example, UTC-7. String

TranslationAnswer

Defines the translation of a word or phrase in the query string to another language.

Name Value Type
attributions A list of publishers that you must attribute the information to when you render the answer.

You must display the names of all publishers in the list as the source of the data. Typically, you display the providers in a single line after the translation. For example, “Data from: <provider> | <provider> | …", where <provider> is the name of the provider in providerDisplayName.

Note: If the answer includes contractualRules, you must apply them instead of applying attributions from this field.
Attribution[]
contractualRules A list of rules that you must adhere to if you display the answer. The following contractual rules may apply. Object[]
id An ID that uniquely identifies this answer.

The RankingResponse answer uses the ID to indicate where in the rendered response you should display this answer. For information about how to use this field, see How to use ranking to display search results.
String
inLanguage The language that the text was translated from. An ISO 639-1 two-letter language code identifies the language. For example, es for Spanish. String
originalText The text to translate. String
translatedLanguageName The language that the text was translated to. An ISO 639-1 two-letter language code identifies the language. For example, en for English. String
translatedText The translated text. String

WebAnswer

Defines a list of relevant webpage links.

Name Value Type
id An ID that uniquely identifies the web answer.

The object includes this field only if the Ranking answer suggests that you display all web results in a group. For more information about how to use the ID, see Ranking results.
String
someResultsRemoved A Boolean value that indicates whether the response excluded some results from the answer. If Bing excluded some results, the value is true. Boolean
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
about For internal use only. Object[]
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
contractualRules A list of rules that you must adhere to if you display the answer. The following contractual rules may apply.
For information about displaying contractual rules, see Data Attribution.
Object[]
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 and url fields and optionally the snippet field.
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
isFamilyFriendly A Boolean value that indicates whether the webpage contains adult content. If the webpage doesn't contain adult content, isFamilyFriendly is set to true. Boolean
isNavigational A Boolean value that indicates whether the user’s query is frequently used for navigation to different parts of the webpage’s domain. Is true if users navigate from this page to other parts of the website. Boolean
language A two-letter language code that identifies the language used by the webpage. For example, the language code is en for English. String
malware A notice that Bing provides if it thinks the webpage may cause a potential issue if the user clicks the url link. You should display the notice with high visibility next to the webpage link. Malware
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
mentions For internal use only. Object
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