class ytapi_kit._data.DataClient(session, base_url: str = 'https://www.googleapis.com/youtube/v3')[source]

Bases: object

High-level wrapper around the YouTube Data API v3.

The client offers:

Parameters:

  • session (google.auth.transport.requests.AuthorizedSession) – Pre-authenticated HTTP session. The client never refreshes or mutates the credentials object; bring your own refresh logic if needed.

  • base_url (str, optional) – API root to use instead of the default "https://youtube.googleapis.com/youtube/v3/".

session

The underlying HTTP session. Closed automatically when the client is used as a context manager and the session was created inside the client.

Type:

AuthorizedSession

base_url

Root prefix for every endpoint path.

Type:

str

Core list wrappers

list_activities, list_captions, list_channels, list_channel_sections, list_comments, list_comment_threads, list_i18n_languages, list_i18n_regions, list_members, list_membership_levels, list_playlist_images, list_playlist_items, list_playlists, list_search, list_subscriptions, list_video_abuse_report_reasons, list_video_categories, list_videos.

High-level helpers

channel_playlists, playlist_videos, channel_videos, video_metadata.

Raises:
google.auth.exceptions.TransportError:

Propagated from the underlying session if the network fails.

ytapi_kit.RateLimitError:

Raised when the API returns 429 Too Many Requests or a quota error; see ytapi_kit._errors.raise_for_status().

ValueError, TypeError:

Argument-validation errors surfaced verbatim from individual endpoint helpers.

Examples:

dc = DataClient(AuthorizedSession(creds)) playlists = dc.channel_playlists(mine=True) playlists[[“id”, “snippet.title”]].head()

channel_playlists(part: str | Sequence[str] = 'contentDetails', mine: bool | None = None, channel_id: str | None = None) → DataFrame[source]

Return all playlists owned by a channel.

This helper calls playlists.list() until every page has been retrieved and concatenates the results into a single DataFrame.

Parameters:

  • part (str | Sequence[str]) – Required. One or more of: - “contentDetails” - “id” - “localizations” - “player” - “snippet” - “status”

  • channel_id (str | None) – Channel whose playlists should be returned.

  • mine (bool | None) – True to fetch playlists for the authenticated user instead of specifying channel_id.

  • supplied. (**Exactly one** of channel_id or mine must be)

Returns:

All playlists owned by the channel.

Return type:

pandas.DataFrame

Raises:

  • ValueError – If both or neither of channel_id and mine are supplied.

  • TypeError – If a parameter has an invalid type.

channel_videos(mine: bool | None = None, channel_id: str | None = None) → DataFrame[source]

Return all videos contained in a channel.

NOTE: A bug has persisted for several years, where not all channel videos are returned solely by querying videos in the “uploads” playlist. For this reason, this function lists ALL playlists in a channel (including the “uploads” playlist), and then lists videos in each playlist and aggregates them into a single DataFrame.

Parameters:

  • channel_id (str | None) – ID of channel whose playlists should be returned.

  • mine (bool | None) –

    True to fetch playlists for the authenticated user instead of specifying channel_id.

    Exactly one of channel_id or mine must be supplied.

Returns:

All videos in channel.

Return type:

pandas.DataFrame

Raises:

TypeError – If a parameter has an invalid type.

list_activities(*, channel_id: str | None = None, mine: bool | None = None, part: str | Sequence[str] = ('contentDetails', 'snippet'), published_after: datetime | date | str | None = None, published_before: datetime | date | str | None = None, region_code: str | None = None, page_token: str | None = None, max_results: int | None = 50) → tuple[DataFrame, str | None][source]

Wrapper for the activities.list endpoint.

Parameters:

  • channel_id (str | None) – ID of a specific channel. Exactly one of channel_id or mine must be supplied.

  • mine (bool | None) – Set to True to fetch activities for the authenticated user’s own channel.

  • part (str | Sequence[str]) – Required. One or more of: - "contentDetails" - "id" - "snippet"

  • published_after (datetime | date | str | None) – Earliest date/time (inclusive) the activity occurred.

  • published_before (datetime | date | str | None) – Latest date/time (exclusive) the activity occurred.

  • region_code (str | None) – Two-letter ISO 3166-1 alpha-2 region code used to filter results.

  • page_token (str | None) – Token that identifies the results page to return.

  • max_results (int | None) – Maximum items per page (1–50). Larger result sets require pagination via page_token.

Returns:

  • DataFrame containing the activities.

  • nextPageToken if more data are available, else None.

Return type:

tuple[pandas.DataFrame, str | None]

Raises:

ValueError – If both or neither of channel_id and mine are supplied.

References

https://developers.google.com/youtube/v3/docs/activities/list

list_captions(*, part: str | Sequence[str] = ('id', 'snippet'), video_id: str, caption_id: str | None = None, on_behalf_of_content_owner: str | None = None) → DataFrame[source]

Wrapper for the captions.list endpoint.

Parameters:

  • part (str | Sequence[str]) –

    Required. Set to one or more of the following values:

    • ”id”

    • ”snippet

  • video_id (str) – Required. ID of specific video

  • caption_id (str | None) – ID of specific caption resource to be retrieved

  • on_behalf_of_content_owner (str | None) – ID of content owner

Returns:

Dataframe containing the captions.

Return type:

pandas.Dataframe

Raises:

  • ValueError – If part is not an allowed value.

  • TypeError – If any arguments passed are invalid.

References

https://developers.google.com/youtube/v3/docs/captions/list

list_channel_sections(*, part: str | Sequence[str] = ('contentDetails', 'snippet'), channel_id: str | None = None, channel_section_id: str | None = None, mine: bool | None = None, on_behalf_of_content_owner: str | None = None) → DataFrame[source]

Wrapper for the channelSections.list endpoint.

Parameters:

  • part (str | Sequence[str]) –

    Required. Set to one or more of the following values:

    • ”contentDetails”

    • ”id”

    • ”snippet”

  • channel_id (str | None) – Required. ID of specific channel. Exactly one of channel_id , channel_section_id, or mine must be supplied.

  • channel_section_id (str | None) – ID of specific channelSection resource.

  • mine (bool | None) – Set to True to fetch channels owned by the user.

  • on_behalf_of_content_owner (str | None) – ID of content owner

Returns:

  • DataFrame containing the channel sections.

Return type:

pandas.DataFrame

Raises:

ValueError – If not exactly one of channel_id, channel_section_id, or mine are supplied.

References

https://developers.google.com/youtube/v3/docs/channels/list

list_channels(*, part: str | Sequence[str] = ('contentDetails', 'snippet'), for_handle: str | None = None, for_username: str | None = None, channel_id: str | None = None, managed_by_me: bool | None = None, mine: bool | None = None, hl: str | None = None, max_results: int | None = None, on_behalf_of_content_owner: str | None = None, page_token: str | None = None) → tuple[DataFrame, str | None][source]

Wrapper for the channels.list endpoint.

Parameters:

  • part (str | Sequence[str]) –

    Required. Set to one or more of the following values:

    • ”auditDetails”

    • ”brandingSettings”

    • ”contentDetails”

    • ”contentOwnerDetails”

    • ”id”

    • ”localizations”

    • ”snippet”

    • ”statistics”

    • ”status”

    • ”topicDetails”

  • for_handle (str | None) – Handle of specific channel. Exactly one of for_handle , for_username, id, managed_by_me, or mine must be supplied.

  • for_username (str | None) – Username of specific channel.

  • channel_id (str | None) – ID of specific channel.

  • managed_by_me (bool | None) – Set to True to fetch channels managed by the user.

  • mine (bool | None) – Set to True to fetch channels owned by the user.

  • hl (str | None) – A specified language that the YouTube website supports.

  • max_results (int | None) – Maximum items per page (1–50). Larger result sets require pagination via page_token.

  • on_behalf_of_content_owner (str | None) – ID of content owner

  • page_token (str | None) – Token that identifies the results page to return.

Returns:

  • DataFrame containing the activities.

  • nextPageToken if more data are available, else None.

Return type:

tuple[pandas.DataFrame, str | None]

Raises:

ValueError – If both or neither of channel_id and mine are supplied.

References

https://developers.google.com/youtube/v3/docs/channels/list

list_comment_threads(*, part: str | Sequence[str] = 'snippet', all_threads_related_to_channel_id: str | None = None, comment_thread_id: str | None = None, video_id: str | None = None, max_results: int | None = None, moderation_status: str | None = None, order: str | None = None, page_token: str | None = None, search_terms: str | None = None, text_format: str | None = None) → tuple[DataFrame, str | None][source]

Wrapper for the commentThreads.list endpoint.

Parameters:

  • part (str | Sequence[str]) – Required. One or more of: - “id” - “replies” - “snippet”

  • video_id (str | None) – Retrieve comment threads for the video identified by this ID.

  • comment_thread_id (str | Sequence[str] | None) – Comma-separated list of comment-thread IDs to retrieve.

  • all_threads_related_to_channel_id (str | None) –

    Retrieve threads for any video uploaded to the specified channel.

    Exactly one of video_id, id, or all_threads_related_to_channel_id must be supplied.

  • max_results (int | None) – Maximum items per page (1–100). Larger result sets require pagination via page_token.

  • moderation_status (str | None) – Filter threads by moderation status. Acceptable values are: - “heldForReview” - “likelySpam” - “published”

  • order (str | None) – Sort order of returned threads. Acceptable values are: - “time” - “relevance”

  • page_token (str | None) – Token that identifies the results page to return.

  • search_terms (str | None) – Restrict results to threads that contain the specified text.

  • text_format (str | None) – Output format for comment text. Acceptable values are: - “html” - “plainText”

Returns:

  • DataFrame containing the comment threads.

  • nextPageToken if more data are available, else None.

Return type:

tuple[pandas.DataFrame, str | None]

Raises:

  • ValueError – If not exactly one of video_id, id, or all_threads_related_to_channel_id is supplied.

  • TypeError – If an invalid type is supplied.

References

https://developers.google.com/youtube/v3/docs/commentThreads/list

list_comments(*, part: str | Sequence[str] = ('contentDetails', 'snippet'), comment_id: str | None = None, parent_id: str | None = None, max_results: int | None = None, page_token: str | None = None, text_format: str | None = None) → tuple[DataFrame, str | None][source]

Wrapper for the comments.list endpoint.

Parameters:

  • part (str | Sequence[str]) – Required. Set to one or more of the following values: - “id” - “snippet”

  • comment_id (str | None) – ID of specific comments. Exactly one of id or parent_id must be supplied.

  • parent_id (str | None) – ID of specific comments for which replies should be retrieved.

  • max_results (int | None) – Maximum items per page (1–50). Larger result sets require pagination via page_token.

  • page_token (str | None) – Token that identifies the results page to return.

  • text_format (str | None) – Format comments should be returned in. Acceptable values are: - “html” - “plainText”

Returns:

  • DataFrame containing the channel sections.

  • nextPageToken if more data are available, else None.

Return type:

tuple[pandas.DataFrame, str | None]

Raises:

  • ValueError – If not exactly one of id or parent_id are supplied.

  • TypeError – If an invalid type is supplied.

References

https://developers.google.com/youtube/v3/docs/comments/list

list_i18n_languages(hl: str | None = None) → DataFrame[source]

Wrapper for the i18nLanguages.list endpoint.

Parameters:

hl (str | None) – Language code (e.g. "en_US", "es_MX") used to localise the language names in the response.

Returns:

DataFrame containing the supported interface languages. Each row represents one language.

Return type:

pandas.DataFrame

Raises:

TypeError – If an invalid type is supplied.

References

https://developers.google.com/youtube/v3/docs/i18nLanguages/list

list_i18n_regions(hl: str | None = None) → DataFrame[source]

Wrapper for the i18nRegions.list endpoint.

Parameters:

hl (str | None) – Language code (e.g. "en_US", "es_MX") used to localise the language names in the response.

Returns:

DataFrame containing the supported YouTube regions (each row is an ISO 3166-1 alpha-2 country code and its human-readable name).

Return type:

pandas.DataFrame

Raises:

TypeError – If an invalid type is supplied.

References

https://developers.google.com/youtube/v3/docs/i18nRegions/list

list_members(*, mode: str | None = None, max_results: int | None = None, page_token: str | None = None, has_access_to_level: str | None = None, filter_by_member_channel_id: str | None = None) → tuple[DataFrame, str | None][source]

Wrapper for the members.list endpoint.

Parameters:

  • mode (str | None) – Determines which members are included. Acceptable values are: - “all_current” (default) - “updates”

  • max_results (int | None) – Maximum items per page (1–1000). Larger result sets require pagination via page_token.

  • page_token (str | None) – Token identifying the results page to return.

  • has_access_to_level (str | None) – Return only members who have at minimum access to the specified level ID.

  • filter_by_member_channel_id (str | Sequence[str] | None) – Channel IDs whose membership status should be checked (max 100 IDs)

Returns:

  • DataFrame containing the members.

  • nextPageToken if more data are available, else None.

Return type:

tuple[pandas.DataFrame, str | None]

Raises:

TypeError – If an argument has an invalid type.

References

https://developers.google.com/youtube/v3/docs/members/list

list_membership_levels(*, part: str | Sequence[str] = 'snippet') → DataFrame[source]

Wrapper for the membershipsLevels.list endpoint.

Parameters:

part (str | Sequence[str]) – Required. One or more of: - "id" - "snippet"

Returns:

DataFrame containing the channel’s membership levels.

Return type:

pandas.DataFrame

Raises:

TypeError – If an argument has an invalid type.

References

https://developers.google.com/youtube/v3/docs/membershipsLevels/list

list_playlist_images(*, part: str, playlist_image_id: str | None = None, playlist_id: str | None = None, max_results: int | None = None, on_behalf_of_content_owner: str | None = None, on_behalf_of_content_owner_channel: str | None = None, page_token: str | None = None) → tuple[DataFrame, str | None][source]

Wrapper for the playlistImages.list endpoint.

Parameters:

  • part (str | Sequence[str]) – Required.

  • playlist_image_id (str | Sequence[str] | None) – Playlist-image IDs to retrieve.

  • playlist_id (str | None) –

    Playlist id to retrieve images from.

    Exactly one of playlist_id or id must be supplied.

  • max_results (int | None) – Maximum items per page (0–50). Larger result sets require pagination via page_token.

  • on_behalf_of_content_owner (str | None) – ID of content owner

  • on_behalf_of_content_owner_channel (str | None) – ID of the channel to which a video is being added.

  • page_token (str | None) – Token that identifies the results page to return.

Returns:

  • DataFrame containing the playlist images.

  • nextPageToken if more data are available, else None.

Return type:

tuple[pandas.DataFrame, str | None]

Raises:

  • ValueError – If not exactly one of playlist_id or id is supplied.

  • TypeError – If an invalid type is supplied.

References

https://developers.google.com/youtube/v3/docs/playlistImages/list

list_playlist_items(*, part: str | Sequence[str] = 'snippet', playlist_item_id: str | Sequence[str] | None = None, playlist_id: str | None = None, max_results: int | None = None, on_behalf_of_content_owner: str | None = None, page_token: str | None = None, video_id: str | None = None) → tuple[DataFrame, str | None][source]

Wrapper for the playlistItems.list endpoint.

Parameters:

  • part (str | Sequence[str]) – Required. One or more of: - “contentDetails” - “id” - “snippet” - “status”

  • playlist_item_id (str | Sequence[str] | None) – ID of playlist item(s)

  • playlist_id (str | Sequence[str] | None) –

    ID of playlist(s)

    Exactly one of id or playlist_id must be supplied.

  • max_results (int | None) – Maximum items per page (0–50). Larger result sets require pagination via page_token.

  • on_behalf_of_content_owner (str | None) – ID of content owner

  • page_token (str | None) – Token that identifies the results page to return.

  • video_id (str | None) – ID of specific video to return playlist items of.

Returns:

  • DataFrame containing the playlist items.

  • nextPageToken if more data are available, else None.

Return type:

tuple[pandas.DataFrame, str | None]

Raises:

  • ValueError – If not exactly one of playlist_id or id is supplied.

  • TypeError – If an invalid type is supplied.

References

https://developers.google.com/youtube/v3/docs/playlistItems/list

list_playlists(*, part: str | Sequence[str] = 'snippet', channel_id: str | None = None, playlist_id: str | None = None, mine: bool | None = None, hl: str | None = None, max_results: int | None = None, on_behalf_of_content_owner: str | None = None, on_behalf_of_content_owner_channel: str | None = None, page_token: str | None = None) → tuple[DataFrame, str | None][source]

Wrapper for the playlists.list endpoint.

Parameters:

  • part (str | Sequence[str]) – Required. One or more of: - “contentDetails” - “id” - “localizations” - “player” - “snippet” - “status”

  • channel_id (str | None) – ID of channel to return playlist items of.

  • playlist_id (str | Sequence[str] | None) – Playlist IDs to retrieve.

  • mine (bool | None) –

    True to retrieve playlists owned by the authenticated user.

    Exactly one of channel_id, id, or mine must be supplied.

  • hl (str | None) – Language code (e.g. "en_US", "es_MX") used to localise the language names in the response.

  • max_results (int | None) – Maximum items per page (0–50). Larger result sets require pagination via page_token.

  • on_behalf_of_content_owner (str | None) – ID of content owner

  • on_behalf_of_content_owner_channel (str | None) – ID of the channel to which a video is being added.

  • page_token (str | None) – Token that identifies the results page to return.

Returns:

  • DataFrame containing the playlists.

  • nextPageToken if more data are available, else None.

Return type:

tuple[pandas.DataFrame, str | None]

Raises:

  • ValueError – If not exactly one of channel_id, playlist_id, or mine is supplied.

  • TypeError – If an invalid type is supplied.

References

https://developers.google.com/youtube/v3/docs/playlists/list

Wrapper for the search.list endpoint.

Parameters:

  • q (str | None) – Query term to search for. Use Boolean NOT (-) and OR (|) operators for advanced search

  • for_content_owner (bool | None) – Boolean to restrict search to only videos owned by content owner identified in on_behalf_of_content_owner parameter

  • for_developer (bool | None) – Boolean to restrict search to only videos uploaded by the developer’s application or website

  • for_mine (bool | None) –

    Boolean to restrict search to only videos uploaded by authenticated user

    Specify 0 or 1 of for_content_owner, for_developer, or for_mine

  • channel_id (str | None) – ID of channel to show results of.

  • channel_type (str | None) – Restrict search to a particular type of channel. Acceptable values are: - “any” - “show”

  • event_type (str | None) –

    Only include broadcasts of this type. Acceptable values are:

    • ”completed”,

    • ”live”,

    • ”upcoming”

    This parameter requires type=”video”

  • location (str | None) – Latitude/longitude of search centre (e.g. "37.42307,-122.08427"). Requires type=”video” and location_radius

  • location_radius (str | None) – Distance from location (e.g. "5km", "10000ft")

  • max_results (int | None) – Maximum items per page (0 – 50). Larger result sets require pagination via page_token

  • on_behalf_of_content_owner (str | None) – ID of content owner

  • order (str | None) –

    Sort order of results. Acceptable values are:

    • ”date”,

    • ”rating”,

    • ”relevance”,

    • ”title”,

    • ”videoCount”,

    • ”viewCount”

  • page_token (str | None) – Token that identifies the results page to return

  • published_after (datetime | date | str | None) – Earliest date/time (inclusive) the activity occurred.

  • published_before (datetime | date | str | None) – Latest date/time (exclusive) the activity occurred.

  • region_code (str | None) – Two-letter ISO 3166-1 alpha-2 region code used to filter results.

  • relevance_language (str | None) – Two-letter ISO 639-1 language code used to filter results.

  • safe_search (str | None) – Safe-search filtering. Acceptable values are: - “moderate”, - “none”, - “strict”

  • topic_id (str | None) – ID of topic to show results of.

  • type (str | None) – Resource type to return. Acceptable values are: - “video” - “channel” - “playlist”

  • video_caption (str | None) –

    Caption filter for video results. Acceptable values are: - “any”, - “closedCaption”, - “none”

    Requires type=”video”

  • video_category_id (str | None) – ID of video category to show results of. Requires type=”video”

  • video_definition (str | None) –

    Video definition to show results of. Acceptable values are: - “any”, - “high”, - “standard”

    Requires type=”video”

  • video_dimensions (str | None) –

    Video dimensions to show results of. Acceptable values are: - “2d”, - “3d”, - “any”

    Requires type=”video”

  • video_duration (str | None) –

    Video duration to show results of. Acceptable values are: - “any” - “long” - “medium” - “short”

    Requires type=”video”

  • video_embeddable (str | None) –

    Show videos that can only be embedded into a webpage. Acceptable values are: - “any” - “true”

    Requires type=”video”

  • video_license (str | None) –

    License of videos to show results of. Acceptable values are: - “any” - “creativeCommon” - “youtube”

    Requires type=”video”

  • video_paid_product_placement (str | None) –

    Show videos that have paid product placement. Acceptable values are: - “any” - “true”

    Requires type=”video”

  • video_syndicated (str | None) –

    Show videos that can be played outside YouTube.com. Acceptable values are: - “any” - “true”

    Requires type=”video”

  • video_type (str | None) –

    Type of video to show results of. Acceptable values are: - “any” - “episode” - “movie”

    Requires type=”video”

Returns:

  • DataFrame containing the search results.

  • nextPageToken if more data are available, else None.

Return type:

tuple[pandas.DataFrame, str | None]

Raises:

  • ValueError – If not 0 or 1 of for_content_owner, for_developer or for_mine passed

  • TypeError – If an argument has an invalid type.

References

https://developers.google.com/youtube/v3/docs/search/list

list_subscriptions(*, part: str | Sequence[str] = ('contentDetails', 'snippet'), channel_id: str | None = None, subscription_id: str | None = None, mine: bool | None = None, my_recent_subscribers: bool | None = None, my_subscribers: bool | None = None, for_channel_id: str | None = None, max_results: int | None = None, on_behalf_of_content_owner: str | None = None, on_behalf_of_content_owner_channel: str | None = None, order: str | None = None, page_token: str | None = None) → tuple[DataFrame, str] | None[source]

Wrapper for the subscriptions.list endpoint.

Parameters:

  • part (str | Sequence[str]) – Required. One or more of: - "contentDetails" - "id" - "snippet" - "subscriberSnippet"

  • channel_id (str | None) – ID of channel to get subscriptions for.

  • subscription_id (str | Sequence[str] | None) – ID of subscriptions to retrieve.

  • mine (bool | None) – True to list subscriptions of the authenticated user

  • my_recent_subscribers (bool | None) – True to list recent subscribers to the authenticated user

  • my_subscribers (bool | None) –

    True to list all subscribers to the authenticated user

    Exactly one of channel_id, id, mine, my_recent_subscribers, or my_subscribers must be supplied.

  • for_channel_id (str | None) – ID of channel to get subscriptions for.

  • max_results (int | None) – Maximum items per page (0 – 50). Larger result sets require pagination via page_token

  • on_behalf_of_content_owner (str | None) – ID of content owner

  • on_behalf_of_content_owner_channel (str | None) – ID of the channel to which a video is being added.

  • order (str | None) – Sort order of results. Acceptable values are: - “alphabetical”, - “relevance”, - “unread”

  • page_token (str | None) – Token that identifies the results page to return

Returns:

  • DataFrame containing the subscriptions.

  • nextPageToken if more data are available, else None.

Return type:

tuple[pandas.DataFrame, str | None]

Raises:

  • ValueError – If the “exactly one” filter rule is violated.

  • TypeError – If an argument has an invalid type.

References

https://developers.google.com/youtube/v3/docs/subscriptions/list

list_video_abuse_report_reasons(*, part: str | Sequence[str] = ('id', 'snippet'), hl: str | None = None) → DataFrame[source]

Wrapper for the videoAbuseReportReasons.list endpoint.

Parameters:

  • part (str | Sequence[str]) – Required. One or more of: - “id” - “snippet”

  • hl (str | None) – Language code (e.g. "en_US", "es_MX") used to localise the language names in the response.

Returns:

DataFrame containing the abuse-report reasons.

Return type:

pandas.DataFrame

Raises:

TypeError – If an argument has an invalid type.

References

https://developers.google.com/youtube/v3/docs/videoAbuseReportReasons/list

list_video_categories(*, video_category_id: str | None = None, region_code: str | None = None, hl: str | None = None) → DataFrame[source]

Wrapper for the videoCategories.list endpoint.

Parameters:

  • video_category_id (str | Sequence[str] | None) – Comma-separated list of video-category IDs to retrieve

  • region_code (str | None) –

    Two-letter ISO 3166-1 alpha-2 region code used to filter results.

    Exactly one of region_code or id must be supplied.

  • hl (str | None) – Language code (e.g. "en_US", "es_MX") used to localise the language names in the response.

Returns:

DataFrame containing the video categories.

Return type:

pandas.DataFrame

Raises:

  • ValueError – If both or neither of region_code and id are supplied.

  • TypeError – If an argument has an invalid type.

References

https://developers.google.com/youtube/v3/docs/videoCategories/list

list_videos(*, part: str | Sequence[str] = ('contentDetails', 'snippet'), chart: str | None = None, video_id: str | None = None, my_rating: str | None = None, hl: str | None = None, max_height: int | None = None, max_results: int | None = None, max_width: int | None = None, on_behalf_of_content_owner: str | None = None, page_token: str | None = None, region_code: str | None = None, video_category_id: str | None = None) → tuple[DataFrame, str | None][source]

Wrapper for the videos.list endpoint.

Parameters:

  • part (str | Sequence[str]) – Required. One or more of: - “contentDetails” - “fileDetails” - “id” - “liveStreamingDetails” - “localizations” - “paidProductPlacementDetails” - “player” - “processingDetails” - “recordingDetails” - “snippet” - “statistics” - “status” - “suggestions” - “topicDetails”

  • chart (str | None) – Retrieve the specified chart. Acceptable value: - “mostPopular”

  • video_id (str | Sequence[str] | None) – ID of videos to return

  • my_rating (str | None) –

    Filter to videos liked or disliked by the authenticated user. Acceptable values are: - “like” - “dislike”

    Exactly one of chart, id or my_rating must be supplied.

  • hl (str | None) – Language code (e.g. "en_US", "es_MX") used to localise the language names in the response.

  • max_height (int | None) – Maximum height of embedded player in the player.embedHtml property

  • max_results (int | None) – Maximum items per page (0 – 50). Larger result sets require pagination via page_token

  • max_width (int | None) – Maximum width of embedded player in the player.embedHtml property

  • on_behalf_of_content_owner (str | None) – ID of content owner

  • page_token (str | None) – Token that identifies the results page to return.:contentReference

  • region_code (str | None) – Two-letter ISO 3166-1 alpha-2 region code used to filter results.

  • video_category_id (str | None) – ID of video-category ID to return.

Returns:

  • DataFrame containing the videos.

  • nextPageToken if more data are available, else None.

Return type:

tuple[pandas.DataFrame, str | None]

Raises:

  • ValueError – If the “exactly one” filter rule is violated.

  • TypeError – If an argument has an invalid type.

References

https://developers.google.com/youtube/v3/docs/videos/list

playlist_videos(playlist_id: str, part: str = 'contentDetails') → DataFrame[source]

Return all videos contained in a playlist.

Internally pages through playlistItems.list() until every item is retrieved.

Parameters:

  • playlist_id (str) – Required. ID of the playlist to get videos from.

  • part (str | Sequence[str]) – Required. One or more of: - “id” - “snippet” - “contentDetails” - “status”

Returns:

All videos in playlist_id.

Return type:

pandas.DataFrame

Raises:

TypeError – If a parameter has an invalid type.

video_metadata(video_id: str | Sequence[str], part: str | Sequence[str] = ('snippet', 'contentDetails')) → DataFrame[source]

Return metadata for one or more videos.

Parameters:

  • video_id (str | Sequence[str]) – Required. ID of the video(s) to get metadata for.

  • part (str | Sequence[str]) – Required. Most relevant parts are: - “contentDetails” - “status” - “snippet”

Returns:

All videos in video_id.

Return type:

pandas.DataFrame

Raises:

TypeError – If a parameter has an invalid type.