Gitiles
Code Review Sign In
gerrit-public.fairphone.software / platform / external / python / google-api-python-client / c482712935d1c1331e33bd7f9968bd3b2be223bb / . / docs / dyn / youtube_v3.search.html
blob: 747c47da4ccc54e609797689aefdae020d1ca752 [file] [log] [blame]
John Asmuth614db982014-04-24 15:46:26 -0400[diff] [blame]1<html><body>
2<style>
3
4body, h1, h2, h3, div, span, p, pre, a {
5 margin: 0;
6 padding: 0;
7 border: 0;
8 font-weight: inherit;
9 font-style: inherit;
10 font-size: 100%;
11 font-family: inherit;
12 vertical-align: baseline;
13}
14
15body {
16 font-size: 13px;
17 padding: 1em;
18}
19
20h1 {
21 font-size: 26px;
22 margin-bottom: 1em;
23}
24
25h2 {
26 font-size: 24px;
27 margin-bottom: 1em;
28}
29
30h3 {
31 font-size: 20px;
32 margin-bottom: 1em;
33 margin-top: 1em;
34}
35
36pre, code {
37 line-height: 1.5;
38 font-family: Monaco, 'DejaVu Sans Mono', 'Bitstream Vera Sans Mono', 'Lucida Console', monospace;
39}
40
41pre {
42 margin-top: 0.5em;
43}
44
45h1, h2, h3, p {
46 font-family: Arial, sans serif;
47}
48
49h1, h2, h3 {
50 border-bottom: solid #CCC 1px;
51}
52
53.toc_element {
54 margin-top: 0.5em;
55}
56
57.firstline {
58 margin-left: 2 em;
59}
60
61.method {
62 margin-top: 1em;
63 border: solid 1px #CCC;
64 padding: 1em;
65 background: #EEE;
66}
67
68.details {
69 font-weight: bold;
70 font-size: 14px;
71}
72
73</style>
74
75<h1><a href="youtube_v3.html">YouTube Data API</a> . <a href="youtube_v3.search.html">search</a></h1>
76<h2>Instance Methods</h2>
77<p class="toc_element">
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame]78 <code><a href="#list">list(part, channelId=None, channelType=None, eventType=None, forContentOwner=None, forDeveloper=None, forMine=None, location=None, locationRadius=None, maxResults=None, onBehalfOfContentOwner=None, order=None, pageToken=None, publishedAfter=None, publishedBefore=None, q=None, regionCode=None, relatedToVideoId=None, relevanceLanguage=None, safeSearch=None, topicId=None, type=None, videoCaption=None, videoCategoryId=None, videoDefinition=None, videoDimension=None, videoDuration=None, videoEmbeddable=None, videoLicense=None, videoSyndicated=None, videoType=None)</a></code></p>
John Asmuth614db982014-04-24 15:46:26 -0400[diff] [blame]79<p class="firstline">Returns a collection of search results that match the query parameters specified in the API request. By default, a search result set identifies matching video, channel, and playlist resources, but you can also configure queries to only retrieve a specific type of resource.</p>
80<p class="toc_element">
81 <code><a href="#list_next">list_next(previous_request, previous_response)</a></code></p>
82<p class="firstline">Retrieves the next page of results.</p>
83<h3>Method Details</h3>
84<div class="method">
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame]85 <code class="details" id="list">list(part, channelId=None, channelType=None, eventType=None, forContentOwner=None, forDeveloper=None, forMine=None, location=None, locationRadius=None, maxResults=None, onBehalfOfContentOwner=None, order=None, pageToken=None, publishedAfter=None, publishedBefore=None, q=None, regionCode=None, relatedToVideoId=None, relevanceLanguage=None, safeSearch=None, topicId=None, type=None, videoCaption=None, videoCategoryId=None, videoDefinition=None, videoDimension=None, videoDuration=None, videoEmbeddable=None, videoLicense=None, videoSyndicated=None, videoType=None)</code>
John Asmuth614db982014-04-24 15:46:26 -0400[diff] [blame]86 <pre>Returns a collection of search results that match the query parameters specified in the API request. By default, a search result set identifies matching video, channel, and playlist resources, but you can also configure queries to only retrieve a specific type of resource.
87
88Args:
Takashi Matsuo06694102015-09-11 13:55:40 -0700[diff] [blame]89 part: string, The part parameter specifies a comma-separated list of one or more search resource properties that the API response will include. Set the parameter value to snippet. (required)
John Asmuth614db982014-04-24 15:46:26 -0400[diff] [blame]90 channelId: string, The channelId parameter indicates that the API response should only contain resources created by the channel
John Asmuth614db982014-04-24 15:46:26 -0400[diff] [blame]91 channelType: string, The channelType parameter lets you restrict a search to a particular type of channel.
92 Allowed values
93 any - Return all channels.
94 show - Only retrieve shows.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame]95 eventType: string, The eventType parameter restricts a search to broadcast events. If you specify a value for this parameter, you must also set the type parameter&#x27;s value to video.
John Asmuth614db982014-04-24 15:46:26 -0400[diff] [blame]96 Allowed values
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame]97 completed - Only include completed broadcasts.
98 live - Only include active broadcasts.
99 upcoming - Only include upcoming broadcasts.
John Asmuth614db982014-04-24 15:46:26 -0400[diff] [blame]100 forContentOwner: boolean, Note: This parameter is intended exclusively for YouTube content partners.
101
102The forContentOwner parameter restricts the search to only retrieve resources owned by the content owner specified by the onBehalfOfContentOwner parameter. The user must be authenticated using a CMS account linked to the specified content owner and onBehalfOfContentOwner must be provided.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame]103 forDeveloper: boolean, The forDeveloper parameter restricts the search to only retrieve videos uploaded via the developer&#x27;s application or website. The API server uses the request&#x27;s authorization credentials to identify the developer. Therefore, a developer can restrict results to videos uploaded through the developer&#x27;s own app or website but not to videos uploaded through other apps or sites.
104 forMine: boolean, The forMine parameter restricts the search to only retrieve videos owned by the authenticated user. If you set this parameter to true, then the type parameter&#x27;s value must also be set to video.
Takashi Matsuo06694102015-09-11 13:55:40 -0700[diff] [blame]105 location: string, The location parameter, 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. The parameter value is a string that specifies latitude/longitude coordinates e.g. (37.42307,-122.08427).
106
107
108- The location parameter value identifies the point at the center of the area.
109- The locationRadius parameter specifies the maximum distance that the location associated with a video can be from that point for the video to still be included in the search results.The API returns an error if your request specifies a value for the location parameter but does not also specify a value for the locationRadius parameter.
110 locationRadius: string, The locationRadius parameter, in conjunction with the location parameter, defines a circular geographic area.
111
112The parameter value must be a floating point number followed by a measurement unit. Valid measurement units are m, km, ft, and mi. For example, valid parameter values include 1500m, 5km, 10000ft, and 0.75mi. The API does not support locationRadius parameter values larger than 1000 kilometers.
113
114Note: See the definition of the location parameter for more information.
John Asmuth614db982014-04-24 15:46:26 -0400[diff] [blame]115 maxResults: integer, The maxResults parameter specifies the maximum number of items that should be returned in the result set.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame]116 onBehalfOfContentOwner: string, Note: This parameter is intended exclusively for YouTube content partners.
Takashi Matsuo06694102015-09-11 13:55:40 -0700[diff] [blame]117
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame]118The onBehalfOfContentOwner parameter indicates that the request&#x27;s authorization credentials identify a YouTube CMS user who is acting on behalf of the content owner specified in the parameter value. This parameter is intended for YouTube content partners that own and manage many different YouTube channels. It allows content owners to authenticate once and get access to all their video and channel data, without having to provide authentication credentials for each individual channel. The CMS account that the user authenticates with must be linked to the specified YouTube content owner.
John Asmuth614db982014-04-24 15:46:26 -0400[diff] [blame]119 order: string, The order parameter specifies the method that will be used to order resources in the API response.
120 Allowed values
121 date - Resources are sorted in reverse chronological order based on the date they were created.
122 rating - Resources are sorted from highest to lowest rating.
123 relevance - Resources are sorted based on their relevance to the search query. This is the default value for this parameter.
124 title - Resources are sorted alphabetically by title.
125 videoCount - Channels are sorted in descending order of their number of uploaded videos.
126 viewCount - Resources are sorted from highest to lowest number of views.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame]127 pageToken: string, The pageToken parameter 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.
128 publishedAfter: string, The publishedAfter parameter indicates that the API response should only contain resources created after the specified time. The value is an RFC 3339 formatted date-time value (1970-01-01T00:00:00Z).
129 publishedBefore: string, The publishedBefore parameter indicates that the API response should only contain resources created before the specified time. The value is an RFC 3339 formatted date-time value (1970-01-01T00:00:00Z).
130 q: string, The q parameter specifies the query term to search for.
131
132Your 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 &quot;boating&quot; or &quot;sailing&quot;, set the q parameter value to boating|sailing. Similarly, to search for videos matching either &quot;boating&quot; or &quot;sailing&quot; but not &quot;fishing&quot;, 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.
133 regionCode: string, The regionCode parameter instructs the API to return search results for the specified country. The parameter value is an ISO 3166-1 alpha-2 country code.
134 relatedToVideoId: string, The relatedToVideoId parameter retrieves a list of videos that are related to the video that the parameter value identifies. The parameter value must be set to a YouTube video ID and, if you are using this parameter, the type parameter must be set to video.
135 relevanceLanguage: string, The relevanceLanguage parameter 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. However, you should use the values zh-Hans for simplified Chinese and zh-Hant for traditional Chinese. Please note that results in other languages will still be returned if they are highly relevant to the search query term.
136 safeSearch: string, The safeSearch parameter indicates whether the search results should include restricted content as well as standard content.
137 Allowed values
138 moderate - YouTube will filter some content from search results and, at the least, will filter content that is restricted in your locale. Based on their content, search results could be removed from search results or demoted in search results. This is the default parameter value.
139 none - YouTube will not filter the search result set.
140 strict - YouTube will try to exclude all restricted content from the search result set. Based on their content, search results could be removed from search results or demoted in search results.
141 topicId: string, The topicId parameter indicates that the API response should only contain resources associated with the specified topic. The value identifies a Freebase topic ID.
142 type: string, The type parameter restricts a search query to only retrieve a particular type of resource. The value is a comma-separated list of resource types.
143 videoCaption: string, The videoCaption parameter indicates whether the API should filter video search results based on whether they have captions. If you specify a value for this parameter, you must also set the type parameter&#x27;s value to video.
144 Allowed values
145 any - Do not filter results based on caption availability.
146 closedCaption - Only include videos that have captions.
147 none - Only include videos that do not have captions.
148 videoCategoryId: string, The videoCategoryId parameter filters video search results based on their category. If you specify a value for this parameter, you must also set the type parameter&#x27;s value to video.
149 videoDefinition: string, The videoDefinition parameter lets you restrict a search to only include either high definition (HD) or standard definition (SD) videos. HD videos are available for playback in at least 720p, though higher resolutions, like 1080p, might also be available. If you specify a value for this parameter, you must also set the type parameter&#x27;s value to video.
150 Allowed values
151 any - Return all videos, regardless of their resolution.
152 high - Only retrieve HD videos.
153 standard - Only retrieve videos in standard definition.
154 videoDimension: string, The videoDimension parameter lets you restrict a search to only retrieve 2D or 3D videos. If you specify a value for this parameter, you must also set the type parameter&#x27;s value to video.
155 Allowed values
156 2d - Restrict search results to exclude 3D videos.
157 3d - Restrict search results to only include 3D videos.
158 any - Include both 3D and non-3D videos in returned results. This is the default value.
159 videoDuration: string, The videoDuration parameter filters video search results based on their duration. If you specify a value for this parameter, you must also set the type parameter&#x27;s value to video.
160 Allowed values
161 any - Do not filter video search results based on their duration. This is the default value.
162 long - Only include videos longer than 20 minutes.
163 medium - Only include videos that are between four and 20 minutes long (inclusive).
164 short - Only include videos that are less than four minutes long.
165 videoEmbeddable: string, The videoEmbeddable parameter lets you to restrict a search to only videos that can be embedded into a webpage. If you specify a value for this parameter, you must also set the type parameter&#x27;s value to video.
166 Allowed values
167 any - Return all videos, embeddable or not.
168 true - Only retrieve embeddable videos.
169 videoLicense: string, The videoLicense parameter filters search results to only include videos with a particular license. YouTube lets video uploaders choose to attach either the Creative Commons license or the standard YouTube license to each of their videos. If you specify a value for this parameter, you must also set the type parameter&#x27;s value to video.
170 Allowed values
171 any - Return all videos, regardless of which license they have, that match the query parameters.
172 creativeCommon - Only return videos that have a Creative Commons license. Users can reuse videos with this license in other videos that they create. Learn more.
173 youtube - Only return videos that have the standard YouTube license.
174 videoSyndicated: string, The videoSyndicated parameter lets you to restrict a search to only videos that can be played outside youtube.com. If you specify a value for this parameter, you must also set the type parameter&#x27;s value to video.
175 Allowed values
176 any - Return all videos, syndicated or not.
177 true - Only retrieve syndicated videos.
178 videoType: string, The videoType parameter lets you restrict a search to a particular type of videos. If you specify a value for this parameter, you must also set the type parameter&#x27;s value to video.
179 Allowed values
180 any - Return all videos.
181 episode - Only retrieve episodes of shows.
182 movie - Only retrieve movies.
John Asmuth614db982014-04-24 15:46:26 -0400[diff] [blame]183
184Returns:
185 An object of the form:
186
187 {
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame]188 &quot;etag&quot;: &quot;A String&quot;, # Etag of this resource.
189 &quot;eventId&quot;: &quot;A String&quot;, # Serialized EventId of the request which produced this response.
190 &quot;items&quot;: [ # A list of results that match the search criteria.
John Asmuth614db982014-04-24 15:46:26 -0400[diff] [blame]191 { # A search result contains information about a YouTube video, channel, or playlist that matches the search parameters specified in an API request. While a search result points to a uniquely identifiable resource, like a video, it does not have its own persistent data.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame]192 &quot;etag&quot;: &quot;A String&quot;, # Etag of this resource.
193 &quot;id&quot;: { # A resource id is a generic reference that points to another YouTube resource. # The id object contains information that can be used to uniquely identify the resource that matches the search request.
194 &quot;channelId&quot;: &quot;A String&quot;, # The ID that YouTube uses to uniquely identify the referred resource, if that resource is a channel. This property is only present if the resourceId.kind value is youtube#channel.
195 &quot;kind&quot;: &quot;A String&quot;, # The type of the API resource.
196 &quot;playlistId&quot;: &quot;A String&quot;, # The ID that YouTube uses to uniquely identify the referred resource, if that resource is a playlist. This property is only present if the resourceId.kind value is youtube#playlist.
197 &quot;videoId&quot;: &quot;A String&quot;, # The ID that YouTube uses to uniquely identify the referred resource, if that resource is a video. This property is only present if the resourceId.kind value is youtube#video.
198 },
199 &quot;kind&quot;: &quot;youtube#searchResult&quot;, # Identifies what kind of resource this is. Value: the fixed string &quot;youtube#searchResult&quot;.
200 &quot;snippet&quot;: { # Basic details about a search result, including title, description and thumbnails of the item referenced by the search result. # The snippet object contains basic details about a search result, such as its title or description. For example, if the search result is a video, then the title will be the video&#x27;s title and the description will be the video&#x27;s description.
201 &quot;channelId&quot;: &quot;A String&quot;, # The value that YouTube uses to uniquely identify the channel that published the resource that the search result identifies.
202 &quot;channelTitle&quot;: &quot;A String&quot;, # The title of the channel that published the resource that the search result identifies.
203 &quot;description&quot;: &quot;A String&quot;, # A description of the search result.
204 &quot;liveBroadcastContent&quot;: &quot;A String&quot;, # It indicates if the resource (video or channel) has upcoming/active live broadcast content. Or it&#x27;s &quot;none&quot; if there is not any upcoming/active live broadcasts.
205 &quot;publishedAt&quot;: &quot;A String&quot;, # The creation date and time of the resource that the search result identifies. The value is specified in ISO 8601 (YYYY-MM-DDThh:mm:ss.sZ) format.
206 &quot;thumbnails&quot;: { # Internal representation of thumbnails for a YouTube resource. # A map of thumbnail images associated with the search result. For each object in the map, the key is the name of the thumbnail image, and the value is an object that contains other information about the thumbnail.
207 &quot;default&quot;: { # A thumbnail is an image representing a YouTube resource. # The default image for this resource.
208 &quot;height&quot;: 42, # (Optional) Height of the thumbnail image.
209 &quot;url&quot;: &quot;A String&quot;, # The thumbnail image&#x27;s URL.
210 &quot;width&quot;: 42, # (Optional) Width of the thumbnail image.
John Asmuth614db982014-04-24 15:46:26 -0400[diff] [blame]211 },
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame]212 &quot;high&quot;: { # A thumbnail is an image representing a YouTube resource. # The high quality image for this resource.
213 &quot;height&quot;: 42, # (Optional) Height of the thumbnail image.
214 &quot;url&quot;: &quot;A String&quot;, # The thumbnail image&#x27;s URL.
215 &quot;width&quot;: 42, # (Optional) Width of the thumbnail image.
John Asmuth614db982014-04-24 15:46:26 -0400[diff] [blame]216 },
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame]217 &quot;maxres&quot;: { # A thumbnail is an image representing a YouTube resource. # The maximum resolution quality image for this resource.
218 &quot;height&quot;: 42, # (Optional) Height of the thumbnail image.
219 &quot;url&quot;: &quot;A String&quot;, # The thumbnail image&#x27;s URL.
220 &quot;width&quot;: 42, # (Optional) Width of the thumbnail image.
John Asmuth614db982014-04-24 15:46:26 -0400[diff] [blame]221 },
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame]222 &quot;medium&quot;: { # A thumbnail is an image representing a YouTube resource. # The medium quality image for this resource.
223 &quot;height&quot;: 42, # (Optional) Height of the thumbnail image.
224 &quot;url&quot;: &quot;A String&quot;, # The thumbnail image&#x27;s URL.
225 &quot;width&quot;: 42, # (Optional) Width of the thumbnail image.
John Asmuth614db982014-04-24 15:46:26 -0400[diff] [blame]226 },
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame]227 &quot;standard&quot;: { # A thumbnail is an image representing a YouTube resource. # The standard quality image for this resource.
228 &quot;height&quot;: 42, # (Optional) Height of the thumbnail image.
229 &quot;url&quot;: &quot;A String&quot;, # The thumbnail image&#x27;s URL.
230 &quot;width&quot;: 42, # (Optional) Width of the thumbnail image.
John Asmuth614db982014-04-24 15:46:26 -0400[diff] [blame]231 },
232 },
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame]233 &quot;title&quot;: &quot;A String&quot;, # The title of the search result.
John Asmuth614db982014-04-24 15:46:26 -0400[diff] [blame]234 },
235 },
236 ],
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame]237 &quot;kind&quot;: &quot;youtube#searchListResponse&quot;, # Identifies what kind of resource this is. Value: the fixed string &quot;youtube#searchListResponse&quot;.
238 &quot;nextPageToken&quot;: &quot;A String&quot;, # The token that can be used as the value of the pageToken parameter to retrieve the next page in the result set.
239 &quot;pageInfo&quot;: { # Paging details for lists of resources, including total number of items available and number of resources returned in a single page.
240 &quot;resultsPerPage&quot;: 42, # The number of results included in the API response.
241 &quot;totalResults&quot;: 42, # The total number of results in the result set.
John Asmuth614db982014-04-24 15:46:26 -0400[diff] [blame]242 },
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame]243 &quot;prevPageToken&quot;: &quot;A String&quot;, # The token that can be used as the value of the pageToken parameter to retrieve the previous page in the result set.
244 &quot;regionCode&quot;: &quot;A String&quot;,
245 &quot;tokenPagination&quot;: { # Stub token pagination template to suppress results.
John Asmuth614db982014-04-24 15:46:26 -0400[diff] [blame]246 },
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame]247 &quot;visitorId&quot;: &quot;A String&quot;, # The visitorId identifies the visitor.
John Asmuth614db982014-04-24 15:46:26 -0400[diff] [blame]248 }</pre>
249</div>
250
251<div class="method">
252 <code class="details" id="list_next">list_next(previous_request, previous_response)</code>
253 <pre>Retrieves the next page of results.
254
255Args:
256 previous_request: The request for the previous page. (required)
257 previous_response: The response from the request for the previous page. (required)
258
259Returns:
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame]260 A request object that you can call &#x27;execute()&#x27; on to request the next
John Asmuth614db982014-04-24 15:46:26 -0400[diff] [blame]261 page. Returns None if there are no more items in the collection.
262 </pre>
263</div>
264
265</body></html>