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.

  • active (Resource | None) – The currently authorised service. If no service is authorised, this None.

authorise(use_console=False)

Authorises the YouTube service.

Parameters

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

Raises

ServiceAlreadyExists – A service already exists, and has been authorised.

authorize(use_console=False)

An alias to authorise.

close()

Closes a YouTube service

Raises

NoAuthorisedService – No authorised service currently exists.

class youtube.YouTubeAnalytics(service)

A class to retrieve data from the YouTube Analytics API.

Parameters

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

service

The YouTube service to perform the operation on.

Type

YouTubeService

retrieve(metrics='all', verify=True, **kwargs)

Executes an API request to pull down analytical information.

Warning

The start_date and end_date parameters do not account for delayed analytics such as revenue.

Note

This will retrieve video reports by default. To retrieve playlist reports, include ‘“isCurated”: “1”’ in your filters.

Parameters

  • metrics (str | tuple[str, ..] | list[str]) – The metrics (or columns) to retrieve. Defaults to “all”.

  • verify (bool) – Whether to verify the requests before passing them to the API. Defaults to True.

  • start_date (datetime.date) – The earliest date to fetch data for. Defaults to 28 days before the current date.

  • end_date (datetime.date) – The latest date to fetch data for. Defaults to the current date.

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

  • dimensions (tuple[str, ..] | list[str]) – The dimensions in which data is split. Defaults to an empty tuple.

  • filters (dict[str, str]) – The filters to be applied when retrieving data. Defaults to an empty dictionary.

  • include_historical_data (bool) – Whether data before the point in which the specified channel(s) were linked to the content owner should be retrieved. Defaults to False.

  • max_results (int | None) – The maximum number of rows to fetch. Defaults to None.

  • sort_by (tuple[str, ..] | list[str]) – The dimensions in which to sort the data. Defaults to an empty tuple.

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

Returns

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

Return type

YouTubeAnalyticsReport

Raises