Entity 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.
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.
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 |
| entityPresentationInfo | Additional information about the entity such as hints that you can use to determine the entity's type. To determine the entity's type, use the entityScenario and entityTypeHint fields. For example, the fields help you determine whether the entity is a dominant or disambiguation entity and whether it's a person or movie.The entity is a dominant entity if Bing believes that only one entity satisfies the request. If multiple entities could satisfy the request, the entity is a disambiguation entity and the user needs to select the entity they're interested in. |
EntityPresentationInfo |
| 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 |
EntityAnswer
Defines an entity answer that contains the list of entities.
| Name | Value | Type |
|---|---|---|
| queryScenario | The supported query scenario. This field is set to DominantEntity or DisambiguationItem. The field is set to DominantEntity if Bing determines that only a single entity satisfies the request. For example, a book, movie, person, or attraction. If multiple entities could satisfy the request, the field is set to DisambiguationItem. For example, if the request uses the generic title of a movie franchise, the entity's type would likely be DisambiguationItem. But, if the request specifies a specific title from the franchise, the entity's type would likely be DominantEntity. |
String |
| value | A list of entities. | Entity[] |
EntityPresentationInfo
Defines additional information about an entity such as type hints.
| Name | Value | Type |
|---|---|---|
| entityScenario | The supported scenario. | String |
| entityTypeDisplayHint | A display version of the entity hint. For example, if entityTypeHints is Artist, this field may be set to American Singer. |
String |
| entityTypeHint | A list of hints that indicate the entity's type. The list could contain a single hint such as Movie or a list of hints such as Place, LocalBusiness, Restaurant. Each successive hint in the array narrows the entity's type. For a list of possible types, see Entity Types. If the object does not include this field, Generic is assumed. |
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 the URL format 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. |
Organization[] |
| thumbnailUrl | The URL to a thumbnail of the image. | String |
| width | The width of the source image, in pixels. | Unsigned Short |
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 |
Link
Defines the components of a hyperlink.
| Name | Value | Type |
|---|---|---|
| _type | Type hint. | String |
| text | The display text. | String |
| url | A URL. Use the URL and display text to create a hyperlink. | 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 |
LocalEntityAnswer
Defines an local entity answer that contains the list of places.
| Name | Value | Type |
|---|---|---|
| value | A list of places. | Place[] |
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 |
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 |
Place
Defines information about a local entity, such as a restaurant or hotel.
Note
Entity responses support multiple markets, but the Places response supports only US Business locations.
| Name | Value | Type |
|---|---|---|
| _type | Type hint, which may be set to one of the following:
|
String |
| address | The postal address of where the entity is located. | PostalAddress |
| entityPresentationInfo | Additional information about the entity such as hints that you can use to determine the entity's type. For example, whether it's a restaurant or hotel. The entityScenario field is set to ListItem. |
EntityPresentationInfo |
| name | The entity's name. | String |
| telephone | The entity's telephone number. | String |
| url | The URL to the entity's website. Use this URL along with the entity's name to create a hyperlink that when clicked takes the user to the entity's website. |
String |
| webSearchUrl | The URL to Bing's search result for this place. | String |
PostalAddress
Defines a postal address.
| Name | Value | Type |
|---|---|---|
| addressCountry | The country/region where the street address is located. This could be the two-letter ISO code (for example, US) or the full name (for example, United States). | String |
| addressLocality | The city where the street address is located. For example, Seattle. | String |
| addressRegion | The state or province code where the street address is located. This could be the two-letter code (for example, WA) or the full name (for example, Washington). | String |
| neighborhood | The neighborhood where the street address is located. For example, Westlake. | String |
| postalCode | The zip code or postal code where the street address is located. For example, 98052. | 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 |
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 |
| entities | A list of entities that are relevant to the search query. | EntityAnswer |
| 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 |
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 |