If the query requests information about a person, place or thing, the response can contain an entities answer. Queries always return webpages, facts and/or entities are query dependent.
Entities support three query scenarios:
- DominantEntity—There is only one entity that matches the user's query and intent. For example, the query, Space Needle, is a DominantEntity scenario.
- Disambiguation—There is more than one entity that matches the user's query and intent and it is up to the user to select the correct entity. For example, the query Game of Thrones is a Disambiguation scenario that returns the television show and the book series.
- List—There are multiple entities that match the user's query and intent. For example, the query "List of endangered species" is a list scenario that returns tabular values formatted for display in rows and cells.
To determine the query scenario, use the queryScenario field of the entities object.
The data that the entity includes depends on the entity's type. Although entities include the same basic information, some entities such as tourist attractions or books include additional properties. Entities that include additional properties include the _type field that contains a hint used by the serializer. The following entities include additional properties:
- Book
- MusicRecording
- Person
- Attraction
To determine the type of entity that the response contains, use the entityTypeHints field as shown in the query for Bill Gates.
},
"description": "Bill Gates is an American business man and philanthropist, co-founder of Microsoft",
"entityPresentationInfo": {
"entityScenario": "DominantEntity",
"entityTypeHints": [
"Person"
]
},
"bingId": "6d7d66a7-2cb8-0ae9-637c-f81fd749dc9a"
}
The following is a query for Space Needle:
https://api.labs.cognitive.microsoft.com/answerSearch/v7.0/search?q=space+needle&mkt=en-us
The response includes the entities answer. Note the entityScenario and entityTypeHints fields.
"entities": {
"value": [
{
"id": "https://www.bingapis.com/api/v7/#Entities.0",
"contractualRules": [
{
"_type": "ContractualRules/LicenseAttribution",
"targetPropertyName": "description",
"mustBeCloseToContent": true,
"license": {
"name": "CC-BY-SA",
"url": "https://creativecommons.org/licenses/by-sa/3.0/"
},
"licenseNotice": "Text under CC-BY-SA license"
},
{
"_type": "ContractualRules/LinkAttribution",
"targetPropertyName": "description",
"mustBeCloseToContent": true,
"text": "Wikipedia",
"url": "https://en.wikipedia.org/wiki/Space_Needle"
},
{
"_type": "ContractualRules/MediaAttribution",
"targetPropertyName": "image",
"mustBeCloseToContent": true,
"url": "https://en.wikipedia.org/wiki/Space_Needle"
}
],
"webSearchUrl": "https://www.bing.com/entityexplore?q\u003dSpace+Needle\u0026filters\u003dsid:%22f8dd5b08-206d-2554-6e4a-893f51f4de7e%22\u0026elv\u003dAXXfrEiqqD9r3GuelwApulpmymQx!ODfuQu*veOQHkvP0!Zbvi5F5tVcMSDJvDEWiQWwrdueYTtIszgj03oFQHykYYLYgq3q5!Sf00QxXGIS",
"name": "Space Needle",
"image": {
"name": "Space Needle",
"thumbnailUrl": "https://www.bing.com/th?id\u003dA15d336cf119b9b5c7e0ab37e271421d3\u0026w\u003d110\u0026h\u003d110\u0026c\u003d7\u0026rs\u003d1\u0026qlt\u003d80\u0026cdv\u003d1\u0026pid\u003d16.1",
"provider": [
{
"_type": "Organization",
"url": "https://en.wikipedia.org/wiki/Space_Needle"
}
],
"hostPageUrl": "https://upload.wikimedia.org/wikipedia/commons/2/23/Space_Needle_2011-07-04.jpg",
"width": 110,
"height": 110,
"sourceWidth": 152,
"sourceHeight": 300
},
"description": "The Space Needle is an observation tower in Seattle, Washington, a landmark of the Pacific Northwest, and an icon of Seattle. It was built in the Seattle Center for the 1962 World\u0027s Fair, which drew over 2.3 million visitors, when nearly 20,000 people a day used its elevators.",
"entityPresentationInfo": {
"entityScenario": "DominantEntity",
"entityTypeHints": [
"Attraction"
]
},
"bingId": "f8dd5b08-206d-2554-6e4a-893f51f4de7e"
}
]
},
A query can return a list if it is relevant.
Query: The following query finds a list of endangered species:
https://api.labs.cognitive.microsoft.com/answerSearch/v7.0/search?q=list+of+endangered+species
Response: The response includes a list formatted for display as tabular values:
"facts": {
"id": "https://www.bingapis.com/api/v7/#Facts",
"contractualRules": [
{
"_type": "ContractualRules/LinkAttribution",
"text": "www.worldwildlife.org/species/directory?direction=desc&sort=e…",
"url": "https://www.worldwildlife.org/species/directory?direction=desc&sort=extinction_status"
}
],
"attributions": [
{
"providerDisplayName": "www.worldwildlife.org/species/directory?direction=desc&sort=e…",
"seeMoreUrl": "https://www.worldwildlife.org/species/directory?direction=desc&sort=extinction_status"
}
],
"value": [
{
"subjectName": "Species Directory",
"richCaption": {
"_type": "StructuredValue/TabularData",
"header": [
"Common name",
"Scientific name",
"Conservation status ↓"
],
"rows": [
{
"cells": [
{
"_type": "Properties/Link",
"text": "Amur Leopard",
"url": "https://www.bing.com/https//www.worldwildlife.org/species/amur-leopard"
},
{
"text": "Panthera pardus orientalis"
},
{
"text": "Critically Endangered"
}
]
},
{
"cells": [
{
"_type": "Properties/Link",
"text": "Black Rhino",
"url": "https://www.bing.com/https//www.worldwildlife.org/species/black-rhino"
},
{
"text": "Diceros bicornis"
},
{
"text": "Critically Endangered"
}
]
},
{
"cells": [
{
"_type": "Properties/Link",
"text": "Bornean Orangutan",
"url": "https://www.bing.com/https//www.worldwildlife.org/species/bornean-orangutan"
},
{
"text": "Pongo pygmaeus"
},
{
"text": "Critically Endangered"
}
]
},
{
"cells": [
{
"_type": "Properties/Link",
"text": "Cross River Gorilla",
"url": "https://www.bing.com/https//www.worldwildlife.org/species/cross-river-gorilla"
},
{
"text": "Gorilla gorilla diehli"
},
{
"text": "Critically Endangered"
}
]
}
],
"seeMoreUrl": {
"text": "46 more rows",
"url": "https://www.worldwildlife.org/species/directory?direction=desc&sort=extinction_status"
}
}
}
]
},