YouTube Engineering and Developers Blog: September 2013

Engineering and Developers Blog

What's happening with engineering and developers at YouTube

What to watch? Our APIs can help!

Thursday, September 12, 2013

It’s an age-old question: what to watch? Applications that integrate with YouTube have access to countless hours of videos, and, as a developer, you have an interest in helping your users find the videos and channel most relevant to them. This blog post will walk you through a few ways that you can use the latest YouTube Data API to discover great content.

If you have an OAuth 2 token for the current user, your application can make a call to youtube.activities.list(part=”snippet”, home=true) to get back a list of videos and channels similar to the recommendations that the user would see on the YouTube.com home page. These results are customized for each individual user, and the list is kept fresh automatically, so it’s a great way to present your users with content they’re likely to enjoy.

Even if your users are not logged in, there are still are a few charts and guides at your disposal to aid in discovery.

To find popular videos your users might want to watch, youtube.videos.list(part=”snippet”, chart=”mostPopular”) is the basic API call to use. By default, it will return a list of videos in any category that are considered popular globally. If this is too broad a list, though, you can narrow things down using the regionCode or videoCategoryId (or both) parameters. regionCode can be set to a two-letter country code to retrieve a list of videos popular in that specific country (though not every country is currently supported). videoCategoryId needs to be set to an ID corresponding to one of our existing video categories—you can retrieve a list of valid categories and their corresponding IDs via youtube.videoCategories.list(part=”snippet”, regionCode=”XX”), where “XX” is also a two-letter country code.

There’s an analogous set of API calls that you could make to find channels your users might be interested in. youtube.guideCategories.list(part=”snippet”, regionCode=”XX”) will return a list of all the channel categories that are available in a given country. Once a user has chosen a category, you can get back a list of the most relevant channels in that category via a call to youtube.channels.list(part=”snippet”, categoryId=”CATEGORY_ID”), where “CATEGORY_ID” is the ID of the guide category you’re interested in. At that point, you could display a list of the most recent videos associated with each channel, and give your users the option of subscribing (assuming they grant OAuth 2 authorization first).

All of these examples assume that you’re using the latest version of the YouTube Data API, v3. Developers still using the Data API v1 or v2 should be aware of some recent changes to our older content discovery mechanism, standard feeds. As explained in the documentation, all of the previous different types of standard feeds are now returning the equivalent of the most_popular feed, with the time parameter set to “today”. If you are still using v1 or v2, there’s no time like the present (time=”today”, if you will) to make the switch to v3.

Update: For a walkthrough and demos of all the API calls, please watch this episode of YouTube Developers Live:
Cheers,—Jeff Posnick, YouTube API Team