analytics#
- class analytix.analytics.Analytics(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.
- secrets#
A
Secrets
object representing your project secrets.
- 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 legacy_auth: bool#
Whether to use manual copy/paste authorisation.
Warning
Manual copy/paste authorisation is deprecated by Google, and stopped being made available from 1 April. While analytix still provides the ability to use it for now, it is strongly recommended you only do so if you absolutely have to (for example, if your firewall does not allow loopback communication).
Warning
Manual copy/paste authorisation is not always available. If it is not, analytix will lock up.
New in version 3.4.0.
- 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(*, port: int = 8080) None #
Refresh the access token.
- Keyword Arguments
port –
The port to use for the authorisation webserver when using loopback IP address authorisation. Defaults to 8080. This is ignored if analytix is configured to use manual copy/paste authorisation.
New in version 3.4.0.
- authorise(token_path: pathlib.Path | str = '.', *, force: bool = False, port: int = 8080) Tokens #
Authorise the client. This is called automatically when needed if not manually called.
- 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
.port –
The port to use for the authorisation webserver when using loopback IP address authorisation. Defaults to 8080. This is ignored if analytix is configured to use manual copy/paste authorisation.
New in version 3.4.0.
- 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 = '.', port: int = 8080) Report #
Retrieves a report from the YouTube Analytics API.
- Keyword Arguments
dimensions – The dimensions to use in the report. Defaults to
None
. If this isNone
, no dimensions will be used.filters – The filters to use in the report. Defaults to
None
. If this isNone
, no filters will be used.metrics – The metrics to use in the report. Defaults to
None
. If this isNone
, 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 isNone
, no sort options will be used.max_results – The maximum number of results to include in the report. Defaults to
0
. If this is0
, 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 isNone
, 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 isNone
, 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 to1
will include all rows, and setting it to10
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.
port –
The port to use for the authorisation webserver when using loopback IP address authorisation. Defaults to 8080. This is ignored if analytix is configured to use manual copy/paste authorisation.
New in version 3.4.0.
- Returns
An instance for working with retrieved data.