Search for videos with the Bing Video Search API

  • Grein

Warning

On October 30, 2020, the Bing Search APIs moved from Azure AI services to Bing Search Services. This documentation is provided for reference only. For updated documentation, see the Bing search API documentation. For instructions on creating new Azure resources for Bing search, see Create a Bing Search resource through the Azure Marketplace.

The Bing Video Search API makes it easy to integrate Bing's cognitive news searching capabilities into your applications. While the API primarily finds and returns relevant videos from the web, it provides several features for intelligent and focused video retrieval on the web.

Getting videos

To get videos related to the user's search term from the web, send the following GET request:

GET https://api.cognitive.microsoft.com/bing/v7.0/videos/search?q=sailing+dinghies&mkt=en-us HTTP/1.1
Ocp-Apim-Subscription-Key: 123456789ABCDE
User-Agent: Mozilla/5.0 (compatible; MSIE 10.0; Windows Phone 8.0; Trident/6.0; IEMobile/10.0; ARM; Touch; NOKIA; Lumia 822)
X-Search-ClientIP: 999.999.999.999
X-Search-Location: lat:47.60357;long:-122.3295;re:100
X-MSEdge-ClientID: <blobFromPriorResponseGoesHere>
Host: api.cognitive.microsoft.com

All requests must be made from a server.

If it's your first time calling any of the Bing APIs, don't include the client ID header. Only include the client ID if you've previously called a Bing API and Bing returned a client ID for the user and device combination.

To get videos from a specific domain, use the site: query operator.

GET https://api.cognitive.microsoft.com/bing/v7.0/videos/search?q=sailing+dinghies+site:contososailing.com&mkt=en-us HTTP/1.1

The response contains a Videos answer that contains a list of videos that Bing thought were relevant to the query. Each Video object in the list includes the URL of the video, its duration, its dimensions, and its encoding format among other attributes. The video object also includes the URL of a thumbnail of the video and the thumbnail's dimensions.

{
    "_type" : "Videos",
    "webSearchUrl" : "https:\/\/www.bing.com\/cr?IG=81EF7545...",
    "totalEstimatedMatches" : 1000,
    "value" : [
        {
            "name" : "How to sail - What to Wear for Dinghy Sailing",
            "description" : "An informative video on what to wear when...",
            "webSearchUrl" : "https:\/\/www.bing.com\/cr?IG=81EF7...",
            "thumbnailUrl" : "https:\/\/tse4.mm.bing.net\/th?id=OVP.DYW...",
            "datePublished" : "2014-03-04T11:51:53",
            "publisher" : [
                {
                    "name" : "Fabrikam"
                }
            ],
            "creator" : 
            {
                "name" : "Marcus Appel"
            },
            "contentUrl" : "https:\/\/www.fabrikam.com\/watch?v=vzmPjZ--g",
            "hostPageUrl" : "https:\/\/www.bing.com\/cr?IG=81EF7545D569...",
            "encodingFormat" : "h264",
            "hostPageDisplayUrl" : "https:\/\/www.fabrikam.com\/watch?v=vzmPjZ--g",
            "width" : 1280,
            "height" : 720,
            "duration" : "PT2M47S",
            "motionThumbnailUrl" : "https:\/\/tse3.mm.bing.net\/th?id=OM.Y62...",
            "embedHtml" : "<iframe width=\"1280\" height=\"720\" src=\"https:...><\/iframe>",
            "allowHttpsEmbed" : true,
            "viewCount" : 8743,
            "thumbnail" : 
            {
                "width" : 300,
                "height" : 168
            },
            "videoId" : "6DB795E11A6E3CBAAD636DB795E113CBAAD63",
            "allowMobileEmbed" : true,
            "isSuperfresh" : false
        },
        ...
    ],
    "queryExpansions" : [...],
    "nextOffsetAddCount" : 0,
    "pivotSuggestions" : [...]
}

Video thumbnails

You can display all, or a subset of the video thumbnails returned by the Bing Video Search API. If you display a subset, provide the user an option to view the remaining videos. as part of the Bing API use and display requirements, You must display the videos in the order provided in the response. For information about resizing the thumbnail, see Resizing and Cropping Thumbnails.

As the user hovers over the thumbnail you can use motionThumbnailUrl to play a thumbnail version of the video. Be sure to attribute the motion thumbnail when you display it.

When a thumbnail is clicked, there are three options for viewing the video:

  • Use hostPageUrl to view the video on the host website (for example, YouTube)
  • Use webSearchUrl to view the video in the Bing video browser
  • Use embdedHtml to embed the video in your own experience

Be sure to use the publisher and creator to attribute the video when you play it.

For details about using videoId to get insights about the video, see Video Insights.

Filtering videos

By default, the Video Search API returns all videos that are relevant to the query. If you only want free videos or videos less than five minutes in length, you'd use the following filter query parameters:

  • pricing—Filter videos by pricing (for example, videos that are free or that you have to pay for)
  • resolution—Filter videos by resolution (for example, videos with a 720p or higher resolution)
  • videoLength—Filter videos by video length (for example, videos that are less than five minutes in length)
  • freshness—Filter videos by age (for example, videos discovered by Bing in the past week)

To get videos from a specific domain, include the site: query operator in the query string.

Note

Depending on the query, if you use the site: query operator, there is the chance that the response contains adult content regardless of the safeSearch setting. You should use site: only if you are aware of the content on the site and your scenario supports the possibility of adult content.

The following example shows how to get free videos from ContosoSailing.com that have a resolution of 720p or better and that Bing has discovered in the past month.

GET https://api.cognitive.microsoft.com/bing/v7.0/videos/search?q=sailing+dinghies+site:contososailing.com&pricing=free&freshness=month&resolution=720p&mkt=en-us HTTP/1.1
Ocp-Apim-Subscription-Key: 123456789ABCDE
User-Agent: Mozilla/5.0 (compatible; MSIE 10.0; Windows Phone 8.0; Trident/6.0; IEMobile/10.0; ARM; Touch; NOKIA; Lumia 822)
X-MSEdge-ClientIP: 999.999.999.999
X-Search-Location: lat:47.60357;long:-122.3295;re:100
X-MSEdge-ClientID: <blobFromPriorResponseGoesHere>
Host: api.cognitive.microsoft.com

Expanding the query

If Bing can expand the query to narrow the original search, the Videos object contains the queryExpansions field. For example, if the query was Cleaning Gutters, the expanded queries might be: Gutter Cleaning Tools, Cleaning Gutters From the Ground, Gutter Cleaning Machine, and Easy Gutter Cleaning.

The following example shows the expanded queries for Cleaning Gutters.

{
    "_type" : "Videos",
    "webSearchUrl" : "https:\/\/www.bing.com\/cr?IG=B52FBC5...",
    "totalEstimatedMatches" : 1000,
    "value" : [...],
    "nextOffsetAddCount" : 4,
    "queryExpansions" : [
        {
            "text" : "Gutter Cleaning Tools",
            "displayText" : "Tools",
            "webSearchUrl" : "https:\/\/www.bing.com\/cr?IG=B52FB....",
            "searchLink" : "https:\/\/api.cognitive.microsoft.com\/api\/v5...",
            "thumbnail" : {
                "thumbnailUrl" : "https:\/\/tse4.mm.bing.net\/th?q=Gutter..."
            }
        },
        ...
    ]
    "pivotSuggestions" : [...],
}

The queryExpansions field contains a list of Query objects. The text field contains the expanded query and the displayText field contains the expansion term. You can use the text and thumbnail fields to display the expanded query strings to the user in case the expanded query string is really what they're looking for. Make the thumbnail and text clickable using the webSearchUrl URL or searchLink URL. Use webSearchUrl to send the user to the Bing search results, or searchLink if you provide your own results page.

Pivoting the query

If Bing can segment the original search query, the Videos object contains the pivotSuggestions field. For example, if the original query was Cleaning Gutters, Bing might segment the query into Cleaning and Gutters.

The following example shows the pivot suggestions for Cleaning Gutters.

{
    "_type" : "Videos",
    "webSearchUrl" : "https:\/\/www.bing.com\/cr?IG=B52FBC...",
    "totalEstimatedMatches" : 1000,
    "value" : [...],
    "nextOffsetAddCount" : 0,
    "queryExpansions" : [...],
    "pivotSuggestions" : [
        {
            "pivot" : "cleaning",
            "suggestions" : [
                {
                    "text" : "Gutter Repair",
                    "displayText" : "Repair",
                    "webSearchUrl" : "https:\/\/www.bing.com\/cr?IG=B52...",
                    "searchLink" : "https:\/\/api.cognitive.microsoft.com\/api\/v5\/videos...",
                    "thumbnail" : {
                        "thumbnailUrl" : "https:\/\/tse3.mm.bing.net\/th?q=Gutter..."
                    }
                },
                ...
            ]
        },
        {
            "pivot" : "gutters",
            "suggestions" : [
                {
                    "text" : "Window Cleaning",
                    "displayText" : "Window",
                    "webSearchUrl" : "https:\/\/www.bing.com\/cr?IG=B52FBC59...",
                    "searchLink" : "https:\/\/api.cognitive.microsoft.com\/api\/v5...",
                    "thumbnail" : {
                        "thumbnailUrl" : "https:\/\/tse2.mm.bing.net\/th?q=Window..."
                    }
                },
                ...
            ]
        }
    ]
}

For each pivot, the response contains a list of Query objects that contain suggested queries. The text field contains the suggested query and the displayText field contains the term that replaces the pivot in the original query. For example, Window Cleaning.

You can use the text and thumbnail fields to display the expanded query strings to the user in case the expanded query string is really what they're looking for. Make the thumbnail and text clickable using the webSearchUrl URL or searchLink URL. Use webSearchUrl to send the user to the Bing search results, or searchLink if you provide your own results page.

Throttling requests

The service and your subscription type determine the number of queries per second (QPS) that you can make. Make sure your application includes the logic to stay within your quota. If the QPS limit is met or exceeded, the request fails and an HTTP 429 status code is returned. The response includes the Retry-After header, which indicates how long you must wait before sending another request.

Denial-of-service versus throttling

The service makes a differentiation between a denial-of-service (DoS) attack and a QPS violation. If the service suspects a DoS attack, the request succeeds (HTTP status code is 200 OK). However, the body of the response is empty.