def test_extract_error():
with pytest.raises(HTTPError) as exc_info:
# No API key will raise authorization error
query_endpoint("i18nLanguages", {})
exceptions = json.loads(exc_info.value.args[0])
assert exceptions[0][
"message"] == "The request is missing a valid API key."
assert exceptions[0]["reason"] == "forbidden"
def get_videos(key: str, parts: List[str], video_ids: List[str], localization_code: str = None,
max_height: int = None, max_width: int = None) -> dict:
""" Query the videos endpoint.
See https://developers.google.com/youtube/v3/docs/videos/list for complete documentation.
:param key: Required API key.
:param parts: ChannelSection resource properties that the API response will include.
:param video_ids: IDs of the videos to retrieve.
:param localization_code: BCP-47 code that uniquely identifies a language for localization.
:param max_width: Maximum width of the embedded player returned in the player.embedHtml property. 72 to 8192.
:param max_height: Maximum height of the embedded player returned in the player.embedHtml property. 72 to 8192.
:return: JSON object associated with the query endpoint. See documentation for details.
"""
param_dict = {
"key": key,
"part": ",".join(parts),
"id": ",".join(video_ids)}
if localization_code:
param_dict["hl"] = localization_code
if max_height:
# Value 0 is invalid so truthy value check is enough
param_dict["maxHeight"] = max(72, min(8192, max_height))
if max_width:
# Value 0 is invalid so truthy value check is enough
param_dict["maxWidth"] = max(72, min(8192, max_width))
return query_endpoint("videos", param_dict)
def get_comment_threads_in_video(key: str,
parts: List[str],
video_id: str,
max_results: int = 20,
order: str = "time",
page_token: str = None,
search_terms: str = None,
text_format: str = "html") -> dict:
""" Query the comment threads endpoint for comment threads in a specific video.
See https://developers.google.com/youtube/v3/docs/commentThreads/list for complete documentation.
:param key: Required API key.
:param parts: CommentThread resource properties that the API response will include.
:param video_id: The ID of the video to retrieve threads from.
:param max_results: Maximum items that should be returned in the result set. Values between 1 to 100, inclusive.
:param order: Whether the threads should be sorted by "time" or "relevance".
:param page_token: Identifies a specific page in the result set that should be returned.
:param search_terms: Limit the API response to only contain comments that contain the specified search terms.
:param text_format: Indicates whether the API should return comments formatted as "html" or as "plainText".
:return: JSON object associated with the query endpoint. See documentation for details.
"""
param_dict = {
"key": key,
"part": ",".join(parts),
"videoId": video_id,
"maxResults": max(1, min(100, max_results)),
"textFormat": text_format,
"order": order
}
if page_token:
param_dict["pageToken"] = page_token
if search_terms:
param_dict["searchTerms"] = search_terms
return query_endpoint("commentThreads", param_dict)
def get_playlists(key: str,
parts: List[str],
playlist_ids: List[str],
max_results: int = 5,
page_token: str = None,
localization_code: str = None) -> dict:
""" Query the playlists endpoint.
See https://developers.google.com/youtube/v3/docs/playlists/list for complete documentation.
:param key: Required API key.
:param parts: PlaylistItem resource properties that the API response will include.
:param playlist_ids: IDs of the playlists to retrieve.
:param max_results: Maximum items that should be returned in the result set. Values between 0 to 50, inclusive.
:param page_token: Identifies a specific page in the result set that should be returned.
:param localization_code: BCP-47 code that uniquely identifies a language for localization.
:return: JSON object associated with the query endpoint. See documentation for details.
"""
param_dict = {
"key": key,
"part": ",".join(parts),
"id": ",".join(playlist_ids),
"maxResults": max(0, min(50, max_results))
}
if page_token:
param_dict["pageToken"] = page_token
if localization_code:
param_dict["hl"] = localization_code
return query_endpoint("playlists", param_dict)
def get_playlist_items(key: str,
parts: List[str],
playlist_id: str,
max_results: int = 5,
page_token: str = None,
video_id: str = None) -> dict:
""" Query the playlist items endpoint for items in a specific playlist.
See https://developers.google.com/youtube/v3/docs/playlistItems/list for complete documentation.
:param key: Required API key.
:param parts: PlaylistItem resource properties that the API response will include.
:param playlist_id: ID of the playlist for which to retrieve playlist items.
:param max_results: Maximum items that should be returned in the result set. Values between 0 to 50, inclusive.
:param page_token: Identifies a specific page in the result set that should be returned.
:param video_id: Specifies that the query should return only the items that contain the specified video.
:return: JSON object associated with the query endpoint. See documentation for details.
"""
param_dict = {
"key": key,
"part": ",".join(parts),
"playlistId": ",".join(playlist_id),
"maxResults": max(0, min(50, max_results))
}
if page_token:
param_dict["pageToken"] = page_token
if video_id:
param_dict["videoId"] = video_id
return query_endpoint("playlistItems", param_dict)
def get_user_channel(key: str,
parts: List[str],
username: str,
max_results: int = 5,
page_token: str = None,
localization_code: str = None) -> dict:
""" Query the channels endpoint for a channel with a specific username.
See https://developers.google.com/youtube/v3/docs/channels/list for complete documentation.
:param key: Required API key.
:param parts: Channel resource properties that the API response will include.
:param username: Specifies a YouTube username, thereby requesting the channel associated with that username.
:param max_results: Maximum items that should be returned in the result set. Values between 0 to 50, inclusive.
:param page_token: Identifies a specific page in the result set that should be returned.
:param localization_code: BCP-47 code that uniquely identifies a language for localization.
:return: JSON object associated with the query endpoint. See documentation for details.
"""
param_dict = {
"key": key,
"part": ",".join(parts),
"maxResults": max(0, min(50, max_results)),
"forUsername": username
}
if page_token:
param_dict["pageToken"] = page_token
if localization_code:
param_dict["hl"] = localization_code
return query_endpoint("channels", param_dict)
def get_channel_subscriptions(key: str, parts: List[str], channel_id: str, to_channel_ids: List[str] = None,
max_results: int = 5, order: str = "relevance", page_token: str = None) -> dict:
""" Query the subscriptions endpoint for subscriptions from a certain channel.
See https://developers.google.com/youtube/v3/docs/subscriptions/list for complete documentation.
:param key: Required API key.
:param parts: PlaylistItem resource properties that the API response will include.
:param channel_id: ID of the channel to retrieve subscriptions from.
:param to_channel_ids: IDs of the subscribed channels. Acts as a filter.
:param max_results: Maximum items that should be returned in the result set. Values between 0 to 50, inclusive.
:param order: Whether the subscriptions should be sorted by "alphabetical", "relevance", or "unread".
:param page_token: Identifies a specific page in the result set that should be returned.
:return: JSON object associated with the query endpoint. See documentation for details.
"""
param_dict = {
"key": key,
"part": ",".join(parts),
"channelId": channel_id,
"maxResults": max(0, min(50, max_results)),
"order": order}
if to_channel_ids:
param_dict["forChannelIds"] = ",".join(to_channel_ids)
if page_token:
param_dict["pageToken"] = page_token
return query_endpoint("subscriptions", param_dict)
def get_comment_responses(key: str,
parts: List[str],
comment_id: str,
max_results: int = 20,
page_token: str = None,
text_format: str = "html") -> dict:
""" Query the comments endpoint for the responses to a comment.
See https://developers.google.com/youtube/v3/docs/comments/list for complete documentation.
:param key: Required API key.
:param parts: Comment resource properties that the API response will include.
:param comment_id: ID of the comment for which replies should be retrieved.
:param max_results: Maximum items that should be returned in the result set. Values between 1 to 100, inclusive.
:param page_token: Identifies a specific page in the result set that should be returned.
:param text_format: Indicates whether the API should return comments formatted as "html" or as "plainText".
:return: JSON object associated with the query endpoint. See documentation for details.
"""
param_dict = {
"key": key,
"part": ",".join(parts),
"parentId": comment_id,
"maxResults": max(1, min(100, max_results)),
"textFormat": text_format
}
if page_token:
param_dict["pageToken"] = page_token
return query_endpoint("comments", param_dict)
def get_languages(key: str, localization_code: str = None) -> dict:
""" Query the languages endpoint.
See https://developers.google.com/youtube/v3/docs/i18nLanguages/list for complete documentation.
:param key: Required API key.
:param localization_code: BCP-47 code that uniquely identifies a language for localization.
:return: JSON object associated with the query endpoint. See documentation for details.
"""
param_dict = {"key": key, "part": "snippet"}
if localization_code:
param_dict["hl"] = localization_code
return query_endpoint("i18nLanguages", param_dict)
def get_abuse_report_reasons(key: str,
parts: List[str],
localization_code: str = None) -> dict:
""" Query the video abuse report reasons endpoint.
See https://developers.google.com/youtube/v3/docs/videoAbuseReportReasons/list for complete documentation.
:param key: Required API key.
:param parts: VideoAbuseReportReason resource properties that the API response will include.
:param localization_code: BCP-47 code that uniquely identifies a language for localization.
:return: JSON object associated with the query endpoint. See documentation for details.
"""
param_dict = {"key": key, "part": ",".join(parts)}
if localization_code:
param_dict["hl"] = localization_code
return query_endpoint("videoAbuseReportReasons", param_dict)
def get_video_categories_in_region(key: str,
region_code: str,
localization_code: str = None) -> dict:
""" Query the video categories endpoint for video categories in a specific region.
See https://developers.google.com/youtube/v3/docs/videoCategories/list for complete documentation.
:param key: Required API key.
:param region_code: ISO 3166-1 alpha-2 code for the country to retrieve categories from.
:param localization_code: BCP-47 code that uniquely identifies a language for localization.
:return: JSON object associated with the query endpoint. See documentation for details.
"""
param_dict = {"key": key, "part": "snippet", "regionCode": region_code}
if localization_code:
param_dict["hl"] = localization_code
return query_endpoint("videoCategories", param_dict)
def get_video_categories(key: str,
category_ids: List[str],
localization_code: str = None) -> dict:
""" Query the video categories endpoint.
See https://developers.google.com/youtube/v3/docs/videoCategories/list for complete documentation.
:param key: Required API key.
:param category_ids: IDs for the resources that you are retrieving.
:param localization_code: BCP-47 code that uniquely identifies a language for localization.
:return: JSON object associated with the query endpoint. See documentation for details.
"""
param_dict = {"key": key, "part": "snippet", "id": ",".join(category_ids)}
if localization_code:
param_dict["hl"] = localization_code
return query_endpoint("videoCategories", param_dict)
def get_captions(key: str,
parts: List[str],
video_id: str,
caption_ids: List[str] = None) -> dict:
""" Query the captions endpoint for the captions in a video.
See https://developers.google.com/youtube/v3/docs/captions/list for complete documentation.
:param key: Required API key.
:param parts: Caption resource parts that the API response will include.
:param video_id: The YouTube video ID of the video for which the API should return caption tracks.
:param caption_ids: Each ID must identify a caption track associated with the specified video.
:return: JSON object associated with the query endpoint. See documentation for details.
"""
param_dict = {"key": key, "part": ",".join(parts), "videoId": video_id}
if caption_ids:
param_dict["id"] = ",".join(caption_ids)
return query_endpoint("captions", param_dict)
def get_comments(key: str,
parts: List[str],
comment_ids: List[str],
text_format: str = "html") -> dict:
""" Query the comments endpoint.
See https://developers.google.com/youtube/v3/docs/comments/list for complete documentation.
:param key: Required API key.
:param parts: Comment resource properties that the API response will include.
:param comment_ids: Comment IDs for the resources that are being retrieved.
:param text_format: Indicates whether the API should return comments formatted as "html" or as "plainText".
:return: Response object associated with the query_endpoint. See documentation for details.
"""
param_dict = {
"key": key,
"part": ",".join(parts),
"id": ",".join(comment_ids),
"textFormat": text_format
}
return query_endpoint("comments", param_dict)
def get_channel_sections(key: str,
parts: List[str],
channel_id: str,
localization_code: str = None) -> dict:
""" Query the channel sections endpoint for a specific channel.
See https://developers.google.com/youtube/v3/docs/channelSections/list for complete documentation.
:param key: Required API key.
:param parts: ChannelSection resource properties that the API response will include.
:param channel_id: IDs of the channel to retrieve the sections from.
:param localization_code: BCP-47 code that uniquely identifies a language for localization.
:return: JSON object associated with the query endpoint. See documentation for details.
"""
param_dict = {
"key": key,
"part": ",".join(parts),
"channelId": ",".join(channel_id)
}
if localization_code:
param_dict["hl"] = localization_code
return query_endpoint("channelSections", param_dict)
def get_popular_videos(key: str, parts: List[str], localization_code: str = None, max_results: int = 5,
max_height: int = None, max_width: int = None, page_token: str = None,
region_code: str = None, category_id: str = "0") -> dict:
""" Query the videos endpoint for the most popular videos in a category and/or region.
See https://developers.google.com/youtube/v3/docs/videos/list for complete documentation.
:param key: Required API key.
:param parts: ChannelSection resource properties that the API response will include.
:param localization_code: BCP-47 code that uniquely identifies a language for localization.
:param max_results: Maximum items that should be returned in the result set. Values between 1 to 50, inclusive.
:param max_width: Maximum width of the embedded player returned in the player.embedHtml property. 72 to 8192.
:param max_height: Maximum height of the embedded player returned in the player.embedHtml property. 72 to 8192.
:param page_token: Identifies a specific page in the result set that should be returned.
:param category_id: Video category for which the popular videos should be retrieved.
:param region_code: ISO 3166-1 alpha-2 code for the country to retrieve popular videos from.
:return: JSON object associated with the query endpoint. See documentation for details.
"""
param_dict = {
"key": key,
"part": ",".join(parts),
"chart": "mostPopular",
"maxResults": max(1, min(50, max_results)),
"videoCategoryId": category_id}
if localization_code:
param_dict["hl"] = localization_code
if max_height:
# Value 0 is invalid so truthy value check is enough
param_dict["maxHeight"] = max(72, min(8192, max_height))
if max_width:
# Value 0 is invalid so truthy value check is enough
param_dict["maxWidth"] = max(72, min(8192, max_width))
if page_token:
param_dict["pageToken"] = page_token
if region_code:
param_dict["regionCode"] = region_code
return query_endpoint("videos", param_dict)
def test_query_endpoint(api_key):
response_body = query_endpoint("i18nLanguages", {"key": api_key})
assert response_body is not None
assert response_body.get("kind") == "youtube#i18nLanguageListResponse"
assert response_body.get("etag") is not None
assert len(response_body.get("items")) > 0