analytics#

class analytix.analytics.Analytics(secrets: analytix.secrets.Secrets, **kwargs: Any)#

A class representing a client for the YouTube Analytics API.

Parameters

secrets – The project secrets from the Google Developers Console.

Keyword Arguments

**kwargs – Additional parameters to be passed to the httpx.Client constructor.

classmethod with_secrets(path: pathlib.Path | str) → Analytics#

Create a client using secrets from a file downloaded from the Google Developers Console.

Parameters

path – The path to the secrets file.

Returns

The created client instance.

property authorised: bool#

Whether this client is authorised.

close_session() → None#

Close the currently open session.

check_for_updates() → str | None#

Checks for newer versions of analytix.

Returns

The latest version, or None if either you are using the latest version, or the latest version could not be ascertained.

needs_refresh() → bool#

Check whether any existing token needs refreshing. If the client is not currently authorised, this will return False.

Returns

Whether the access token needs to be refreshed.

refresh_access_token() → None#

Refresh the access token.

authorise(token_path: pathlib.Path | str = '.', *, force: bool = False) → Tokens#

Authorise the client. This is called automatically when needed if not manually called, though if you want to authorise with non-default options, you will need to call this manually.

Parameters

token_path – The path to the token file or the directory the token file is or should be stored in. If this is not provided, this defaults to the current directory, and if a directory is passed, the file is given the name “tokens.json”.

Keyword Arguments

force – Whether to forcibly authorise the client. Defaults to False.

Returns

The tokens the client is authorised with.

retrieve(*, dimensions: t.Collection[str] | None = None, filters: dict[str, str] | None = None, metrics: t.Collection[str] | None = None, sort_options: t.Collection[str] | None = None, max_results: int = 0, start_date: dt.date | None = None, end_date: dt.date | None = None, currency: str = 'USD', start_index: int = 1, include_historical_data: bool = False, skip_validation: bool = False, force_authorisation: bool = False, skip_update_check: bool = False, skip_refresh_check: bool = False, token_path: pathlib.Path | str = '.') → Report#

Retrieves a report from the YouTube Analytics API.

Keyword Arguments

  • dimensions – The dimensions to use in the report. Defaults to None. If this is None, no dimensions will be used.

  • filters – The filters to use in the report. Defaults to None. If this is None, no filters will be used.

  • metrics – The metrics to use in the report. Defaults to None. If this is None, all available metrics for the selected report type will be used.

  • sort_options – The sort options to use in the report. Defaults to None. If this is None, no sort options will be used.

  • max_results – The maximum number of results to include in the report. Defaults to 0. If this is 0, no limit will be set on the maximum number of results.

  • start_date – The date from which to begin pulling data. Defaults to None. If this is None, this will be set to 28 days before the end date.

  • end_date –

    The date in which to pull data up to. Defaults to None. If this is None, this will be set to the current date.

    Warning

    Due to the nature of the YouTube Analytics API, some dates may be missing from the report. analytix does not compensate for this, as the number missing is not consistent.

  • currency – The currency in which financial data will be displayed. Defaults to “USD”. This must be an ISO 4217 currency code (such as USD or GBP).

  • start_index – The first row of the data to include in the report. Defaults to 1. This value one-indexed, meaning setting this to 1 will include all rows, and setting it to 10 will remove the first nine rows.

  • include_historical_data – Whether to retrieve data from dates earlier than the current channel owner assumed ownership of the channel. Defaults to False. You only need to worry about this if you are not the original owner of the channel.

  • skip_validation – Whether to skip the validation process. Defaults to False.

  • force_authorisation – Whether to force the (re)authorisation of the client. Defaults to False.

  • skip_update_check – Whether to skip checking for updates. Defaults to False.

  • skip_refresh_token – Whether to skip token refreshing. Defaults to False.

  • token_path –

    The path to the token file or the directory the token file is or should be stored in. If this is not provided, this defaults to the current directory, and if a directory is passed, the file is given the name “tokens.json”.

    New in version 3.3.0.

Returns

An instance for working with retrieved data.