Sending search requests to the Bing Video Search API
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.
This article describes the parameters and attributes of requests sent to the Bing Video Search API, as well as the JSON response object it returns.
Create an Azure resource
Start using the Bing Video Search API by creating one of the following Azure resources:
- Available through the Azure portal until you delete the resource.
- Use the free pricing tier to try the service, and upgrade later to a paid tier for production.
- Available through the Azure portal until you delete the resource.
- Use the same key and endpoint for your applications, across multiple Azure AI services.
Suggest search terms with the Bing Autosuggest API
If you provide a search box where the user enters their search term, use the Bing Autosuggest API to improve the experience. The API returns suggested query strings based on partial search terms as the user types.
After the user enters their search term, URL-encode it before setting the q query parameter. For example, if the user enters sailing dinghies, set q to sailing+dinghies or sailing%20dinghies.
Sending a request
To get Video search results, you'd send a GET request to the following endpoint:
https://api.cognitive.microsoft.com/bing/v7.0/videos/search
The request must use the HTTPS protocol.
We recommend that all requests originate from a server. Distributing the key as part of a client application provides more opportunity for a malicious third party to access it. Making calls from a server also provides a single upgrade point for future versions of the API.
The request must specify the q query parameter, which contains the user's search term. Although it's optional, the request should also specify the mkt query parameter, which identifies the market where you want the results to come from. For a list of optional query parameters such as pricing, see Query Parameters. All query parameter values must be URL encoded.
The request must specify the Ocp-Apim-Subscription-Key header. Although optional, you are encouraged to also specify the following headers:
The client IP and location headers are important for returning location aware content.
For a list of all request and response headers, see Headers.
Example search request
The following shows a search request that includes all the suggested query parameters and headers. 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.
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
Example JSON response
The following shows the response to the previous request. The example also shows the Bing-specific response headers.
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.
BingAPIs-TraceId: 76DD2C2549B94F9FB55B4BD6FEB6AC
X-MSEdge-ClientID: 1C3352B306E669780D58D607B96869
BingAPIs-Market: en-US
{
"_type" : "Videos",
"webSearchUrl" : "https:\/\/www.bing.com\/cr?IG=81EF7545D5694...",
"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=81EF7545D56...",
"thumbnailUrl" : "https:\/\/tse4.mm.bing.net\/th?id=OVP.DYWCvh...",
"datePublished" : "2014-03-04T11:51:53",
"publisher" : [
{
"name" : "Fabrikam"
}
],
"creator" : {
"name" : "Marcus Appel"
},
"contentUrl" : "https:\/\/www.fabrikam.com\/watch?v=vzmPjHZ--g",
"hostPageUrl" : "https:\/\/www.bing.com\/cr?IG=81EF7545D56944...",
"encodingFormat" : "h264",
"hostPageDisplayUrl" : "https:\/\/www.fabrikam.com\/watch?v=vzmPjBZ--g",
"width" : 1280,
"height" : 720,
"duration" : "PT2M47S",
"motionThumbnailUrl" : "https:\/\/tse3.mm.bing.net\/th?id=OM.Y6...",
"embedHtml" : "<iframe width=\"1280\" height=\"720\" src=\"https:...><\/iframe>",
"allowHttpsEmbed" : true,
"viewCount" : 8743,
"thumbnail" : {
"width" : 300,
"height" : 168
},
"videoId" : "6DB795E11A6E3CBAAD636DB795E11E3CBAAD63",
"allowMobileEmbed" : true,
"isSuperfresh" : false
},
. . .
],
"nextOffset" : 0,
"pivotSuggestions" : [
{
"pivot" : "sailing",
"suggestions" : []
},
{
"pivot" : "dinghies",
"suggestions" : [
{
"text" : "Sailing Cruising",
"displayText" : "Cruising",
"webSearchUrl" : "https:\/\/www.bing.com\/cr?IG=81EF754...",
"searchLink" : "https:\/\/api.cognitive.microsoft.com...",
"thumbnail" : {
"thumbnailUrl" : "https:\/\/tse4.mm.bing.net\/th?q=Sailing..."
}
},
. . .
]
}
]
}
Next steps
Try out the API. Go to Video Search API Testing Console.
For details about consuming the response objects, see Searching the Web for Videos.
For details about getting insights about a video such as related searches, see Video Insights.
For details about videos that are trending on social media, see Trending Videos.