Reference
youte.collector.Youte
__init__(api_key)
Requires an API key to instantiate.
get_channel_metadata(ids, part=None, max_results=50, include_meta=True, **kwargs)
Retrieve full metadata for channels using their IDs. Currently, do not work with usernames. Channel IDs can be obtained in API responses to other methods such as search() or get_video_metadata().
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
ids |
list[str]
|
A list of one or multiple channel IDs. If a single ID is specified, it should be wrapped in a list as well, e.g. ["video_id"]. |
required |
part |
list[str]
|
A list of video resource properties that the API response will include. If nothing is passed, the parts used are [ "snippet", "statistics", "topicDetails", "status", "contentDetails", "brandingSettings", "contentOwnerDetails"] |
None
|
max_results |
int
|
Maximum number of results returned in one page of response. Accepted value is between 0 and 50. |
50
|
include_meta |
bool
|
Include |
True
|
**kwargs |
Any metadata to be included in |
{}
|
Yields:
| Type | Description |
|---|---|
Iterator[APIResponse]
|
Dict mappings containing API response. |
Raises:
| Type | Description |
|---|---|
TypeError
|
If the value passed to ids is not a list, a TypeError will be raised. |
get_comment_threads(video_ids=None, related_channel_ids=None, comment_ids=None, order='time', search_terms=None, text_format='html', max_results=100, include_meta=True, **kwargs)
Retrieve comment threads (top-level comments) by their IDs, by video IDs, or by channel IDs. If video_ids are specified, retrieve all comment threads for those videos. If related_channel_ids are specified, retrieve all comments associated with those channels, including comments about the channels' videos. If comment_ids are specified, retrieve metadata of those comments. Exactly ONE of these parameters should be specified in one method call.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
video_ids |
list[str]
|
list of video IDs. If a single ID, wrap in list, too, e.g. ["video_id"]. If this parameter is specified, the call will retrieve all comment threads on the specified videos. Nothing should be passed for related_channel_ids or comment_ids if this parameter is specified. A warning will be displayed if a video has disabled comments. |
None
|
related_channel_ids |
list[str]
|
list of channel IDs. If a single ID, wrap in list, too, e.g. ["channel_id"]. If this parameter is specified, retrieve all comment threads associated with these channels, including comments about the channels or the channels' videos. Nothing should be passed for video_ids or comment_ids if this parameter is specified. |
None
|
comment_ids |
list[str]
|
list of comment IDs. If a single ID, wrap in list, too, e.g. ["cmt_id"]. If this parameter is specified, retrieve metadata for all specified comment IDs. Nothing should be passed for video_ids or comment_ids if this parameter is specified. |
None
|
order |
time, relevance
|
How comment threads are sorted. |
'time'
|
search_terms |
str
|
Only retrieve comment threads matching search terms. |
None
|
text_format |
html, plainText
|
Specify the format of returned data. |
'html'
|
max_results |
int
|
Maximum number of results returned in one page of response. Accepted value is between 0 and 100. Only applicable when retrieving comment threads using video or channel IDs. When comment IDs are provided, this argument is not used. |
100
|
include_meta |
bool
|
Include |
True
|
**kwargs |
Any metadata to be included in |
{}
|
Yields:
| Type | Description |
|---|---|
Iterator[APIResponse]
|
Dict mappings containing API response. |
Raises:
| Type | Description |
|---|---|
ValueError
|
If more than one of these parameters - video_ids, related_channel_ids, comment_ids - are specified, a ValueError will be raised. |
get_most_popular(region_code='us', video_category_id=None, max_results=100, part=None, include_meta=True, **kwargs)
Retrieve the most popular videos for a region and video category.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
region_code |
str
|
ISO 3166-1 alpha-2 country code for specifying a region. |
'us'
|
video_category_id |
str
|
The video category ID for which the most popular videos should be retrieved. |
None
|
max_results |
int
|
Maximum number of results to be retrieved per page. |
100
|
part |
list[str]
|
A list of video resource properties that the API response will include. If noting is passed, the parts used are [ "snippet", "statistics", "topicDetails", "status", "contentDetails", "recordingDetails", "id"] |
None
|
include_meta |
bool
|
Include |
True
|
**kwargs |
Any metadata to be included in |
{}
|
Yields:
| Type | Description |
|---|---|
Iterator[APIResponse]
|
Dict mappings containing API response. |
get_related_videos(video_ids, region=None, relevance_language=None, safe_search='none', max_results=50, max_pages_retrieved=None, include_meta=True, **kwargs)
Retrieve videos related to a specified video. Can iterate over a list of video IDs and retrieve related videos for each of the specified ID.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
video_ids |
list[str]
|
A list of video IDs for each of which to retrieve related videos. The function will iterate through each ID and get all related videos for that ID before moving on to the next. If a single ID is passed, wrap that in a list, too. |
required |
region |
str
|
An ISO 3166-1 alpha-2 country code to specify the region that videos can be viewed in. |
None
|
relevance_language |
str
|
An ISO 639-1 two-letter language code to filter results most relevant to a language. Results in other languages will still be included if they are highly relevant to the video. |
None
|
safe_search |
none, moderate, strict
|
Include restricted content or not. |
'none'
|
max_results |
int
|
Maximum number of items that should be returned in one page of the result. Accepted values are between 0 and 50, inclusive. |
50
|
max_pages_retrieved |
int
|
Limit the number of result pages returned PER video ID. Equals the maximum number of calls made to the API PER video ID. So, if this parameter is set to 2 and a list of 3 IDs is specified for video_ids, that makes 6 calls to the API in total. |
None
|
include_meta |
bool
|
Include |
True
|
**kwargs |
Any metadata to be included in |
{}
|
Yields:
| Type | Description |
|---|---|
Iterator[APIResponse]
|
Dict mappings containing API response. |
get_thread_replies(thread_ids, text_format='html', max_results=100, include_meta=True, **kwargs)
Retrieve replies to comment threads. Currently, the API only supports getting replies to top-level comments. Replies to replies are not supported as of this version.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
thread_ids |
list[str]
|
list of comment thread IDs. If a single ID, wrap in list, too, e.g. ["thread_id"]. |
required |
text_format |
html, plainText
|
Specify the format of returned data. |
'html'
|
max_results |
int
|
Maximum number of results returned in one page of response. Accepted value is between 0 and 100. |
100
|
include_meta |
bool
|
Include |
True
|
**kwargs |
Any metadata to be included in |
{}
|
Yields:
| Type | Description |
|---|---|
Iterator[APIResponse]
|
Dict mappings containing API response. |
Raises:
| Type | Description |
|---|---|
TypeError
|
If thread_ids is not a list, a TypeError will be raised. |
get_video_metadata(ids, part=None, max_results=50, include_meta=True, **kwargs)
Retrieve full metadata for videos using their IDs.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
ids |
list[str]
|
A list of one or multiple video IDs. If a single ID is specified, it should be wrapped in a list as well, e.g. ["video_id"]. |
required |
part |
list[str]
|
A list of video resource properties that the API response will include. If not, these are the parts used: ["snippet", "statistics", "topicDetails", "status", "contentDetails", "recordingDetails", "id"]. |
None
|
max_results |
int
|
Maximum number of results returned in one page of response. Accepted value is between 0 and 50. |
50
|
include_meta |
bool
|
Include |
True
|
**kwargs |
Any metadata to be included in |
{}
|
Yields:
| Type | Description |
|---|---|
Iterator[APIResponse]
|
Dict mappings containing API response. |
Raises:
| Type | Description |
|---|---|
TypeError
|
If the value passed to ids is not a list, a TypeError will be raised. |
search(query, type_='video', start_time=None, end_time=None, order='relevance', safe_search='none', language=None, region=None, video_duration='any', channel_type='any', video_type='any', caption='any', video_definition='any', video_embeddable='any', video_license='any', video_dimension='any', location=None, location_radius=None, max_result=50, max_pages_retrieved=None, include_meta=True, **kwargs)
Do a YouTube search.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
query |
str
|
The term to search for. You can also use the Boolean NOT (-) and OR (|) operators to exclude videos or to find videos matching one of several search terms. |
required |
type_ |
str | list[str]
|
Type of resources to retrieve. Can be one or a list containing one or more of "channel", "video", "playlist" |
'video'
|
start_time |
str
|
Retrieve resources after this date. Has to be in YYYY-MM-DD format |
None
|
end_time |
str
|
Retrieve resources before this date. Has to be in YYYY-MM-DD format |
None
|
order |
date, rating, relevance, title, videoCount, viewCount
|
Sort results. - "date" sorts results in reverse chronological order. - "rating" sorts results from highest to lowest ratings. - "relevance" sorts results based on their relevance to the search query. - "title" sorts results alphabetically by title. - "videoCount" sorts channels in descending order of their number of videos. - "viewCount" sorts videos in descending order of views. For live broadcasts, videos are sorted by number of concurrent viewers while broadcasts are live. |
'relevance'
|
safe_search |
moderate, none, strict
|
Include restricted content or not. |
'none'
|
language |
str
|
Return results most relevant to a language. Accepted values are ISO 639-1 two-letter language code. |
None
|
region |
str
|
Returns results that can be viewed in the specified country. Use ISO 3166-1 alpha-2 country code. |
None
|
video_duration |
any, long, medium, short
|
Filter results by video duration. type_ has to be "video". |
'any'
|
channel_type |
any, show
|
Filter results by channel type. |
'any'
|
video_type |
any, episode, movie
|
Filter results by video type. |
'any'
|
caption |
any, closedCaption, none
|
Filter results based on whether they have captions. |
'any'
|
video_definition |
any, high, standard
|
Filter results by HD or SD videos. |
'any'
|
video_embeddable |
any, true
|
Restrict to only videos that can be embedded into a webpage. |
'any'
|
video_license |
any, creativeCommon, youtube
|
Only include videos with a particular license. |
'any'
|
video_dimension |
2d, 3d, any
|
Only retrieve 2D or 3D videos. |
'any'
|
location |
tuple
|
Along with location_radius, defines a circular geographic area and restricts a search to videos that specify, in their metadata, a geographic location within that area. Both location and location_radius have to be specified. Input is a tuple of latitude/longitude coordinates, e.g. (37.42307,-122.08427). |
None
|
location_radius |
str
|
Along with location, defines a circular geographic area and restricts a search to videos that specify, in their metadata, a geographic location within that area. The parameter value must be a floating point number followed by a measurement unit. Valid measurement units are m, km, ft, and mi. Values larger than 1000 km are not supported. |
None
|
max_result |
int
|
Maximum number of items that should be returned in one page of the result. Accepted values are between 0 and 50, inclusive. |
50
|
max_pages_retrieved |
int
|
Limit the number of result pages returned. Equals the maximum number of calls made to the API. |
None
|
include_meta |
bool
|
Include |
True
|
**kwargs |
Any metadata to be included in |
{}
|
Yields:
| Type | Description |
|---|---|
Iterator[APIResponse]
|
Dict mappings containing API response. |
youte.parser
parse_channel(data)
Parse a single page of results from Youte.get_channel_metadata() into a list of Channel objects. These Channel objects are like dictionaries with keys representing channel attributes.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
data |
dict
|
A single dictionary returned by Youte.get_channel_metadata() |
required |
Returns:
| Type | Description |
|---|---|
Channels
|
A Channels object containing a list of Channel objects. |
parse_channels(data)
Parse an iterable of pages of results from Youte.get_channel_metadata() into a list of Channel objects. These Channel objects are like dictionaries with keys representing channel attributes.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
data |
Iterable[dict]
|
A list or iterator of dictionaries returned by Youte.get_channel_metadata() |
required |
Returns:
| Type | Description |
|---|---|
Channels
|
A Channels object containing a list of Channel objects. |
parse_comment(data)
Parse a single page of results from Youte.get_comment_thread() or Youte.get_thread_replies() into a list of Comments objects. These Comment objects are like dictionaries with keys representing comment attributes.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
data |
dict
|
A single dictionary returned by Youte.get_comment_thread() or Youte.get_thread_replies() |
required |
Returns:
| Type | Description |
|---|---|
Comments
|
A Comments object containing a list of Comment objects. |
parse_comments(data)
Parse multiple pages of results from Youte.get_comment_thread() or Youte.get_thread_replies() into a list of Comments objects. These Comment objects are like dictionaries with keys representing comment attributes.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
data |
dict
|
A list or iterator of dictionaries returned by Youte.get_comment_thread() or Youte.get_thread_replies() |
required |
Returns:
| Type | Description |
|---|---|
Comments
|
A Comments object containing a list of Comment objects. |
parse_search(data)
Parse a single page of search results from Youte.search() into a list of Search objects. These Search objects are like dictionaries with keys representing attributes of the search results.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
data |
dict
|
A single dictionary as returned by Youte.search() |
required |
Returns:
| Type | Description |
|---|---|
Searches
|
A list of Search objects. |
parse_searches(data)
Parse a list or iterable of result pages from Youte.search() into a list of Search objects. Works very similarly to parse_search except over a list of search results.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
data |
Iterable[dict]
|
A list or iterator of dictionaries returned by Youte.search() |
required |
Returns:
| Type | Description |
|---|---|
Searches
|
A list of Search objects. |
parse_video(data)
Parse a single page of results from Youte.get_video_metadata() or Youte.get_most_popular() into a list of Video objects. These Video objects are like dictionaries with keys representing video attributes.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
data |
dict
|
A single dictionary returned by Youte.get_video_metadata() or Youte.get_most_popular() |
required |
Returns:
| Type | Description |
|---|---|
Videos
|
A Videos object containing a list of Video objects. |
parse_videos(data)
Parse a list or iterable of result pages from Youte.get_video_metadata() or Youte.get_most_popular() into a list of Video objects. These Video objects are like dictionaries with keys representing video attributes.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
data |
Iterable[dict]
|
A list or iterator of dictionaries returned by Youte.get_video_metadata() or Youte.get_most_popular() |
required |
Returns:
| Type | Description |
|---|---|
Videos
|
A Videos object containing a list of Video objects. |