WEBVTT 00:00:00.033 --> 00:00:08.615 Hi, I'm Jeff Fisher, and in this video, we're going to talk about how to search for videos using the YouTube API 00:00:08.615 --> 00:00:12.600 A common operation on YouTube is searching for videos 00:00:12.600 --> 00:00:15.906 You search for videos in the API by using the videos feed. 00:00:15.906 --> 00:00:20.500 We specify our search term with the 'q' parameter. You can specify 00:00:20.500 --> 00:00:24.800 You can specify a more complicated search term by URL escaping it. 00:00:24.800 --> 00:00:27.800 There are many versions of the API 00:00:27.800 --> 00:00:34.412 which we can specify which version we want to use using the 'v' parameter, or a special header. 00:00:34.412 --> 00:00:39.474 Since there are many cute puppy videos on YouTube, and we don't want to handle them all at once, 00:00:39.474 --> 00:00:44.675 we can specify how many we want by using 'max-results.' 00:00:44.675 --> 00:00:48.567 Since we only want 10 at once, but we might want to page to the next 10, 00:00:48.567 --> 00:00:53.986 we can look at the feed that's returned to the API for a 'link' element with 'rel' equals 'next' 00:00:53.986 --> 00:00:58.400 This will identify the next page of results, and is the proper way of paging through a feed. 00:00:58.400 --> 00:01:04.400 If you look at that 'next' link, you'll notice it has a 'start-index' parameter, which identifies the beginning of the next page 00:01:04.400 --> 00:01:10.844 However, you should not try to set this parameter manually and instead always extract the value of the 'next' link from the feed 00:01:10.844 --> 00:01:15.633 Now let's talk about some other query parameters that you can use with the YouTube API 00:01:15.633 --> 00:01:21.933 First, we're going to talk about 'orderby'. By default, results are returned in order of relevance 00:01:21.933 --> 00:01:28.800 but you can also have them ordered by rating, view count, and the date they were published. 00:01:28.800 --> 00:01:34.467 You can also search for all the videos uploaded by a particular YouTube user with the 'author' parameter. 00:01:34.467 --> 00:01:37.767 This is equivalent to retrieving their uploads feed. 00:01:37.767 --> 00:01:41.936 In version 2 of the API, we added location based search 00:01:41.936 --> 00:01:49.300 where you can pass latitude and longitude information and find videos that occurred near that point. 00:01:49.300 --> 00:01:52.710 Since a large number of videos only have descriptive locations, such as London, 00:01:52.710 --> 00:01:58.538 if you only wish for videos with explicit latitude and longitude information to be returned, 00:01:58.538 --> 00:02:02.508 add an exclamation point to your query. 00:02:02.508 --> 00:02:10.033 To only show embeddable videos, such as for embedding on an external webpage, use the 'format' parameter. 00:02:10.033 --> 00:02:14.400 If you only want results in a specific language, you can use language restrict. 00:02:14.400 --> 00:02:21.667 Note this is only for video metadata, and not the audio track of the video 00:02:21.667 --> 00:02:24.733 You can also specify a safeSearch value which defaults to 'moderate', 00:02:24.733 --> 00:02:31.967 but can also be 'strict' or 'none' for filtering restricted content. 00:02:31.967 --> 00:02:34.200 Some videos cannot be played in certain locales. 00:02:34.200 --> 00:02:38.967 You can specify the locale of your user by passing in their country code or their IP address 00:02:38.967 --> 00:02:41.309 in which case we'll figure out their country code for you. 00:02:41.309 --> 00:02:46.167 Note this is only to improve the user experience, as it will filter out videos they cannot play. 00:02:46.167 --> 00:02:52.333 Using this parameter will not affect the videos that they can play. 00:02:52.333 --> 00:02:57.267 YouTube has a number of video categories, such as Comedy, News and Politics, and more. 00:02:57.267 --> 00:03:03.933 If we only wanted videos in the Comedy category, we can use the 'category' parameter to retrieve them. 00:03:03.933 --> 00:03:08.709 If you are familiar with other Google Data APIs, you can also use the below syntax. 00:03:08.709 --> 00:03:18.300 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' 00:03:18.300 --> 00:03:23.667 Note that the video category started with an uppercase letter, whereas tags are all lowercase. 00:03:23.667 --> 00:03:27.867 This means that the above search is for all videos in the Comedy category, 00:03:27.867 --> 00:03:33.233 whereas the below search is for videos that have the tag 'comedy'. 00:03:33.233 --> 00:03:37.433 You can also mix and match to combine the different query parameters we have discussed here. 00:03:37.433 --> 00:03:41.733 For example, if you want to query for kitten videos in the Comedy category 00:03:41.733 --> 00:03:47.718 that are embeddable on external webpages, you could use this query. 00:03:47.718 --> 00:03:52.000 YouTube also provides lists of popular videos 00:03:52.000 --> 00:03:55.334 These are exposed in the API as standard feeds. 00:03:55.334 --> 00:04:01.633 Such as the top rated videos, the most viewed videos, and the most discussed videos. 00:04:01.633 --> 00:04:06.367 We can also look at the top rated videos that were uploaded this week using the 'time' parameter. 00:04:06.367 --> 00:04:13.533 We could also look at the top rated videos this month, or today. 00:04:13.533 --> 00:04:21.200 You are also able to look at only the top rated videos in this particular category, such as Comedy. 00:04:21.200 --> 00:04:25.033 Note that this is different from using the 'category' query parameter we talked about earlier. 00:04:25.033 --> 00:04:29.700 The above feed is the top 100 rated videos in the Comedy category. 00:04:29.700 --> 00:04:38.533 Whereas the bottom is -- of the top 100 rated videos on YouTube, which ones are in the Comedy category. 00:04:38.533 --> 00:04:48.276 You can also look at regional versions of the different standard feeds, such as the top rated Comedy videos in Japan. 00:04:48.276 --> 00:04:51.167 Hopefully, you're getting pretty excited about using the YouTube API 00:04:51.167 --> 00:04:56.867 But before you get started, we want to go over a few simple caveats. 00:04:56.867 --> 00:05:04.300 You cannot retrieve more than 1000 videos in a video search feed. This is the same as YouTube.com. 00:05:04.300 --> 00:05:07.339 The openSearch totalResults value is an approximation. 00:05:07.339 --> 00:05:14.133 This is part of why you should not do pagination manually, but instead use the 'next' link. 00:05:14.133 --> 00:05:18.100 Let's go back to our earlier example about searching for cute puppy videos. 00:05:18.100 --> 00:05:23.454 Because YouTube is a large video website, the search information may be cached. 00:05:23.454 --> 00:05:28.133 This means that the most recently uploaded cute puppy videos may not be displayed in the results. 00:05:28.133 --> 00:05:32.033 It also means that the information in these videos, such as the title and description, 00:05:32.033 --> 00:05:35.970 may take a couple hours to be updated in the search index. 00:05:35.970 --> 00:05:43.100 Also, statistics about the video, such as view count and favorite information may not be up to date. 00:05:43.100 --> 00:05:50.367 For videos uploaded as private, and later made public, it will take even longer to enter into the search index. 00:05:50.367 --> 00:05:55.233 What if you know the ID of a video you want to retrieve information on. 00:05:55.233 --> 00:06:01.467 Similar to searching for videos on YouTube, this information will be cached. 00:06:01.467 --> 00:06:07.572 This is also true if you retrieve it through the uploads feed for a user when you're not authenticated as them. 00:06:07.572 --> 00:06:16.267 However, if you do authenticate as them, you will retrieve uncached information, which will be fresh. 00:06:16.267 --> 00:06:20.167 Also, if you retrieve the uploads feed as the user, while authenticating as that user, 00:06:20.167 --> 00:06:25.382 you will receive information about videos that is not cached. 00:06:25.382 --> 00:06:30.900 This means it will the most recent information that YouTube has. It will be ordered by the published time. 00:06:30.900 --> 00:06:34.600 However, if you add a query parameter, such as 'orderby' to this feed, 00:06:34.600 --> 00:06:41.078 even though you're authenticated, the results will be cached. 00:06:41.078 --> 00:06:46.133 Two query parameters that will not affect the caching process, are start-index and max-results, 00:06:46.133 --> 00:06:50.133 so you can still page through a feed. 00:06:50.133 --> 00:06:52.533 If you are using one of our provided client libraries, 00:06:52.533 --> 00:06:56.845 there will be objects and methods which will help you build search queries on YouTube. 00:06:56.845 --> 00:07:01.000 Please check the documentation for these client libraries for specifics. 00:07:01.000 --> 00:07:07.300 All the information in this video is also available in our documentation on code.google.com. 00:07:07.300 --> 99:59:59.999 Thanks for watching!