Skip to content

shard

A shard interface for analytix.

Shards are used by clients as an interface through which to make requests, and are particularly useful when multiple users are likely to make requests at the same time.

Shard

Bases: RequestMixin

A "mini-client" used to handle requests to the YouTube Analytics API.

Shards should only be created using the BaseClient.shard or Client.shard context managers.

Changed in version 5.0
  • Shard-specific scopes can now be passed to the constructor
  • Shards can no longer refresh their own tokens

Parameters:

Name Type Description Default
scopes Scopes

The scopes to allow in requests. This is used to control whether or not to allow access to monetary data.

 required
tokens Tokens

Your tokens.

 required
Warnings

Shards cannot refresh their own tokens. You may want to take extra precautions to ensure a shard's tokens don't expire during its lifetime.

Source code in analytix/shard.py 
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
class Shard(RequestMixin):
    """A "mini-client" used to handle requests to the YouTube Analytics
    API.

    Shards should only be created using the `BaseClient.shard` or
    `Client.shard` context managers.

    ???+ note "Changed in version 5.0"
        * Shard-specific scopes can now be passed to the constructor
        * Shards can no longer refresh their own tokens

    Parameters
    ----------
    scopes
        The scopes to allow in requests. This is used to control whether
        or not to allow access to monetary data.
    tokens
        Your tokens.

    Warnings
    --------
    Shards cannot refresh their own tokens. You may want to take extra
    precautions to ensure a shard's tokens don't expire during its
    lifetime.
    """

    __slots__ = ("_scopes", "_tokens")

    def __init__(self, scopes: "Scopes", tokens: "Tokens") -> None:
        self._scopes = scopes
        self._tokens = tokens

    def fetch_report(
        self,
        *,
        dimensions: Optional[Collection[str]] = None,
        filters: Optional[Dict[str, str]] = None,
        metrics: Optional[Collection[str]] = None,
        sort_options: Optional[Collection[str]] = None,
        start_date: Optional[dt.date] = None,
        end_date: Optional[dt.date] = None,
        max_results: int = 0,
        currency: str = "USD",
        start_index: int = 1,
        include_historical_data: bool = False,
    ) -> Report:
        """Fetch an analytics report.

        ???+ note "Changed in version 5.0"
            This used to be `retrieve_report`.

        ???+ note "Changed in version 5.2"
            Support for [new playlst reports](../guides/
            new-playlist-reports.md) has been added.

        Parameters
        ----------
        dimensions
            The dimensions to use within the request.
        filters
            The filters to use within the request.
        metrics
            The metrics to use within the request. If none are provided,
            all supported metrics are used.
        sort_options
            The sort options to use within the request.

        Returns
        -------
        Report
            The generated report.

        Other Parameters
        ----------------
        start_date
            The date in which data should be pulled from. If this is
            not provided, this is set to 28 days before `end_date`.
        end_date
            The date in which data should be pulled to. If this is not
            provided, this is set to the current date.
        max_results
            The maximum number of results the report should include. If
            this is `0`, no upper limit is applied.
        currency
            The currency revenue data should be represented using. This
            should be an ISO 4217 currency code.
        start_index
            The first row in the report to include. This is one-indexed.
            If this is `1`, all rows are included.
        include_historical_data
            Whether to include data from before the current channel
            owner assumed control of the channel. You only need to worry
            about this is the current channel owner did not create the
            channel.

        Raises
        ------
        InvalidRequest
            Your request was invalid.
        BadRequest
            Your request was invalid, but it was not caught by
            analytix's verification systems.
        Unauthorised
            Your access token is invalid.
        Forbidden
            You tried to access data you're not allowed to access. If
            your channel is not partnered, this is raised when you try
            to access monetary data.

        Warnings
        --------
        * If your channel is not partnered, attempting to access
          monetary data will result in a `Forbidden` error. Ensure
          your scopes are set up correctly before calling this method.
        * The "isCurated" filter will stop working on 30 Jun 2024. See
          the [guide on new playlist reports](../guides/
          new-playlist-reports.md) for information on how to migrate.

        See Also
        --------
        You can learn more about dimensions, filters, metrics, and sort
        options by reading the [detailed guides](../guides/
        dimensions.md).

        Examples
        --------
        Fetching daily analytics data for 2022.

        >>> import datetime
        >>> shard.fetch_report(
        ...     dimensions=("day",),
        ...     start_date=datetime.date(2022, 1, 1),
        ...     end_date=datetime.date(2022, 12, 31),
        ... )

        Fetching 10 most watched videos over last 28 days.

        >>> shard.fetch_report(
        ...     dimensions=("video",),
        ...     metrics=("estimatedMinutesWatched", "views"),
        ...     sort_options=("-estimatedMinutesWatched",),
        ...     max_results=10,
        ... )
        """
        query = ReportQuery(
            dimensions,
            filters,
            metrics,
            sort_options,
            max_results,
            start_date,
            end_date,
            currency,
            start_index,
            include_historical_data,
        )
        query.validate(self._scopes)

        with self._request(query.url, token=self._tokens.access_token) as resp:
            data = json.loads(resp.data)

        assert query.rtype
        report = Report(data, query.rtype)
        _log.info("Created '%s' report of shape %s", query.rtype, report.shape)
        return report

    def fetch_groups(
        self,
        *,
        ids: Optional[Collection[str]] = None,
        next_page_token: Optional[str] = None,
    ) -> GroupList:
        """Fetch a list of analytics groups.

        Parameters
        ----------
        ids
            The IDs of groups you want to fetch. If none are provided,
            all your groups will be fetched.
        next_page_token
            If you need to make multiple requests, you can pass this to
            load a specific page. To check if you've arrived back at the
            first page, check the next page token from the request and
            compare it to the next page token from the first page.

        Returns
        -------
        GroupList
            An object containing the list of your groups and the next
            page token.

        Raises
        ------
        BadRequest
            Your request was invalid.
        Unauthorised
            Your access token is invalid.
        Forbidden
            You tried to access data you're not allowed to access. If
            your channel is not partnered, this is raised when you try
            to access monetary data.
        """
        query = GroupQuery(ids, next_page_token)
        with self._request(query.url, token=self._tokens.access_token) as resp:
            return GroupList.from_json(self, json.loads(resp.data))

    def fetch_group_items(self, group_id: str) -> GroupItemList:
        """Fetch a list of all items within a group.

        Parameters
        ----------
        group_id
            The ID of the group to fetch items for.

        Returns
        -------
        GroupItemList
            An object containing the list of group items and the next
            page token.

        Raises
        ------
        BadRequest
            Your request was invalid.
        Unauthorised
            Your access token is invalid.
        Forbidden
            You tried to access data you're not allowed to access. If
            your channel is not partnered, this is raised when you try
            to access monetary data.
        """
        query = GroupItemQuery(group_id)
        with self._request(query.url, token=self._tokens.access_token) as resp:
            return GroupItemList.from_json(json.loads(resp.data))

fetch_group_items 

fetch_group_items(group_id: str) -> GroupItemList

Fetch a list of all items within a group.

Parameters:

Name Type Description Default
group_id str

The ID of the group to fetch items for.

 required

Returns:

Type Description
GroupItemList

An object containing the list of group items and the next page token.

Raises:

Type Description
BadRequest

Your request was invalid.
Unauthorised

Your access token is invalid.
Forbidden

You tried to access data you're not allowed to access. If your channel is not partnered, this is raised when you try to access monetary data.
Source code in analytix/shard.py 
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
def fetch_group_items(self, group_id: str) -> GroupItemList:
    """Fetch a list of all items within a group.

    Parameters
    ----------
    group_id
        The ID of the group to fetch items for.

    Returns
    -------
    GroupItemList
        An object containing the list of group items and the next
        page token.

    Raises
    ------
    BadRequest
        Your request was invalid.
    Unauthorised
        Your access token is invalid.
    Forbidden
        You tried to access data you're not allowed to access. If
        your channel is not partnered, this is raised when you try
        to access monetary data.
    """
    query = GroupItemQuery(group_id)
    with self._request(query.url, token=self._tokens.access_token) as resp:
        return GroupItemList.from_json(json.loads(resp.data))

fetch_groups 

fetch_groups(*, ids: Optional[Collection[str]] = None, next_page_token: Optional[str] = None) -> GroupList

Fetch a list of analytics groups.

Parameters:

Name Type Description Default
ids Optional[Collection[str]]

The IDs of groups you want to fetch. If none are provided, all your groups will be fetched.

 None
next_page_token Optional[str]

If you need to make multiple requests, you can pass this to load a specific page. To check if you've arrived back at the first page, check the next page token from the request and compare it to the next page token from the first page.

 None

Returns:

Type Description
GroupList

An object containing the list of your groups and the next page token.

Raises:

Type Description
BadRequest

Your request was invalid.
Unauthorised

Your access token is invalid.
Forbidden

You tried to access data you're not allowed to access. If your channel is not partnered, this is raised when you try to access monetary data.
Source code in analytix/shard.py 
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
def fetch_groups(
    self,
    *,
    ids: Optional[Collection[str]] = None,
    next_page_token: Optional[str] = None,
) -> GroupList:
    """Fetch a list of analytics groups.

    Parameters
    ----------
    ids
        The IDs of groups you want to fetch. If none are provided,
        all your groups will be fetched.
    next_page_token
        If you need to make multiple requests, you can pass this to
        load a specific page. To check if you've arrived back at the
        first page, check the next page token from the request and
        compare it to the next page token from the first page.

    Returns
    -------
    GroupList
        An object containing the list of your groups and the next
        page token.

    Raises
    ------
    BadRequest
        Your request was invalid.
    Unauthorised
        Your access token is invalid.
    Forbidden
        You tried to access data you're not allowed to access. If
        your channel is not partnered, this is raised when you try
        to access monetary data.
    """
    query = GroupQuery(ids, next_page_token)
    with self._request(query.url, token=self._tokens.access_token) as resp:
        return GroupList.from_json(self, json.loads(resp.data))

fetch_report 

fetch_report(*, dimensions: Optional[Collection[str]] = None, filters: Optional[Dict[str, str]] = None, metrics: Optional[Collection[str]] = None, sort_options: Optional[Collection[str]] = None, start_date: Optional[dt.date] = None, end_date: Optional[dt.date] = None, max_results: int = 0, currency: str = 'USD', start_index: int = 1, include_historical_data: bool = False) -> Report

Fetch an analytics report.

Changed in version 5.0

This used to be retrieve_report.

Changed in version 5.2

Support for new playlst reports has been added.

Parameters:

Name Type Description Default
dimensions Optional[Collection[str]]

The dimensions to use within the request.

 None
filters Optional[Dict[str, str]]

The filters to use within the request.

 None
metrics Optional[Collection[str]]

The metrics to use within the request. If none are provided, all supported metrics are used.

 None
sort_options Optional[Collection[str]]

The sort options to use within the request.

 None

Returns:

Type Description
Report

The generated report.

Other Parameters:

Name Type Description
start_date Optional[date]

The date in which data should be pulled from. If this is not provided, this is set to 28 days before end_date.
end_date Optional[date]

The date in which data should be pulled to. If this is not provided, this is set to the current date.
max_results int

The maximum number of results the report should include. If this is 0, no upper limit is applied.
currency str

The currency revenue data should be represented using. This should be an ISO 4217 currency code.
start_index int

The first row in the report to include. This is one-indexed. If this is 1, all rows are included.
include_historical_data bool

Whether to include data from before the current channel owner assumed control of the channel. You only need to worry about this is the current channel owner did not create the channel.

Raises:

Type Description
InvalidRequest

Your request was invalid.
BadRequest

Your request was invalid, but it was not caught by analytix's verification systems.
Unauthorised

Your access token is invalid.
Forbidden

You tried to access data you're not allowed to access. If your channel is not partnered, this is raised when you try to access monetary data.
Warnings
  • If your channel is not partnered, attempting to access monetary data will result in a Forbidden error. Ensure your scopes are set up correctly before calling this method.
  • The "isCurated" filter will stop working on 30 Jun 2024. See the guide on new playlist reports for information on how to migrate.
See Also

You can learn more about dimensions, filters, metrics, and sort options by reading the detailed guides.

Examples:

Fetching daily analytics data for 2022.

>>> import datetime
>>> shard.fetch_report(
...     dimensions=("day",),
...     start_date=datetime.date(2022, 1, 1),
...     end_date=datetime.date(2022, 12, 31),
... )

Fetching 10 most watched videos over last 28 days.

>>> shard.fetch_report(
...     dimensions=("video",),
...     metrics=("estimatedMinutesWatched", "views"),
...     sort_options=("-estimatedMinutesWatched",),
...     max_results=10,
... )
Source code in analytix/shard.py 
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
def fetch_report(
    self,
    *,
    dimensions: Optional[Collection[str]] = None,
    filters: Optional[Dict[str, str]] = None,
    metrics: Optional[Collection[str]] = None,
    sort_options: Optional[Collection[str]] = None,
    start_date: Optional[dt.date] = None,
    end_date: Optional[dt.date] = None,
    max_results: int = 0,
    currency: str = "USD",
    start_index: int = 1,
    include_historical_data: bool = False,
) -> Report:
    """Fetch an analytics report.

    ???+ note "Changed in version 5.0"
        This used to be `retrieve_report`.

    ???+ note "Changed in version 5.2"
        Support for [new playlst reports](../guides/
        new-playlist-reports.md) has been added.

    Parameters
    ----------
    dimensions
        The dimensions to use within the request.
    filters
        The filters to use within the request.
    metrics
        The metrics to use within the request. If none are provided,
        all supported metrics are used.
    sort_options
        The sort options to use within the request.

    Returns
    -------
    Report
        The generated report.

    Other Parameters
    ----------------
    start_date
        The date in which data should be pulled from. If this is
        not provided, this is set to 28 days before `end_date`.
    end_date
        The date in which data should be pulled to. If this is not
        provided, this is set to the current date.
    max_results
        The maximum number of results the report should include. If
        this is `0`, no upper limit is applied.
    currency
        The currency revenue data should be represented using. This
        should be an ISO 4217 currency code.
    start_index
        The first row in the report to include. This is one-indexed.
        If this is `1`, all rows are included.
    include_historical_data
        Whether to include data from before the current channel
        owner assumed control of the channel. You only need to worry
        about this is the current channel owner did not create the
        channel.

    Raises
    ------
    InvalidRequest
        Your request was invalid.
    BadRequest
        Your request was invalid, but it was not caught by
        analytix's verification systems.
    Unauthorised
        Your access token is invalid.
    Forbidden
        You tried to access data you're not allowed to access. If
        your channel is not partnered, this is raised when you try
        to access monetary data.

    Warnings
    --------
    * If your channel is not partnered, attempting to access
      monetary data will result in a `Forbidden` error. Ensure
      your scopes are set up correctly before calling this method.
    * The "isCurated" filter will stop working on 30 Jun 2024. See
      the [guide on new playlist reports](../guides/
      new-playlist-reports.md) for information on how to migrate.

    See Also
    --------
    You can learn more about dimensions, filters, metrics, and sort
    options by reading the [detailed guides](../guides/
    dimensions.md).

    Examples
    --------
    Fetching daily analytics data for 2022.

    >>> import datetime
    >>> shard.fetch_report(
    ...     dimensions=("day",),
    ...     start_date=datetime.date(2022, 1, 1),
    ...     end_date=datetime.date(2022, 12, 31),
    ... )

    Fetching 10 most watched videos over last 28 days.

    >>> shard.fetch_report(
    ...     dimensions=("video",),
    ...     metrics=("estimatedMinutesWatched", "views"),
    ...     sort_options=("-estimatedMinutesWatched",),
    ...     max_results=10,
    ... )
    """
    query = ReportQuery(
        dimensions,
        filters,
        metrics,
        sort_options,
        max_results,
        start_date,
        end_date,
        currency,
        start_index,
        include_historical_data,
    )
    query.validate(self._scopes)

    with self._request(query.url, token=self._tokens.access_token) as resp:
        data = json.loads(resp.data)

    assert query.rtype
    report = Report(data, query.rtype)
    _log.info("Created '%s' report of shape %s", query.rtype, report.shape)
    return report