Search Filters¶

class ayt_api.filters.ChannelTypeFilter(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]¶

Bases: Enum

Restrict a search to a particular type of channel (e.g. show).

any¶: Return all channels.

show¶: Only retrieve shows.

class ayt_api.filters.EventTypeFilter(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]¶

Bases: Enum

Restricts a search to broadcast events.

completed¶: Only include completed broadcasts.

live¶: Only include active broadcasts.

upcoming¶: Only include upcoming broadcasts.

class ayt_api.filters.OrderFilter(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]¶

Bases: Enum

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

date¶: Resources are sorted in reverse chronological order based on the date they were created.

rating¶: Resources are sorted from highest to lowest rating.

relevance¶: Resources are sorted based on their relevance to the search query. This is the default value for this parameter.

title¶: Resources are sorted alphabetically by title.

video_count¶: Channels will be sorted in descending order of their number of uploaded videos.

view_count¶: Resources will be sorted from highest to lowest number of views. For live broadcasts, videos are sorted by number of concurrent viewers while the broadcasts are ongoing.

class ayt_api.filters.SafeSearchFilter(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]¶

Bases: Enum

Whether the search results should include restricted content as well as standard content.

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.

none¶: YouTube will not filter the search result set.

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.

class ayt_api.filters.VideoCaptionFilter(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]¶

Bases: Enum

Show results based on whether videos have captions.

any¶: Do not filter results based on caption availability.

closed_caption¶: Only include videos that have captions.

none¶: Only include videos that do not have captions.

class ayt_api.filters.VideoDimensionFilter(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]¶

Bases: Enum

Restrict a search to only retrieve 2D or 3D videos.

_2d¶: Restrict search results to exclude 3D videos.

_3d¶: Restrict search results to only include 3D videos.

any¶: Include both 3D and non-3D videos in returned results. This is the default value.

class ayt_api.filters.VideoDurationFilter(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]¶

Bases: Enum

Show videos based on their duration.

any¶: Do not filter video search results based on their duration. This is the default value.

long¶: Only include videos longer than 20 minutes.

medium¶: Only include videos that are between four and 20 minutes long (inclusive).

short¶: Only include videos that are less than four minutes long.

class ayt_api.filters.VideoEmbeddableFilter(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]¶

Bases: Enum

Restrict a search to only videos that can be embedded into a webpage.

any¶: Return all videos, embeddable or not.

true¶: Only retrieve embeddable videos.

class ayt_api.filters.VideoPaidProductPlacementFilter(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]¶

Bases: Enum

Restrict a search to only show videos that the creator has denoted as having a paid promotion.

any¶: Return all videos, regardless of whether they contain paid promotions.

true¶: Only retrieve videos with paid promotions.

class ayt_api.filters.VideoSyndicatedFilter(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]¶

Bases: Enum

Restrict a search to only videos that can be played outside YouTube.

any¶: Return all videos, syndicated or not.

true¶: Only retrieve syndicated videos.

class ayt_api.filters.VideoTypeFilter(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]¶

Bases: Enum

Restrict a search to a particular type of videos.

any¶: Return all videos.

episode¶: Only retrieve episodes of shows.

movie¶: Only retrieve movies.

class ayt_api.filters.VideoLicenseFilter(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]¶

Bases: Enum

Restrict a search to only show videos that use the particular license specified.

any¶: Return all videos, regardless of which license they have, that match the query parameters.

creative_common¶: Only return videos that have a Creative Commons license. Users can reuse videos with this license in other videos that they create. Learn more.

youtube¶: Only return videos that have the standard YouTube license.

class ayt_api.filters.VideoDefinitionFilter(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]¶

Bases: Enum

Restrict a search to only show videos with the specified definition.

any¶: Return all videos, regardless of their resolution.

high¶: Only retrieve HD videos.

standard¶: Only retrieve videos in standard definition.

class ayt_api.filters.SearchFilter(channel_id: str = None, published_after: str | int | datetime = None, published_before: str | int | datetime = None, region_code: str = None, relevance_language: str = None, topic_id: str = None, video_category_id: str = None, channel_type: ChannelTypeFilter | str = None, event_type: str | EventTypeFilter = None, order: str | OrderFilter = None, safe_search: str | SafeSearchFilter = None, kind: str | type[YoutubeVideo | YoutubeChannel | YoutubePlaylist] = None, video_caption: str | VideoCaptionFilter = None, video_definition: str | VideoDefinitionFilter = None, video_dimension: str | VideoDimensionFilter = None, video_duration: str | VideoDurationFilter = None, video_embeddable: str | VideoEmbeddableFilter = None, video_license: str | VideoLicenseFilter = None, video_paid_product_placement: str | VideoPaidProductPlacementFilter = None, video_syndicated: str | VideoSyndicatedFilter = None, video_type: str | VideoTypeFilter = None)[source]¶

Bases: object

Filters a search result.

Note

All filter names that start with “video” as well as event_type must also have kind set to YoutubeVideo for the request to be valid or a HTTPException will be raised due the API returning a 400 status code error.

channel_id¶

Show results related to a certain channel.

Type:: Optional[str]

published_after¶

Show results at or after the specified date.

Type:: Union[str, int, datetime.datetime, None]

published_before¶

Show results at or before the specified date.

Type:: Union[str, int, datetime.datetime, None]

region_code¶

Show results that can be viewed in the specific country specified in the ISO 3166-1 alpha-2 code.

Type:: Optional[str]

relevance_language¶

Show results most relevant to the specified language as a ISO639-1 code.

Type:: Optional[str]

topic_id¶

Show results associated with the specified topic.

Type:: Optional[str]

video_category_id¶

Filters video search results based on their category. The kind filter must be also be set to YoutubeVideo.

Type:: Optional[str]

channel_type¶

Restrict a search to a particular type of channel (e.g. show).

Type:: Union[ChannelTypeFilter, str, None]

event_type¶

Restricts a search to broadcast events. The kind filter must be also be set to YoutubeVideo.

Type:: Union[str, EventTypeFilter, None]

order¶

Specifies the method that will be used to order resources in the search. The method is relevance.

Type:: Union[str, OrderFilter, None]

safe_search¶

Whether the search results should include restricted content as well as standard content.

Type:: Union[str, SafeSearchFilter, None]

kind¶

Restricts a search to only a particular kind of resource. Defaults to all (no restrictions).

Changed in version 0.4.0: Renamed from _type

Type:: Union[str, type[Union[YoutubeVideo, YoutubeChannel, YoutubePlaylist]], None]

video_caption¶

Show results based on whether videos have captions. The kind filter must be also be set to YoutubeVideo.

Type:: Union[str, VideoCaptionFilter, None]

video_definition¶

Restrict a search to only show videos with the specified definition. The kind filter must be also be set to YoutubeVideo.

Type:: Union[str, VideoDefinitionFilter, None]

video_dimension¶

Restrict a search to only retrieve 2D or 3D videos. The kind filter must be also be set to YoutubeVideo.

Type:: Union[str, VideoDimensionFilter, None]

video_duration¶

Show videos based on their duration. The kind filter must be also be set to YoutubeVideo.

Type:: Union[str, VideoDurationFilter, None]

video_embeddable¶

Restrict a search to only videos that can be embedded into a webpage. The kind filter must be also be set to YoutubeVideo.

Type:: Union[str, VideoEmbeddableFilter, None]

video_license¶

Restrict a search to only show videos that use the particular license specified. The kind filter must be also be set to YoutubeVideo.

Type:: Union[str, VideoLicenseFilter, None]

video_paid_product_placement¶

Restrict a search to only show videos that the creator has denoted as having a paid promotion. The kind filter must be also be set to YoutubeVideo.

Type:: Union[str, VideoPaidProductPlacementFilter, None]

video_syndicated¶

Restrict a search to only videos that can be played outside YouTube. The kind filter must be also be set to YoutubeVideo.

Type:: Union[str, VideoSyndicatedFilter, None]

video_type¶

Restrict a search to a particular type of videos. The kind filter must be also be set to YoutubeVideo.

Type:: Union[str, VideoTypeFilter, None]