YouTube APIs: Search Explained


Hi, I’m Jeff Fisher, and in this video, we’re going to talk about how to search for videos using the YouTube API A common operation on YouTube is searching for videos You search for videos in the API by using the videos feed. We specify our search term with the ‘q’ parameter. You can specify You can specify a more complicated search term by URL escaping it. There are many versions of the API which we can specify which version we want to use using the ‘v’ parameter, or a special header. Since there are many cute puppy videos on YouTube, and we don’t want to handle them all at once, we can specify how many we want by using ‘max-results.’ Since we only want 10 at once, but we might want to page to the next 10, we can look at the feed that’s returned to the API for a ‘link’ element with ‘rel’ equals ‘next’ This will identify the next page of results, and is the proper way of paging through a feed. If you look at that ‘next’ link, you’ll notice it has a ‘start-index’ parameter, which identifies the beginning of the next page However, you should not try to set this parameter manually and instead always extract the value of the ‘next’ link from the feed Now let’s talk about some other query parameters that you can use with the YouTube API First, we’re going to talk about ‘orderby’. By default, results are returned in order of relevance but you can also have them ordered by rating, view count, and the date they were published. You can also search for all the videos uploaded by a particular YouTube user with the ‘author’ parameter. This is equivalent to retrieving their uploads feed. In version 2 of the API, we added location based search where you can pass latitude and longitude information and find videos that occurred near that point. Since a large number of videos only have descriptive locations, such as London, if you only wish for videos with explicit latitude and longitude information to be returned, add an exclamation point to your query. To only show embeddable videos, such as for embedding on an external webpage, use the ‘format’ parameter. If you only want results in a specific language, you can use language restrict. Note this is only for video metadata, and not the audio track of the video You can also specify a safeSearch value which defaults to ‘moderate’, but can also be ‘strict’ or ‘none’ for filtering restricted content. Some videos cannot be played in certain locales. You can specify the locale of your user by passing in their country code or their IP address in which case we’ll figure out their country code for you. Note this is only to improve the user experience, as it will filter out videos they cannot play. Using this parameter will not affect the videos that they can play. YouTube has a number of video categories, such as Comedy, News and Politics, and more. If we only wanted videos in the Comedy category, we can use the ‘category’ parameter to retrieve them. If you are familiar with other Google Data APIs, you can also use the below syntax. If you want to do a tag search, you can use the same mechanism, such as searching for all videos that have the tag ‘puppy’ Note that the video category started with an uppercase letter, whereas tags are all lowercase.  This means that the above search is for all videos in the Comedy category,   whereas the below search is for videos that have the tag ‘comedy’.   You can also mix and match to combine the different query parameters we have discussed here.  For example, if you want to query for kitten videos in the Comedy category that are embeddable on external webpages, you could use this query.  YouTube also provides lists of popular videos    These are exposed in the API as standard feeds.   Such as the top rated videos, the most viewed videos, and the most discussed videos.    We can also look at the top rated videos that were uploaded this week using the ‘time’ parameter.  We could also look at the top rated videos this month, or today.  You are also able to look at only the top rated videos in this particular category, such as Comedy.  Note that this is different from using the ‘category’ query parameter we talked about earlier.  The above feed is the top 100 rated videos in the Comedy category.  Whereas the bottom is — of the top 100 rated videos on YouTube, which ones are in the Comedy category.  You can also look at regional versions of the different standard feeds, such as the top rated Comedy videos in Japan.  Hopefully, you’re getting pretty excited about using the YouTube API  But before you get started, we want to go over a few simple caveats.   You cannot retrieve more than 1000 videos in a video search feed. This is the same as YouTube.com.  The openSearch totalResults value is an approximation. This is part of why you should not do pagination manually, but instead use the ‘next’ link. Let’s go back to our earlier example about searching for cute puppy videos. Because YouTube is a large video website, the search information may be cached.  This means that the most recently uploaded cute puppy videos may not be displayed in the results.  It also means that the information in these videos, such as the title and description,   may take a couple hours to be updated in the search index.  Also, statistics about the video, such as view count and favorite information may not be up to date.  For videos uploaded as private, and later made public, it will take even longer to enter into the search index.  What if you know the ID of a video you want to retrieve information on.  Similar to searching for videos on YouTube, this information will be cached.  This is also true if you retrieve it through the uploads feed for a user when you’re not authenticated as them.  However, if you do authenticate as them, you will retrieve uncached information, which will be fresh.  Also, if you retrieve the uploads feed as the user, while authenticating as that user,   you will receive information about videos that is not cached.   This means it will the most recent information that YouTube has. It will be ordered by the published time.  However, if you add a query parameter, such as ‘orderby’ to this feed,  even though you’re authenticated, the results will be cached.  Two query parameters that will not affect the caching process, are start-index and max-results,   so you can still page through a feed.   If you are using one of our provided client libraries, there will be objects and methods which will help you build search queries on YouTube.   Please check the documentation for these client libraries for specifics. All the information in this video is also available in our documentation on code.google.com. Thanks for watching!

Leave a Reply

Your email address will not be published. Required fields are marked *