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
- 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
- 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. Note that tokens are only valid for an hour before they expire. Defaults to True.
force (bool) – Whether to force an authorisation even when authorisation credentials are still value. If this is False, calls to this method won’t do anything if the client is already authorised. Defaults to False.
**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. Note that tokens are only valid for an hour before they expire. Defaults to True.
force (bool) – Whether to force an authorisation even when authorisation credentials are still value. If this is False, calls to this method won’t do anything if the client is already authorised. Defaults to False.
**kwargs (Any) – Additional arguments to pass when creating the authorisation URL.
- retrieve(start_date, end_date=datetime.date(2021, 7, 27), 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
datetime.date.today()
.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 (-). Defaults to an empty tuple.
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
- Raises
InvalidRequest – Something is wrong with the request.
HTTPError – The API returned an error.
- daily_analytics(of=None, since=None, last=28, metrics='all')¶
A factory method that retrieves daily video or channel analytics.
New in version 2.1.
- Parameters
of (str | None) – A video ID. Pass None to include all videos. Defaults to None.
since (datetime.date | None) – The date to start collecting data from. If this is None, analytix will fall back to the
last
kwarg. Defaults to None.last (int) – The number of days to retrieve data for. If
since
is not None, this is ignored. This accounts for delayed revenue analytics, but does mean that an extra day of data may sometimes be included in the report. In this case, that means the report may contain eitherlast
orlast + 1
rows. Defaults to 28.metrics (iterable[str] | str) – A list of metrics to use. Defaults to “all”.
- Returns
The retrieved report.
- Return type
- Raises
InvalidRequest – Something is wrong with the request.
HTTPError – The API returned an error.
- monthly_analytics(of=None, since=None, last=3, metrics='all')¶
A factory method that retrieves monthly video or channel analytics.
New in version 2.1.
- Parameters
of (str | None) – A video ID. Pass None to include all videos. Defaults to None.
since (datetime.date | None) – The date to start collecting data from. If this is None, analytix will fall back to the
last
kwarg. Theday
argument for the date constructor must be set to 1 – if it is not, it will be set to 1 for you. Defaults to None.last (int) – The number of months to retrieve data for. If
since
is not None, this is ignored. The current month is not included in reports retrieved using this method. The number passed here will be the number of rows in the report. Defaults to 3.metrics (iterable[str] | str) – A list of metrics to use. Defaults to “all”.
- Returns
The retrieved report.
- Return type
- Raises
InvalidRequest – Something is wrong with the request.
HTTPError – The API returned an error.
- regional_analytics(since=None, last=28, metrics='all')¶
A factory method that retrieves channel analytics by country. This is automatically sorted by views.
New in version 2.1.
- Parameters
since (datetime.date | None) – The date to start collecting data from. If this is None, analytix will fall back to the
last
kwarg. Defaults to None.last (int) – The number of days to retrieve data for. If
since
is not None, this is ignored. This accounts for delayed revenue analytics, but does mean that an extra day of data may sometimes be included in the report. Defaults to 28.metrics (iterable[str] | str) – A list of metrics to use. Defaults to “all”.
- Returns
The retrieved report.
- Return type
- Raises
InvalidRequest – Something is wrong with the request.
HTTPError – The API returned an error.
- top_videos(by='views', since=None, last=28, metrics='all')¶
A factory method that retrieves information on your channel’s top videos over time.
New in version 2.1.
- Parameters
by (str) – The metric to sort by. Note that not all metrics are supported. Reports retrieved using this method will be sorted in descending order regardless of whether you prefix the metric with a hyphen (-). Defaults to “views”.
since (datetime.date | None) – The date to start collecting data from. If this is None, analytix will fall back to the
last
kwarg. Defaults to None.last (int) – The number of days to retrieve data for. If
since
is not None, this is ignored. This accounts for delayed revenue analytics, but does mean that an extra day of data may sometimes be included in the report. Defaults to 28.metrics (iterable[str] | str) – A list of metrics to use. Defaults to “all”.
- Returns
The retrieved report.
- Return type
- Raises
InvalidRequest – Something is wrong with the request.
HTTPError – The API returned an error.
- 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 (,).