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.

  • 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.

  • 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.

Parameters

  • store_token (bool) – Whether to store the token locally for future uses. Defaults to True. Note that tokens are only valid for an hour before they expire.

  • force (bool) – Whether to force an authorisation even when authorisation credentials are still value. Defaults to False. If this is False, calls to this method won’t do anything if the client is already authorised.

  • **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.

Parameters

  • store_token (bool) – Whether to store the token locally for future uses. Defaults to True. Note that tokens are only valid for an hour before they expire.

  • force (bool) – Whether to force an authorisation even when authorisation credentials are still value. Defaults to False. If this is False, calls to this method won’t do anything if the client is already authorised.

  • **kwargs (Any) – Additional arguments to pass when creating the authorisation URL.

retrieve(start_date, end_date=datetime.date(2021, 7, 26), 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.

  • end_date (datetime.date) – The date to collect data to. Defaults to the current date.

  • 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 (-).

  • 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
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.

  • 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.

  • delimiter (int) – The delimiter to use to separate columns. Defaults to a comma (,).