Video Search APIs v7 response objects
For a list of possible objects, see In this article in the right pane.
The top-level object in the response depends on the endpoint you call. If you call /videos/search, the top-level object in the response is the VideosAnswer object; for /videos/details, it's VideoDetails; and for /videos/trending, it's TrendingVideos. If the request fails, the top-level object 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.
Category
Defines the category of trending videos.
| Name | Value | Type |
|---|---|---|
| subcategories | A list of subcategories. For example, Top Music Videos. | Subcategory[] |
| title | The name of the video category. For example, Music Videos. | 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[] |
Image
Defines a thumbnail 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 |
|---|---|---|
| contentUrl | The URL to the image on the source website. | String |
| description | An attribution. | String |
| headline | A description of the video. | String |
| thumbnailUrl | The URL to a thumbnail of the image. For information about resizing the image, see Resize and crop thumbnail 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 |
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 query enabled hit highlighting (see the textDecorations query parameter). For details about hit highlighting, see Hit highlighting. | String |
| searchLink | The Video Search API URL that you use to get video search results. The URL includes the q query parameter that's set the search string in text. Before using the URL, append other 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 | A URL to a thumbnail image that represents the search string. | 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 |
Subcategory
Defines a subcategory of videos.
| Name | Value | Type |
|---|---|---|
| tiles | A list of videos that are trending in the subcategory. Each tile contains a thumbnail image of the video and a Bing query that returns the video and other related videos. | Tile[] |
| title | The name of the subcategory. For example, This Week's Viral Videos. | String |
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 |
Tile
Defines a video tile.
| Name | Value | Type |
|---|---|---|
| image | The URL to a thumbnail image of the video. | Image |
| query | A query that returns a Bing search results page with videos of the subject. For example, if the category is Top Music Videos, the query returns top music videos. | Query |
TrendingVideos
The top-level object that the response includes when a Trending Videos API request succeeds.
| Name | Value | Type |
|---|---|---|
| _type | Type hint, which is set to TrendingVideos. | String |
| bannerTiles | A list of the most popular trending videos. | Tile[] |
| categories | A list of categorized videos. For example, music videos and viral videos. | Category[] |
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 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 VideosAnswer 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. You can use the ID in a subsequent request to ensure that this video is the first video returned in the list of videos. To ensure the video is the first video in the list, set the request's id query parameter to this ID. | 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 |
VideoDetails
The top-level object that the response includes when a Video Details API request succeeds.
The modules query parameter affects the fields that Bing includes in the response. If you set modules to RelatedVideos, then this object includes only the relatedVideos field.
| Name | Value | Type |
|---|---|---|
| _type | Type hint, which is set to Api.VideoDetails.VideoDetails. | String |
| relatedVideos | A list of videos that are similar to the specified video.VideosModule | |
| videoResult | The original video that you requested insights of (this is the video that you set the id query parameter to in your insights request). | Video |
VideosAnswer
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 |
| currentOffset | The offset that represents where the first video in value is relative to all videos that Bing might return for this query. Also see nextOffset. |
|
| id | An ID that uniquely identifies the video answer. 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 |
| isFamilyFriendly | A Boolean value that determines whether one or more of the videos contain adult content. If none of the videos contain adult content, isFamilyFriendly is set to true. Otherwise, if one or more of the videos contain adult content, isFamilyFriendly is set to false.If false, the thumbnail images of the videos are pixelated (fuzzy). NOTE: Only Web Search API responses include this field (Video Search API responses do not include this field). |
Boolean |
| 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.Only Video Search API responses include this field. |
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. Only Video Search API responses include this field. |
Pivot[] |
| queryContext | The query string that Bing used for the request. | QueryContext |
| readLink | A URL that you'd use to request videos from Video Search API using the search query string used for this response. | String |
| relatedSearches | A list of related search queries made by others. | Query[] |
| scenario | The scenario that reflects the query's intent. The following are the possible values:
|
String |
| 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 |
VideosModule
Defines a list of videos.
| Name | Value | Type |
|---|---|---|
| value | A list of videos. | Video[] |
Feedback
Coming soon: Throughout 2024 we will be phasing out GitHub Issues as the feedback mechanism for content and replacing it with a new feedback system. For more information see: https://aka.ms/ContentUserFeedback.
Submit and view feedback for