Edit

Get videos that are trending

  • Article

If you’re building a user experience that shows videos that are trending on social media in different categories, use this API.

Calling the API is easy. If you have your subscription key, just send an HTTP GET request to the following endpoint:

https://api.bing.microsoft.com/v7.0/videos/trending

Here's a cURL example that shows you how to call the endpoint using your subscription key.

curl -H "Ocp-Apim-Subscription-Key: <yourkeygoeshere>" https://api.bing.microsoft.com/v7.0/videos/trending

Request and response headers

Although that's all you need to do to get trending videos, Bing suggests you include a couple of other headers to provide a better experience for your user. Those headers include:

  • User-Agent — Lets Bing know whether the user needs a mobile or desktop experience.
  • X-MSEdge-ClientID — Provides continuity of experience.
  • X-MSEdge-ClientIP — Provides the user's location for location aware queries.
  • X-Search-Location — Provides the user's location for location aware queries.

The more information you can provide Bing, the better the experience will be for your users. To learn more about these headers, see Request headers.

Here's a cURL example that includes these headers.

curl -H "Ocp-Apim-Subscription-Key: <yourkeygoeshere>" -H "X-MSEdge-ClientID: 00B4230B74496E7A13CC2C1475056FF4" -H "X-MSEdge-ClientIP: 11.22.33.44" -H "X-Search-Location: lat:55;long:-111;re:22" -A "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/29.0.1547.65 Safari/537.36" https://api.bing.microsoft.com/v7.0/videos/trending

Bing returns a couple of headers you should capture.

  • BingAPIs-TraceId — ID that identifies the request in the log file.
  • X-MSEdge-ClientID — The ID that you need to pass in subsequent request to provide continuity of experience.
  • BingAPIs-Market — The market used by Bing for the request.

To learn more about these headers, see Response headers.

Here's a cURL call that returns the response headers. If you want to remove the response data so you can see only the headers, include the -o nul parameter.

curl -D - -H "Ocp-Apim-Subscription-Key: <yourkeygoeshere>" https://api.bing.microsoft.com/v7.0/videos/trending

Query parameters

The only query parameter that you should pass is the mkt parameter. Set to the market where the results come from, which is typically the market where the user is making the request from. For a list of markets that support trending videos, see Market codes.

You can ignore all other parameters listed in Query parameters.

Here's a cURL example that includes the mkt query parameter.

curl -H "Ocp-Apim-Subscription-Key: <yourkeygoeshere>" https://api.bing.microsoft.com/v7.0/videos/trending?mkt=en-us

Handling the response

When you send a request to Trending Videos API, it returns a TrendingVideos object in the response body. The TrendingVideos object contains a list of videos to highlight in the banner and a list of trending videos by category.

{
  "_type": "TrendingVideos",
  "bannerTiles": [
    {
      "query": { ... },
      "image": { ... }
    },

    . . .
  ],
  "categories": [
    {
      "title": "Music videos",
      "subcategories": [
        {
          "tiles": [
            {
              "query": { ... },
              "image": { ... }
            },
          
            . . .  
          ],
          "title": "Top "
        },
        {
          "tiles": [
            {
              "query": { ... },
              "image": { ... }
            },
          
            . . .  
          ],
          "title": "Trending "
        },

        . . .
      ]
    },
    {
      "title": "Viral videos",
      "subcategories": [ ... ]
    },
    {
      "title": "TV shows",
      "subcategories": [ ... ]
    },
    {
      "title": "Movie trailers",
      "subcategories": [ ... ]
    }
  ]
}

Display banner tiles

The bannerTiles field contains the list of Tile objects that you use to highlight videos in the banner of your UX.

  "bannerTiles": [
    {
      "query": {
        "text": "<search query string>",
        "displayText": "<search query string with possible hit highlighting characters>",
        "webSearchUrl": "https:\/\/www.bing.com\/videos\/search?q=<search query string>&FORM=VSTREQ"
      },
      "image": {
        "description": "Image from: contoso.com",
        "thumbnailUrl": "https:\/\/tse1.mm.bing.net\/th?id=OET.84ceafb8856247968fc5f3a...",
        "headLine": "<description that describes the video's content>",
        "contentUrl": "https:\/\/www.contoso.com\/2019\/10\/23\/path\/"
      }
    },

    . . .
  ]

Use thumbnailUrl to display an image of the video. Use description to attribute the image. Use headLine to provide a description of the video. Options for making the thumbnail clickable:

  • Use contentUrl to take the user to the provider's website where they can watch the video.
  • Use webSearchUrl to take the user to Bing's Video search results where they can watch this and other videos.

The categories field contains the lists of trending videos by category (see the Category object). Use the category's title to group the videos in your user experience. For example, Music videos and Movie trailers.

  "categories": [
    {
      "title": "Music videos",
      "subcategories": [ ... ]
    },
    {
      "title": "Viral videos",
      "subcategories": [ ... ]
    },
    {
      "title": "TV shows",
      "subcategories": [ ... ]
    },
    {
      "title": "Movie trailers",
      "subcategories": [ ... ]
    }
  ]

Each category is further subdivided into subcategories. For example, Music videos may be subdivided into Top music videos, Trending music videos, etc. Use the subcategory's title to group videos in your user experience.

    {
      "title": "Music videos",
      "subcategories": [
        {
          "tiles": [ ... ],
          "title": "Top "
        },
        {
          "tiles": [ ... ],
          "title": "Trending "
        },
        {
          "tiles": [ ... ],
          "title": "More music videos "
        },
      ]
    },

The tiles field contains the list of Tile objects. Each tile is a trending video.

      "subcategories": [
        {
          "tiles": [
            {
              "query": {
                "text": "<search query string>",
                "displayText": "<search query string with possible hit highlighting characters>",
                "webSearchUrl": "https:\/\/www.bing.com\/videos\/search?q=<search query string>&FORM=VSTREQ"
              },
              "image": {
                "description": "Image from: contoso.com",
                "thumbnailUrl": "https:\/\/tse1.mm.bing.net\/th?id=OET.84ceafb8856247968fc5f3a...",
                "contentUrl": "https:\/\/www.contoso.com\/2019\/10\/23\/path\/"
              }
            },
        
            . . .  
          ],
          "title": "Top "
        },

Use thumbnailUrl to display an image of the video. Use description to attribute the image. Options for making the thumbnail clickable:

  • Use contentUrl to take the user to the provider's website where they can watch the video.
  • Use webSearchUrl to take the user to Bing's Video search results where they can watch this and other videos.

Next steps