Library reference - YouTube analytics¶

class analytix.YouTubeAnalytics(session, secrets)¶

A client class to retrieve data from the YouTube Analytics API. This should only be created from the relevant class methods.

Parameters

session (OAuth2Session) – The OAuth 2 session to use.
secrets (dict[str, str]) – A dictionary containing Google Developers project secrets. This is not expected in the same format as the Google Developers console provides it.

secrets¶

A dictionary containing Google Developers project secrets.

Type: dict[str, str]

project_id¶

The ID of the Google Developers project.

Type: str

property authorised¶

Whether the project is authorised.

Returns: bool

property authorized¶

Whether the project is authorised.

Returns: bool

classmethod from_file(path, *, scopes='all', **kwargs)¶

Creates the client object using a secrets file.

Parameters

path (str) – The path to the secrets file.

Keyword Arguments

scopes (iterable[str] | str) – The scopes to use. Defaults to “all”.
**kwargs (Any) – Additional arguments to pass to the OAuth2Session constructor.

Returns

A ready-to-use client object.

Return type

YouTubeAnalytics

classmethod from_dict(secrets, *, scopes='all', **kwargs)¶

Creates the client object using a secrets dictionary.

Parameters

secrets (dict[str, dict[str, str]]) – The secrets dictionary.

Keyword Arguments

scopes (iterable[str] | str) – The scopes to use. Defaults to “all”.
**kwargs (Any) – Additional arguments to pass to the OAuth2Session constructor.

Returns

A ready-to-use client object.

Return type

YouTubeAnalytics

authorise(store_token=True, force=False, **kwargs)¶

Authorises the client. This is typically called automatically when needed, so you often don’t need to call this unless you want to override the default behaviour.

Keyword Arguments

store_token (bool) – Whether to store the token locally for future uses. Note that tokens are only valid for an hour before they expire. Defaults to True.
force (bool) – Whether to force an authorisation even when authorisation credentials are still valid. If this is False, calls to this method won’t do anything if the client is already authorised. Defaults to False.
**kwargs (Any) – Additional arguments to pass when creating the authorisation URL.

authorize(store_token=True, force=False, **kwargs)¶

Authorises the client. This is typically called automatically when needed, so you often don’t need to call this unless you want to override the default behaviour.

Keyword Arguments

store_token (bool) – Whether to store the token locally for future uses. Note that tokens are only valid for an hour before they expire. Defaults to True.
force (bool) – Whether to force an authorisation even when authorisation credentials are still valid. If this is False, calls to this method won’t do anything if the client is already authorised. Defaults to False.
**kwargs (Any) – Additional arguments to pass when creating the authorisation URL.

retrieve(start_date, end_date=datetime.date(2021, 9, 27), metrics='all', **kwargs)¶

Retrieves a report from the YouTube Analytics API.

Parameters

start_date (datetime.date) – The date from which data should be collected from.

Keyword Arguments

end_date (datetime.date) – The date to collect data to. Defaults to datetime.date.today().
metrics (iterable[str] | str) – The metrics (or columns) to use in the report. Defaults to “all”.
dimensions (iterable[str]) – The dimensions to use. These dimensions are how data is split; for example, if the “day” dimension is provided, each row will contain information for a different day. Defaults to an empty tuple.
filters (dict[str, str]) – The filters to use. To get playlist reports, include "isCurated": "1". Defaults to an empty dictionary.
sort_by (iterable[str]) – A list of metrics to sort by. To sort in descending order, prefix the metric(s) with a hyphen (-). Defaults to an empty tuple.
max_results (int) – The maximum number of rows to include in the report. Set this to 0 to remove the limit. Defaults to 0.
currency (str) – The currency to use in the format defined in the ISO 4217 standard. Defaults to “USD”.
start_index (int) – The row to start pulling data from. This value is one-indexed, meaning the first row is 1, not 0. Defaults to 1.
include_historical_data (bool) – Whether to retrieve data before the current owner of the channel became affiliated with the channel. Defaults to False.

Returns

The retrieved report.

Return type

YouTubeAnalyticsReport

Raises

InvalidRequest – Something is wrong with the request.
HTTPError – The API returned an error.

daily_analytics(of=None, since=None, last=28, metrics='all')¶

A factory method that retrieves daily video or channel analytics.

New in version 2.1.

Keyword Arguments

of (str | None) – A video ID. Pass None to include all videos. Defaults to None.
since (datetime.date | None) – The date to start collecting data from. If this is None, analytix will fall back to the last kwarg. Defaults to None.
last (int) – The number of days to retrieve data for. If since is not None, this is ignored. This accounts for delayed revenue analytics, but does mean that an extra day of data may sometimes be included in the report. In this case, that means the report may contain either last or last + 1 rows. Defaults to 28.
metrics (iterable[str] | str) – A list of metrics to use. Defaults to “all”.

Returns

The retrieved report.

Return type

YouTubeAnalyticsReport

Raises

InvalidRequest – Something is wrong with the request.
HTTPError – The API returned an error.

monthly_analytics(of=None, since=None, last=3, metrics='all')¶

A factory method that retrieves monthly video or channel analytics.

New in version 2.1.

Keyword Arguments

of (str | None) – A video ID. Pass None to include all videos. Defaults to None.
since (datetime.date | None) – The date to start collecting data from. If this is None, analytix will fall back to the last kwarg. The day argument for the date constructor must be set to 1 – if it is not, it will be set to 1 for you. Defaults to None.
last (int) – The number of months to retrieve data for. If since is not None, this is ignored. The current month is not included in reports retrieved using this method. The number passed here will be the number of rows in the report. Defaults to 3.
metrics (iterable[str] | str) – A list of metrics to use. Defaults to “all”.

Returns

The retrieved report.

Return type

YouTubeAnalyticsReport

Raises

InvalidRequest – Something is wrong with the request.
HTTPError – The API returned an error.

regional_analytics(since=None, last=28, metrics='all')¶

A factory method that retrieves channel analytics by country. This is automatically sorted by views.

New in version 2.1.

Keyword Arguments

since (datetime.date | None) – The date to start collecting data from. If this is None, analytix will fall back to the last kwarg. Defaults to None.
last (int) – The number of days to retrieve data for. If since is not None, this is ignored. This accounts for delayed revenue analytics, but does mean that an extra day of data may sometimes be included in the report. Defaults to 28.
metrics (iterable[str] | str) – A list of metrics to use. Defaults to “all”.

Returns

The retrieved report.

Return type

YouTubeAnalyticsReport

Raises

InvalidRequest – Something is wrong with the request.
HTTPError – The API returned an error.

top_videos(by='views', since=None, last=28, metrics='all')¶

A factory method that retrieves information on your channel’s top videos over time.

New in version 2.1.

Keyword Arguments

by (str) – The metric to sort by. Note that not all metrics are supported. Reports retrieved using this method will be sorted in descending order regardless of whether you prefix the metric with a hyphen (-). Defaults to “views”.
since (datetime.date | None) – The date to start collecting data from. If this is None, analytix will fall back to the last kwarg. Defaults to None.
last (int) – The number of days to retrieve data for. If since is not None, this is ignored. This accounts for delayed revenue analytics, but does mean that an extra day of data may sometimes be included in the report. Defaults to 28.
metrics (iterable[str] | str) – A list of metrics to use. Defaults to “all”.

Returns

The retrieved report.

Return type

YouTubeAnalyticsReport

Raises

InvalidRequest – Something is wrong with the request.
HTTPError – The API returned an error.

class analytix.youtube.analytics.api.YouTubeAnalyticsReport(type, data)¶

A class created when a report is retrieved. You should not attempt to construct this class manually.

Parameters

type (str) – The report type.
data (dict[str, Any]) – The raw data from the YouTube Analytics API.

type¶

The report type.

Type: str

data¶

The raw data from the YouTube Analytics API.

Type: dict[str, Any]

columns¶

A list of all column names.

Type: list[str]

property shape¶

The shape of the report.

Returns: Number of rows, columns.
Return type: tuple[int, int]

to_dataframe()¶

Returns the data in a pandas DataFrame. If “day” or “month” are columns, these are converted to the datetime64[ns] dtype automatically.

Returns: A pandas DataFrame
Return type: DataFrame

to_json(path, *, indent=4)¶

Writes the raw report data to a JSON file.

Parameters: path (str) – The path to save the file to.
Keyword Arguments: indent (int) – The amount of spaces to use as an indent. Defaults to 4.

to_csv(path, *, delimiter=',')¶

Writes the report data to a CSV file.

Parameters: path (str) – The path to save the file to.
Keyword Arguments: delimiter (int) – The delimiter to use to separate columns. Defaults to a comma (,).