Handle the video search response
When you send a request to Video Search API, it returns a VideosAnswer object in the response body. The object may include one or more of the following fields:
{
"_type": "Videos",
"readLink": "https://api.bing.microsoft.com/api/v7/videos/search?q=sailing+dinghies",
"webSearchUrl": "https://www.bing.com/videos/search?q=sailing+dinghies",
"queryContext": { ... },
"totalEstimatedMatches": 835,
"nextOffset": 36,
"currentOffset": 0,
"value": [ { ... } ],
"pivotSuggestions": [ { ... } ],
"relatedSearches": [ { ... } ]
}
But if an error occurs, the response body contains an ErrorResponse object. Bing returns an error response for all 400 level HTTP status codes. Read more.
{
"_type": "ErrorResponse",
"errors": [
{
"code": "InvalidAuthorization",
"subCode": "AuthorizationMissing",
"message": "Authorization is required.",
"moreDetails": "Subscription key is not recognized."
}
]
}
For information about the nextOffset
and totalEstimatedMatches
fields, see Paging image and video results.
Displaying videos
The value
field contains the list of Video objects that Bing thought were relevant. Here's what the Video object looks like in the response.
{
"webSearchUrl": "https://www.bing.com/videos/search?q=sailing%20dinghies...",
"name": "Getting Started - Dinghy Sailing - with...",
"description": "What to do when your small boat capsizes. Capsizing is a common occurrence...",
"thumbnailUrl": "https://tse2.mm.bing.net/th?id=OVP._9LeWLNdwQBZ8KKAIx...",
"datePublished": "2012-07-25T13:23:33.0000000",
"publisher": [
{
"name": "Fabrikam"
}
],
"creator": {
"name": "Contoso Yachting Association"
},
"isAccessibleForFree": true,
"isFamilyFriendly": true,
"contentUrl": "https://www.fabrikam.com/watch?v=EfJIu_mo",
"hostPageUrl": "https://www.fabrikam.com/watch?v=EfJIu_mo",
"encodingFormat": "h264",
"hostPageDisplayUrl": "https://www.fabrikam.com/watch?v=EfJIu_mo",
"width": 1280,
"height": 720,
"duration": "PT3M12S",
"motionThumbnailUrl": "https://tse1.mm.bing.net/th?id=OM.aBjM7NNnt5GKYA_1595...",
"embedHtml": "<iframe width=\"1280\" height=\"720\" src=\"https://www.fabrikam.com/embed/EfJIu_mo?autoplay=1\" frameborder=\"0\" allowfullscreen></iframe>",
"allowHttpsEmbed": true,
"viewCount": 148295,
"thumbnail": {
"width": 300,
"height": 225
},
"videoId": "608A91B767D3ECCC1868608A91B767DC1868",
"allowMobileEmbed": true,
"isSuperfresh": false
},
If you plan to display a collage of the videos on a page, use the following fields:
thumbnailUrl
— A URL to the thumbnail of the video thatcontentUrl
points to.thumbnail
— The size of the thumbnail thatthumbnailUrl
points to.
For information about resizing the thumbnail, see Resizing and cropping thumbnails.
You should display the following information with each thumbnail:
duration
— The video's length. Convert the duration notion to human-readable form. For example, convert PT3M12S to 3:12.name
— The video's title.datePublished
— The date that Bing discovered the video. Use the date portion of the date time stamp.publisher
— The publisher that's hosting the video.creator
— The person or organization that created the video.viewCount
— The number of times the video has been watched on the publisher's website. Gives an indication of how popular the video is.isAccessibleForFree
— A Boolean value that indicates whether the video is free to view. If false, add a currency sign when you display the video's information.
If you truncate any of the strings to fit your UX, append an ellipsis.
As the user hovers over the thumbnail, use motionThumbnailUrl
, if it exists, to play a thumbnail version of the video. Add a label over the motion thumbnail as it plays that says, Preview. If the Video object doesn't include motionThumbnailUrl
, add a label over the thumbnail as the user hovers over it that says, No preview.
Make the surface where you display the thumbnail and video information clickable by using one of the following URLs:
- Use
hostPageUrl
to view the video on the provider’s website. - Use
webSearchUrl
to view the video in Bing’s video viewer. - Use
embedHtml
, if it exists, to view the video in your own experience. If you provide your own view experience, considerallowHttpsEmbed
andallowMobileEmbed
.
Using pivot queries
If Bing can segment the user’s query, the response includes the pivotSuggestions
field, which is a list of Pivot objects. Each Pivot object contains one of the segments from the user’s query (see the pivot
field). For example, if the user's query is sailing dinghies, the pivots are sailing and dinghies. Basically, Bing replaces each pivot word in the user's query with another term. The following list contains some of the query suggestions for the dinghies pivot.
- Sailing Small Boats
- Sailing Rigging
- Sailing Yachts
As you can see from this example, Bing may not provide suggestions for all pivots.
"pivotSuggestions": [
{
"pivot": "sailing",
"suggestions": []
},
{
"pivot": "dinghies",
"suggestions": [
{
"text": "Sailing Small Boats",
"displayText": "Small Boats",
"webSearchUrl": "https://www.bing.com/videos/search?q=Sailing+Small+Boats...",
"searchLink": "https://api.bing.microsoft.com/v7/videos/search?q=Sailing+Small+Boats...",
"thumbnail": {
"thumbnailUrl": "https://tse4.mm.bing.net/th?q=Sailing+Small+Boats&pid=Api..."
}
},
{
"text": "Sailing Rigging",
"displayText": "Rigging",
"webSearchUrl": "https://www.bing.com/videos/search?q=Sailing+Rigging...",
"searchLink": "https://api.bing.microsoft.com/v7/videos/search?q=Sailing+Rigging...",
"thumbnail": {
"thumbnailUrl": "https://tse1.mm.bing.net/th?q=Sailing+Rigging&pid=Api..."
}
},
. . .
]
}
]
The pivotSuggestions
field contains the list of segments (pivots) that the original query was broken into. For each pivot, the response contains a list of Query objects that contain suggested queries. The text
field contains the suggested query. The displayText
field contains the term that replaces the pivot in the original query.
Make text
clickable by using the URL in webSearchUrl
or searchLink
. Use webSearchUrl
to send the user to Bing's Video search results. If you provide your own results page experience, use searchLink
to get new video search results using the pivot query string.
Related searches answer
The relatedSearches
field contains a list of the most popular related queries made by other users. Each query in the list includes a query string (text
), a query string with hit highlighting characters (displayText
), and a URL (webSearchUrl
) to Bing's Video search results page for that query.
"relatedSearches": [
{
"text": "Sailing Dinghy for Beginners",
"displayText": "Sailing Dinghy for Beginners",
"webSearchUrl": "https://www.bing.com/videos/search?q=Sailing+Dinghy+for+Beginners&FORM=VRPATC",
"searchLink": "https://api.bing.microsoft.com/v7/videos/search?q=Sailing+Dinghy+for+Beginners",
"thumbnail": {
"thumbnailUrl": "https://tse1.mm.bing.net/th?q=Sailing+Dinghy+for+Beginners&pid=Api..."
}
},
{
"text": "Sailing Boats",
"displayText": "Sailing Boats",
"webSearchUrl": "https://www.bing.com/videos/search?q=Sailing+Boats&FORM=VRPATC",
"searchLink": "https://api.bing.microsoft.com/v7/videos/search?q=Sailing+Boats",
"thumbnail": {
"thumbnailUrl": "https://tse3.mm.bing.net/th?q=Sailing+Boats&pid=Api..."
}
},
. . .
]
Use the displayText
query string and the webSearchUrl
URL to create a hyperlink that takes the user to Bing's Video search results page for the related query. If you provide your own results page experience, use searchLink
to get new video search results using the related query string.
For information about how to handle the highlighting markers in displayText
, see Hit Highlighting.
Next steps
- Learn how to get trending videos.
- Learn how to get insights about a video such as related videos.
- Learn about the quickstarts and samples that are available to help you get up and running fast.