GET
/
search

This endpoint allows you to retrieve search results based on a query string. You can specify the number of results you want to retrieve, or paginate through the results.

​
Price

The cost of this request includes the base cost of $0.00003, plus an additional cost for quota usage.

Any search request requires 100 quotas.

Price will always be the same: $0.00003 + (100 quotas * $0.00001) = $0.00103

Authorizations

​
Authorization
string
headerrequired

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Query Parameters

​
q
string

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.

​
channelId
string

Indicates that the API response should only contain resources created by the channel.

Required string length: 24
​
channelType
enum<string>

Lets you restrict a search to a particular type of channel.

Available options:
any,
show,
channelTypeUnspecified
​
maxResults
string
default: 50

Specifies the maximum number of items that should be returned in the result set. Acceptable values are 0 to 50, inclusive.

​
order
enum<string>
default: relevance

Specifies the method that will be used to order resources in the API response.

Available options:
searchSortUnspecified,
date,
rating,
relevance,
title,
videoCount,
viewCount
​
pageToken
string

Identifies a specific page in the result set that should be returned. In an API response, the nextPageToken and prevPageToken properties identify other pages that could be retrieved.

​
publishedAfter
string

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).

​
publishedBefore
string

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).

​
regionCode
string

Instructs the API to return search results for videos that can be viewed in the specified country. The parameter value is an ISO 3166-1 alpha-2 country code.

Required string length: 2
​
relevanceLanguage
string

Instructs the API to return search results that are most relevant to the specified language. The parameter value is typically an ISO 639-1 two-letter language code.

​
safeSearch
enum<string>
default: moderate

Indicates whether the search results should include restricted content as well as standard content.

Available options:
moderate,
none,
strict,
safeSearchSettingUnspecified
​
topicId
enum<string>

Indicates that the API response should only contain resources associated with the specified topic. The value identifies a Freebase topic ID.

Available options:
/m/04rlf,
/m/02mscn,
/m/0ggq0m,
/m/01lyv,
/m/02lkt,
/m/0glt670,
/m/05rwpb,
/m/03_d0,
/m/028sqc,
/m/0g293,
/m/064t9,
/m/06cqb,
/m/06j6l,
/m/06by7,
/m/0gywn,
/m/0bzvm2,
/m/025zzc,
/m/02ntfj,
/m/0b1vjn,
/m/02hygl,
/m/04q1x3q,
/m/01sjng,
/m/0403l3g,
/m/021bp2,
/m/022dc6,
/m/03hf_rm,
/m/06ntj,
/m/0jm_,
/m/018jz,
/m/018w8,
/m/01cgz,
/m/09xp_,
/m/02vx4,
/m/037hz,
/m/03tmr,
/m/01h7lh,
/m/0410tth,
/m/07bs0,
/m/07_53,
/m/02jjt,
/m/09kqc,
/m/02vxn,
/m/05qjc,
/m/066wd,
/m/0f2f9,
/m/019_rr,
/m/032tl,
/m/027x7n,
/m/02wbm,
/m/03glg,
/m/068hy,
/m/041xxh,
/m/07c1v,
/m/07bxq,
/m/07yv9,
/m/098wr,
/m/09s1f,
/m/0kt51,
/m/01h6rj,
/m/05qt0,
/m/06bvp,
/m/01k8wb
​
type
string
default: video,channel,playlist

Restricts a search query to only retrieve a particular type of resource. The value is a comma-separated list of resource types. The default value is video,channel,playlist.

​
eventType
enum<string>

Restricts a search to broadcast events. If you specify a value for this parameter, you must also set the type parameter's value to video.

Available options:
completed,
live,
upcoming,
none
​
location
string

In conjunction with the locationRadius parameter, defines a circular geographic area and also restricts a search to videos that specify, in their metadata, a geographic location that falls within that area.

​
locationRadius
string

In conjunction with the location parameter, defines a circular geographic area.

​
videoCaption
enum<string>

Indicates whether the API should filter video search results based on whether they have captions.

Available options:
any,
closedCaption,
none,
videoCaptionUnspecified
​
videoCategoryId
enum<string>

Filters video search results based on their category.

Available options:
0,
1,
2,
10,
15,
17,
18,
19,
20,
21,
22,
23,
24,
25,
26,
27,
28,
29,
30,
31,
32,
33,
34,
35,
36,
37,
38,
39,
40,
41,
42,
43,
44
​
videoDefinition
enum<string>

Lets you restrict a search to only include either high definition (HD) or standard definition (SD) videos.

Available options:
any,
high,
standard
​
videoDimension
enum<string>
default: any

Lets you restrict a search to only retrieve 2D or 3D videos.

Available options:
2d,
3d,
any
​
videoDuration
enum<string>
default: any

Filters video search results based on their duration.

Available options:
any,
long,
medium,
short,
videoDurationUnspecified
​
videoEmbeddable
enum<string>

Lets you to restrict a search to only videos that can be embedded into a webpage.

Available options:
any,
true,
videoEmbeddableUnspecified
​
videoLicense
enum<string>

Filters search results to only include videos with a particular license.

Available options:
any,
creativeCommon,
youtube
​
videoPaidProductPlacement
enum<string>

Flters search results to only include videos that the creator has denoted as having a paid promotion.

Available options:
any,
true,
videoPaidProductPlacementUnspecified
​
videoSyndicated
enum<string>

Lets you to restrict a search to only videos that can be played outside youtube.com.

Available options:
any,
true,
videoSyndicatedUnspecified
​
videoType
enum<string>

Lets you restrict a search to a particular type of videos.

Available options:
any,
episode,
movie,
videoTypeUnspecified

Response

200 - application/json
​
regionCode
string
required

The region code that was used for the search.

​
totalResults
number
required

The total number of results in the result set.

​
resultsPerPage
number
required

The number of results included in the API response.

​
data
object[]
required

Array of search result objects.

​
nextPageToken
string

Token to retrieve the next page of results, if available

​
prevPageToken
string

Token to retrieve the previous page of results, if available

ErrorsGet popular videos