API Reference

See also

This document only outlines the parts of the API designed for you to use. To view the base classes, see the documentation for the abstract base classes.

Version Info

analytix.__version__

The currently installed analytix version, represented in PEP 440 format.

Exceptions

class errors.AnalytixError

The base exception class for analytix.

class errors.NoAuthorisedService

Exception thrown when an operatoion that requires authorisation is attempted while no service is no authorised.

class errors.ServiceAlreadyExists

Exception thrown when an attempt to create a service is made while one already exists.

class errors.IncompleteRequest

Exception throws when not enough information has been passed to a request.

class errors.InvalidRequest

Exception throws when invalid information has been passed to a request.

YouTube

class youtube.YouTubeService(secrets)

A YouTube service container to help with authorisation.

Parameters

secrets (dict | os.PathLike | str]) – The filepath to a secrets file or a dictionary of credentials used to authorise a YouTube service.

authorise(*scopes, use_console=False)

Authorises the YouTube service.

Parameters

  • scopes (str *args) – A series of string arguments denoting which scopes to use.

  • use_console (bool) – Whether to use the console authorisation method.

Raises
authorize(*scopes, use_console=False)

An alias to authorize.

close()

Closes a YouTube service

Raises

NoAuthorisedService – No authorised service currently exists.

class youtube.BasicYouTubeAnalytics(service, by_province=False)

A class to retrieve basic user activity data.

Parameters

  • service (YouTubeService) – The YouTube service to perform the operation on.

  • by_province (bool) – Whether to get data for provinces or countries. Defaults to False.

dimensions

An object for dimension verification.

Type

Dimensions

metrics

A tuple containing all valid metrics.

Type

tuple[str, ..]

filters

An object for filter verification.

Type

Filters

property by_province

A Boolean shortcut to change the list of allowed metrics, dimensions, and filters by changing whether the data is fetched by province.

retrieve(metrics, start_date, **kwargs)

Executes an API request to pull down analytical information.

Parameters

  • metrics (tuple[str, ..] | list[str]) – The YouTube Analytics metrics to use, such as views, likes, and comments.

  • start_date (datetime.date) – The start date for fetching YouTube Analytics data.

  • end_date (datetime.date) – The end date for fetching YouTube Analytics data. Defaults to the current date, but if the monetary scope is enabled, a few days of data may be missing.

  • currency (str) – The currency to use for monetary analytics in ISO 4217 format. Defaults to USD.

  • dimensions (tuple[str, ..] | list[str]) – The YouTube Analytics dimensions, such as video, ageGroup, or gender. Defaults to an empty tuple.

  • filters (dict[str, str]) – A list of filters that should be applied when retrieving YouTube Analytics data. When providing multiple values for the same filter, separate them with commas. Defaults to an empty dict.

  • include_historical_data (bool) – Indicates whether the API response should include channels’ watch time and view data from the time period prior to when the channels were linked to the content owner. The day and month dimensions overwrite this option. Defaults to False.

  • max_results (int | None) – The maximum number of rows to include in the response. Defaults to None.

  • sort_by (tuple[str, ..] | list[str]) – A series of dimensions in which to sort the data. The first dimension is how the data will be sorted at first, followed by the second, and so forth. Defaults to an empty tuple, though data is typically automatically sorted by the YouTube Analytics API.

  • sort_descending (bool) – Whether to sort in descending order. Defaults to False.

  • start_index (int) – The index of the first entity to retrieve. Note that this is one-indexed, not zero-indexed. Defaults to 1.

Returns

The report object containing the data fetched by the YouTube Analytics API.

Return type

YouTubeAnalyticsReport

Raises

InvalidRequest – The request was invalid.

class youtube.TimeBasedYouTubeAnalytics(service, by_province=False)

A class to retrieve time based analytical data.

Parameters

  • service (YouTubeService) – The YouTube service to perform the operation on.

  • by_province (bool) – Whether to get data for provinces or countries. Defaults to False.

dimensions

An object for dimension verification.

Type

Dimensions

metrics

A tuple containing all valid metrics.

Type

tuple[str, ..]

filters

An object for filter verification.

Type

Filters

property by_province

A Boolean shortcut to change the list of allowed metrics, dimensions, and filters by changing whether the data is fetched by province.

retrieve(metrics, start_date, **kwargs)

Executes an API request to pull down analytical information.

Parameters

  • metrics (tuple[str, ..] | list[str]) – The YouTube Analytics metrics to use, such as views, likes, and comments.

  • start_date (datetime.date) – The start date for fetching YouTube Analytics data.

  • end_date (datetime.date) – The end date for fetching YouTube Analytics data. Defaults to the current date, but if the monetary scope is enabled, a few days of data may be missing.

  • currency (str) – The currency to use for monetary analytics in ISO 4217 format. Defaults to USD.

  • dimensions (tuple[str, ..] | list[str]) – The YouTube Analytics dimensions, such as video, ageGroup, or gender. Defaults to an empty tuple.

  • filters (dict[str, str]) – A list of filters that should be applied when retrieving YouTube Analytics data. When providing multiple values for the same filter, separate them with commas. Defaults to an empty dict.

  • include_historical_data (bool) – Indicates whether the API response should include channels’ watch time and view data from the time period prior to when the channels were linked to the content owner. The day and month dimensions overwrite this option. Defaults to False.

  • max_results (int | None) – The maximum number of rows to include in the response. Defaults to None.

  • sort_by (tuple[str, ..] | list[str]) – A series of dimensions in which to sort the data. The first dimension is how the data will be sorted at first, followed by the second, and so forth. Defaults to an empty tuple, though data is typically automatically sorted by the YouTube Analytics API.

  • sort_descending (bool) – Whether to sort in descending order. Defaults to False.

  • start_index (int) – The index of the first entity to retrieve. Note that this is one-indexed, not zero-indexed. Defaults to 1.

Returns

The report object containing the data fetched by the YouTube Analytics API.

Return type

YouTubeAnalyticsReport

Raises

InvalidRequest – The request was invalid.

class youtube.GeographicYouTubeAnalytics(service, by_province=False)

A class to retrieve user geography analytical data.

Parameters

  • service (YouTubeService) – The YouTube service to perform the operation on.

  • by_province (bool) – Whether to get data for provinces or countries. Defaults to False.

dimensions

An object for dimension verification.

Type

Dimensions

metrics

A tuple containing all valid metrics.

Type

tuple[str, ..]

filters

An object for filter verification.

Type

Filters

property by_province

A Boolean shortcut to change the list of allowed metrics, dimensions, and filters by changing whether the data is fetched by province.

retrieve(metrics, start_date, **kwargs)

Executes an API request to pull down analytical information.

Parameters

  • metrics (tuple[str, ..] | list[str]) – The YouTube Analytics metrics to use, such as views, likes, and comments.

  • start_date (datetime.date) – The start date for fetching YouTube Analytics data.

  • end_date (datetime.date) – The end date for fetching YouTube Analytics data. Defaults to the current date, but if the monetary scope is enabled, a few days of data may be missing.

  • currency (str) – The currency to use for monetary analytics in ISO 4217 format. Defaults to USD.

  • dimensions (tuple[str, ..] | list[str]) – The YouTube Analytics dimensions, such as video, ageGroup, or gender. Defaults to an empty tuple.

  • filters (dict[str, str]) – A list of filters that should be applied when retrieving YouTube Analytics data. When providing multiple values for the same filter, separate them with commas. Defaults to an empty dict.

  • include_historical_data (bool) – Indicates whether the API response should include channels’ watch time and view data from the time period prior to when the channels were linked to the content owner. The day and month dimensions overwrite this option. Defaults to False.

  • max_results (int | None) – The maximum number of rows to include in the response. Defaults to None.

  • sort_by (tuple[str, ..] | list[str]) – A series of dimensions in which to sort the data. The first dimension is how the data will be sorted at first, followed by the second, and so forth. Defaults to an empty tuple, though data is typically automatically sorted by the YouTube Analytics API.

  • sort_descending (bool) – Whether to sort in descending order. Defaults to False.

  • start_index (int) – The index of the first entity to retrieve. Note that this is one-indexed, not zero-indexed. Defaults to 1.

Returns

The report object containing the data fetched by the YouTube Analytics API.

Return type

YouTubeAnalyticsReport

Raises

InvalidRequest – The request was invalid.

class youtube.BasicPlaylistYouTubeAnalytics(service)

A class to retrieve basic user activity data within playlists.

Parameters

  • service (YouTubeService) – The YouTube service to perform the operation on.

  • by_province (bool) – Whether to get data for provinces or countries. Defaults to False.

dimensions

An object for dimension verification.

Type

Dimensions

metrics

A tuple containing all valid metrics.

Type

tuple[str, ..]

filters

An object for filter verification.

Type

Filters

retrieve(metrics, start_date, **kwargs)

Executes an API request to pull down analytical information.

Parameters

  • metrics (tuple[str, ..] | list[str]) – The YouTube Analytics metrics to use, such as views, likes, and comments.

  • start_date (datetime.date) – The start date for fetching YouTube Analytics data.

  • end_date (datetime.date) – The end date for fetching YouTube Analytics data. Defaults to the current date, but if the monetary scope is enabled, a few days of data may be missing.

  • currency (str) – The currency to use for monetary analytics in ISO 4217 format. Defaults to USD.

  • dimensions (tuple[str, ..] | list[str]) – The YouTube Analytics dimensions, such as video, ageGroup, or gender. Defaults to an empty tuple.

  • filters (dict[str, str]) – A list of filters that should be applied when retrieving YouTube Analytics data. When providing multiple values for the same filter, separate them with commas. Defaults to an empty dict.

  • include_historical_data (bool) – Indicates whether the API response should include channels’ watch time and view data from the time period prior to when the channels were linked to the content owner. The day and month dimensions overwrite this option. Defaults to False.

  • max_results (int | None) – The maximum number of rows to include in the response. Defaults to None.

  • sort_by (tuple[str, ..] | list[str]) – A series of dimensions in which to sort the data. The first dimension is how the data will be sorted at first, followed by the second, and so forth. Defaults to an empty tuple, though data is typically automatically sorted by the YouTube Analytics API.

  • sort_descending (bool) – Whether to sort in descending order. Defaults to False.

  • start_index (int) – The index of the first entity to retrieve. Note that this is one-indexed, not zero-indexed. Defaults to 1.

Returns

The report object containing the data fetched by the YouTube Analytics API.

Return type

YouTubeAnalyticsReport

Raises

InvalidRequest – The request was invalid.

class youtube.TimeBasedPlaylistYouTubeAnalytics(service)

A class to retrieve time based analytical data within playlists.

Parameters

  • service (YouTubeService) – The YouTube service to perform the operation on.

  • by_province (bool) – Whether to get data for provinces or countries. Defaults to False.

dimensions

An object for dimension verification.

Type

Dimensions

metrics

A tuple containing all valid metrics.

Type

tuple[str, ..]

filters

An object for filter verification.

Type

Filters

retrieve(metrics, start_date, **kwargs)

Executes an API request to pull down analytical information.

Parameters

  • metrics (tuple[str, ..] | list[str]) – The YouTube Analytics metrics to use, such as views, likes, and comments.

  • start_date (datetime.date) – The start date for fetching YouTube Analytics data.

  • end_date (datetime.date) – The end date for fetching YouTube Analytics data. Defaults to the current date, but if the monetary scope is enabled, a few days of data may be missing.

  • currency (str) – The currency to use for monetary analytics in ISO 4217 format. Defaults to USD.

  • dimensions (tuple[str, ..] | list[str]) – The YouTube Analytics dimensions, such as video, ageGroup, or gender. Defaults to an empty tuple.

  • filters (dict[str, str]) – A list of filters that should be applied when retrieving YouTube Analytics data. When providing multiple values for the same filter, separate them with commas. Defaults to an empty dict.

  • include_historical_data (bool) – Indicates whether the API response should include channels’ watch time and view data from the time period prior to when the channels were linked to the content owner. The day and month dimensions overwrite this option. Defaults to False.

  • max_results (int | None) – The maximum number of rows to include in the response. Defaults to None.

  • sort_by (tuple[str, ..] | list[str]) – A series of dimensions in which to sort the data. The first dimension is how the data will be sorted at first, followed by the second, and so forth. Defaults to an empty tuple, though data is typically automatically sorted by the YouTube Analytics API.

  • sort_descending (bool) – Whether to sort in descending order. Defaults to False.

  • start_index (int) – The index of the first entity to retrieve. Note that this is one-indexed, not zero-indexed. Defaults to 1.

Returns

The report object containing the data fetched by the YouTube Analytics API.

Return type

YouTubeAnalyticsReport

Raises

InvalidRequest – The request was invalid.

class youtube.GeographicPlaylistYouTubeAnalytics(service)

A class to retrieve geographic analytical data within playlists.

Parameters

  • service (YouTubeService) – The YouTube service to perform the operation on.

  • by_province (bool) – Whether to get data for provinces or countries. Defaults to False.

dimensions

An object for dimension verification.

Type

Dimensions

metrics

A tuple containing all valid metrics.

Type

tuple[str, ..]

filters

An object for filter verification.

Type

Filters

retrieve(metrics, start_date, **kwargs)

Executes an API request to pull down analytical information.

Parameters

  • metrics (tuple[str, ..] | list[str]) – The YouTube Analytics metrics to use, such as views, likes, and comments.

  • start_date (datetime.date) – The start date for fetching YouTube Analytics data.

  • end_date (datetime.date) – The end date for fetching YouTube Analytics data. Defaults to the current date, but if the monetary scope is enabled, a few days of data may be missing.

  • currency (str) – The currency to use for monetary analytics in ISO 4217 format. Defaults to USD.

  • dimensions (tuple[str, ..] | list[str]) – The YouTube Analytics dimensions, such as video, ageGroup, or gender. Defaults to an empty tuple.

  • filters (dict[str, str]) – A list of filters that should be applied when retrieving YouTube Analytics data. When providing multiple values for the same filter, separate them with commas. Defaults to an empty dict.

  • include_historical_data (bool) – Indicates whether the API response should include channels’ watch time and view data from the time period prior to when the channels were linked to the content owner. The day and month dimensions overwrite this option. Defaults to False.

  • max_results (int | None) – The maximum number of rows to include in the response. Defaults to None.

  • sort_by (tuple[str, ..] | list[str]) – A series of dimensions in which to sort the data. The first dimension is how the data will be sorted at first, followed by the second, and so forth. Defaults to an empty tuple, though data is typically automatically sorted by the YouTube Analytics API.

  • sort_descending (bool) – Whether to sort in descending order. Defaults to False.

  • start_index (int) – The index of the first entity to retrieve. Note that this is one-indexed, not zero-indexed. Defaults to 1.

Returns

The report object containing the data fetched by the YouTube Analytics API.

Return type

YouTubeAnalyticsReport

Raises

InvalidRequest – The request was invalid.