Search for content / channels / playlists on YouTube - Official Search Endpoint.
auth_token
Required
Your YouTube API Key - see how to get your YouTube API Key if you need help.
channel_id
Optional
Restrict the video search to a specific channel.
channel_type
Optional
Restrict the search to a specific channel type of either:
any
All channelsshow
Only showsevent_type
Optional
Set this if you want to search for live events.
NOTE: You must change the “type” parameter to video
when using this option
completed
live
upcoming
language
Optional
Return results that are most relevant to the provided language. See here for language codes: http://www.loc.gov/standards/iso639-2/php/code_list.php
location_coordinates
Optional
Restrict the search to videos tagged in a specific location. These must be coordinates and you must also supply a “Location Radius”.
location_radius
Optional
When searching by location, also provide a radius in m, km, ft
. Be sure to set “Type” to video
.
order
Optional
Sort order of the results. From the official YouTube API:
The order parameter specifies the method that will be used to order resources in the API response. The default value is relevance.
Acceptable values are:
date
– Resources are sorted in reverse chronological order based on the date they were created.rating
– Resources are sorted from highest to lowest rating.relevance
– Resources are sorted based on their relevance to the search query. This is the default value for this parameter.title
– Resources are sorted alphabetically by title.videoCount
– Channels are sorted in descending order of their number of uploaded videos.viewCount
– Resources are sorted from highest to lowest number of views. For live broadcasts, videos are sorted by number of concurrent viewers while the broadcasts are ongoing.page_token
Optional
Pagination token from the previous response. Leave this blank at first and then look for the nextPageToken
value in the response’s root collection to get the next page of results.
published_after
Optional
Taken from https://developers.google.com/youtube/v3/docs/search/list
The publishedAfter parameter indicates that the API response should only contain resources created at or after the specified time. The value is an RFC 3339 formatted date-time value (1970-01-01T00:00:00Z).
published_before
Optional
Taken from https://developers.google.com/youtube/v3/docs/search/list
The publishedBefore parameter indicates that the API response should only contain resources created before or at the specified time. The value is an RFC 3339 formatted date-time value (1970-01-01T00:00:00Z).
query
Optional
From https://developers.google.com/youtube/v3/docs/search/list
The q parameter specifies the query term to search for.
Your request can also use the Boolean NOT (-) and OR (|) operators to exclude videos or to find videos that are associated with one of several search terms. For example, to search for videos matching either “boating” or “sailing”, set the q parameter value to boating|sailing. Similarly, to search for videos matching either “boating” or “sailing” but not “fishing”, set the q parameter value to boating|sailing -fishing. Note that the pipe character must be URL-escaped when it is sent in your API request. The URL-escaped value for the pipe character is %7C.
region_code
Optional
Restrict results to videos that can only be viewed in certain countries. See country codes here: http://www.iso.org/iso/country_codes/iso_3166_code_lists/country_names_and_code_elements.htm
related_video_id
Optional
Provide this value to return back a list of videos that are related to this one.
IMPORTANT You need to set the type
to video
for this to work.
safe_search
Optional
Whether to moderate the content returned. Default is moderate
, other possible values are:
none
Show all the results, may be inappropriatestrict
Exclude all restricted content (“safe search”)topic_id
Optional
Restrict results to the provided topic. You can get topic IDs by querying for channel details: https://stevesie.com/apps/youtube-api/channel-details and then add topicDetails
to the part input.
video_caption
Optional
Specify which types of videos to return based on their captions. Possible values are:
any
- Return all videos (default)closedCaption
- Only return videos with captionsnone
- Only return videos without captionsvideo_category_id
Optional
Execute https://developers.google.com/youtube/v3/docs/videoCategories/list and provide your country in the regionCode
to see a list of possible categories.
limit
Default 50
Pagination Limit
part
Default snippet
Parts to return in the response. Just enter in snippet
per the documentation: https://developers.google.com/youtube/v3/docs/search/list
type
Default video,channel,playlist
Type of results to return:
channel
playlist
video
IMPORTANT Many advanced search functions only work with type video
, so if you get a strange error then try changing this to video
.
Search for content / channels / playlists on YouTube - Official Search Endpoint.
/youtube/v3/search
?part={{part}}&key={{auth_token}}&q={{query}}&maxResults={{ limit }}&pageToken={{ page_token }}&eventType={{ event_type }}&type={{ type }}&publishedAfter={{ published_after }}&publishedBefore={{ published_before }}&order={{ order }}&relatedToVideoId={{ related_video_id }}&channelId={{ channel_id }}&channelType={{ channel_type }}&location={{ location_coordinates }}&locationRadius={{ location_radius }}®ionCode={{ region_code }}&relevanceLanguage={{ language }}&safeSearch={{ safe_search }}&topicId={{ topic_id }}&videoCaption={{ video_caption }}&videoCategoryId={{ video_category_id }}
Body
Headers