0:00:00.033,0: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

0:00:08.615,0:00:12.600
A common operation on YouTube is searching for videos

0:00:12.600,0:00:15.906
You search for videos in the API by using the videos feed.

0:00:15.906,0:00:20.500
We specify our search term with the 'q' parameter. You can specify

0:00:20.500,0:00:24.800
You can specify a more complicated search term by URL escaping it.

0:00:24.800,0:00:27.800
There are many versions of the API

0:00:27.800,0:00:34.412
which we can specify which version we want to use using the 'v' parameter, or a special header.

0:00:34.412,0:00:39.474
Since there are many cute puppy videos on YouTube, and we don't want to handle them all at once,

0:00:39.474,0:00:44.675
we can specify how many we want by using 'max-results.'

0:00:44.675,0:00:48.567
Since we only want 10 at once, but we might want to page to the next 10,

0:00:48.567,0:00:53.986
we can look at the feed that's returned to the API for a 'link' element with 'rel' equals 'next'

0:00:53.986,0:00:58.400
This will identify the next page of results, and is the proper way of paging through a feed.

0:00:58.400,0: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

0:01:04.400,0: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

0:01:10.844,0:01:15.633
Now let's talk about some other query parameters that you can use with the YouTube API

0:01:15.633,0:01:21.933
First, we're going to talk about 'orderby'. By default, results are returned in order of relevance

0:01:21.933,0:01:28.800
but you can also have them ordered by rating, view count, and the date they were published.

0:01:28.800,0:01:34.467
You can also search for all the videos uploaded by a particular YouTube user with the 'author' parameter.

0:01:34.467,0:01:37.767
This is equivalent to retrieving their uploads feed.

0:01:37.767,0:01:41.936
In version 2 of the API, we added location based search

0:01:41.936,0:01:49.300
where you can pass latitude and longitude information and find videos that occurred near that point.

0:01:49.300,0:01:52.710
Since a large number of videos only have descriptive locations, such as London,

0:01:52.710,0:01:58.538
if you only wish for videos with explicit latitude and longitude information to be returned,

0:01:58.538,0:02:02.508
add an exclamation point to your query.

0:02:02.508,0:02:10.033
To only show embeddable videos, such as for embedding on an external webpage, use the 'format' parameter.

0:02:10.033,0:02:14.400
If you only want results in a specific language, you can use language restrict.

0:02:14.400,0:02:21.667
Note this is only for video metadata, and not the audio track of the video

0:02:21.667,0:02:24.733
You can also specify a safeSearch value which defaults to 'moderate',

0:02:24.733,0:02:31.967
but can also be 'strict' or 'none' for filtering restricted content.

0:02:31.967,0:02:34.200
Some videos cannot be played in certain locales.

0:02:34.200,0:02:38.967
You can specify the locale of your user by passing in their country code or their IP address

0:02:38.967,0:02:41.309
in which case we'll figure out their country code for you.

0:02:41.309,0:02:46.167
Note this is only to improve the user experience, as it will filter out videos they cannot play.

0:02:46.167,0:02:52.333
Using this parameter will not affect the videos that they can play.

0:02:52.333,0:02:57.267
YouTube has a number of video categories, such as Comedy, News and Politics, and more.

0:02:57.267,0:03:03.933
If we only wanted videos in the Comedy category, we can use the 'category' parameter to retrieve them.

0:03:03.933,0:03:08.709
If you are familiar with other Google Data APIs, you can also use the below syntax.

0:03:08.709,0: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'

0:03:18.300,0:03:23.667
Note that the video category started with an uppercase letter, whereas tags are all lowercase.

0:03:23.667,0:03:27.867
This means that the above search is for all videos in the Comedy category,

0:03:27.867,0:03:33.233
whereas the below search is for videos that have the tag 'comedy'.

0:03:33.233,0:03:37.433
You can also mix and match to combine the different query parameters we have discussed here.

0:03:37.433,0:03:41.733
For example, if you want to query for kitten videos in the Comedy category

0:03:41.733,0:03:47.718
that are embeddable on external webpages, you could use this query.

0:03:47.718,0:03:52.000
YouTube also provides lists of popular videos

0:03:52.000,0:03:55.334
These are exposed in the API as standard feeds.

0:03:55.334,0:04:01.633
Such as the top rated videos, the most viewed videos, and the most discussed videos.

0:04:01.633,0:04:06.367
We can also look at the top rated videos that were uploaded this week using the 'time' parameter.

0:04:06.367,0:04:13.533
We could also look at the top rated videos this month, or today.

0:04:13.533,0:04:21.200
You are also able to look at only the top rated videos in this particular category, such as Comedy.

0:04:21.200,0:04:25.033
Note that this is different from using the 'category' query parameter we talked about earlier.

0:04:25.033,0:04:29.700
The above feed is the top 100 rated videos in the Comedy category.

0:04:29.700,0:04:38.533
Whereas the bottom is -- of the top 100 rated videos on YouTube, which ones are in the Comedy category.

0:04:38.533,0:04:48.276
You can also look at regional versions of the different standard feeds, such as the top rated Comedy videos in Japan.

0:04:48.276,0:04:51.167
Hopefully, you're getting pretty excited about using the YouTube API

0:04:51.167,0:04:56.867
But before you get started, we want to go over a few simple caveats.

0:04:56.867,0:05:04.300
You cannot retrieve more than 1000 videos in a video search feed. This is the same as YouTube.com.

0:05:04.300,0:05:07.339
The openSearch totalResults value is an approximation.

0:05:07.339,0:05:14.133
This is part of why you should not do pagination manually, but instead use the 'next' link.

0:05:14.133,0:05:18.100
Let's go back to our earlier example about searching for cute puppy videos.

0:05:18.100,0:05:23.454
Because YouTube is a large video website, the search information may be cached.

0:05:23.454,0:05:28.133
This means that the most recently uploaded cute puppy videos may not be displayed in the results.

0:05:28.133,0:05:32.033
It also means that the information in these videos, such as the title and description,

0:05:32.033,0:05:35.970
may take a couple hours to be updated in the search index.

0:05:35.970,0:05:43.100
Also, statistics about the video, such as view count and favorite information may not be up to date.

0:05:43.100,0:05:50.367
For videos uploaded as private, and later made public, it will take even longer to enter into the search index.

0:05:50.367,0:05:55.233
What if you know the ID of a video you want to retrieve information on.

0:05:55.233,0:06:01.467
Similar to searching for videos on YouTube, this information will be cached.

0:06:01.467,0: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.

0:06:07.572,0:06:16.267
However, if you do authenticate as them, you will retrieve uncached information, which will be fresh.

0:06:16.267,0:06:20.167
Also, if you retrieve the uploads feed as the user, while authenticating as that user,

0:06:20.167,0:06:25.382
you will receive information about videos that is not cached.

0:06:25.382,0:06:30.900
This means it will the most recent information that YouTube has. It will be ordered by the published time.

0:06:30.900,0:06:34.600
However, if you add a query parameter, such as 'orderby' to this feed,

0:06:34.600,0:06:41.078
even though you're authenticated, the results will be cached.

0:06:41.078,0:06:46.133
Two query parameters that will not affect the caching process, are start-index and max-results,

0:06:46.133,0:06:50.133
so you can still page through a feed.

0:06:50.133,0:06:52.533
If you are using one of our provided client libraries,

0:06:52.533,0:06:56.845
there will be objects and methods which will help you build search queries on YouTube.

0:06:56.845,0:07:01.000
Please check the documentation for these client libraries for specifics.

0:07:01.000,0:07:07.300
All the information in this video is also available in our documentation on code.google.com.

0:07:07.300,9:59:59.000
Thanks for watching!