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¶
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.
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.
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
-
get_report_type
(metrics=(), dimensions=(), filters={}, *, verify=True)¶ Gets the report type that best matches the metrics, dimensions, and filters given. If
verify
is False, this will return aGeneric
report type.- Parameters
metrics (tuple[str, ..] | list[str]) – The metrics (or columns) to retrieve. Defaults to an empty tuple.
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.
verify (bool) – Whether to attempt to determine the report type dynamically. Defaults to True.
- Returns
The selected report type.
- Return type
ReportType
-
get_verified_report_type
(metrics=(), dimensions=(), filters={})¶ Like
get_report_type
, but only returns a ReportType object if verification succeeds.- Parameters
metrics (tuple[str, ..] | list[str]) – The metrics (or columns) to retrieve. Defaults to an empty tuple.
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.
- Returns
The selected report type or the error that caused verification to fail.
- Return type
ReportType | InvalidRequest
-
retrieve
(metrics='all', verify=True, **kwargs)¶ Executes an API request to pull down analytical information.
Warning
The
start_date
andend_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 (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
- Raises
NoAuthorisedService – The given service has not been authorised.
InvalidRequest – The request was invalid.
-
class
youtube.
YouTubeAnalyticsReport
(data, type_)¶ A class that provides an interface for working with data retrieved from the YouTube Analytics API.
- Parameters
data (dict) – The response data from the YouTube Analytics API.
type (ReportType) – The type of report generated.
-
data
¶ The response data from the YouTube Analytics API.
- Type
dict
-
ncolumns
¶ The number of columns in the report.
- Type
int
-
nrows
¶ The number of rows in the report.
- Type
int
-
type
¶ The type of report generated.
- Type
ReportType
-
to_csv
(file)¶ Exports the report to a CSV file.
- Parameters
file (str | os.PathLike) – The path in which the report should be saved.
-
to_dataframe
()¶ Returns the report as a Pandas DataFrame.
- Returns
The DataFrame object.
- Return type
pandas.DataFrame
-
to_json
(file, indent=4)¶ Exports the report to a JSON file in the same format as it was provided by the YouTube Analytics API.
- Parameters
file (str | os.PathLike) – The path in which the report should be saved.
indent (int) – The number of spaces to use for indentation. Defaults to 4.