Import YouTube Analytics Data to Google Sheets

This guide will show how to pull private YouTube video data (data you need to be logged in to view) directly into Google Sheets, using the API Connector add-on for Sheets.

In general, YouTube's Public Data API is better developed and easier to work with than their Analytics API, so if you only need simple data like views, comments, and likes, I suggest checking this article instead! But if you want private video metrics for your own channel, like average watch time, views by date, and demographic breakdowns, read on for a step-by-step guide to the YouTube Analytics API.

Contents

• Before You Begin
• Part 1: Connect to the YouTube Analytics API
• Part 2: Create a YouTube Analytics API Request URL
• Part 3: Pull YouTube Analytics API Data into Sheets
• Part 4: More Example API URLs
• Part 5: Handle Pagination
• Part 6: YouTube Compliance
• Part 7: API Documentation

Before You Begin

Click here to install the API Connector add-on from the Google Marketplace.

Part 1: Connect to the YouTube API

If you haven’t connected API Connector to YouTube Analytics before, you’ll first need to initiate the connection as follows:

1. Open up Google Sheets and click Extensions > API Connector > Manage Connections.
2. In the list of available connections, find YouTube and click Connect.
   
   
3. You will see a couple of screens asking you to log in and approve the connection. Click Allow.
   
4. You'll now be returned to your Google Sheet, and can verify that your YouTube connection is active in the Connections screen.
   

Part 2: Create a YouTube Analytics API Request URL

For our first request, we'll get some basic stats about your YouTube channel.

Again, the YouTube Analytics API only lets you query your own data. If you're looking for public YouTube data like view and comment counts for other videos, you'll need the YouTube Public Data API.

• API root: https://youtubeanalytics.googleapis.com
• Endpoint: /v2/reports
• Parameters: ?dimensions=video&sort=-views&metrics=estimatedMinutesWatched,views,likes,subscribersGained&ids=channel==MINE&startDate=2021-01-01&endDate=2021-12-31&maxResults=200

Putting it together, we get the full API Request URL.

https://youtubeanalytics.googleapis.com/v2/reports?dimensions=video&sort=-views&metrics=estimatedMinutesWatched,views,likes,subscribersGained&ids=channel==MINE&startDate=2021-01-01&endDate=2021-12-31&maxResults=200

Part 3: Pull YouTube Analytics API Data into Sheets

Now let's grab that YouTube data.

1. In the Create Request interface, enter the Request URL we just created.
   
2. Under OAuth, choose YouTube from the Connections dropdown. You should see a "Connected" badge.
   
3. We don't need any headers for this API, so just leave that section blank.
4. Create a new tab and click Set current to use that tab as your data destination.
5. The YouTube Analytics API outputs data in a pretty inconvenient format (it returns all the field headers in their own array, then all the data separately), so let's clean it up a bit with some JMESPath. Under Output options > JMESPath, enter {Keys:columnHeaders[].name,rows:rows}
   
6. Name your request and click Run. A moment later you’ll see some statistics about your videos populate your sheet.
   
7. By default, the field headers come through as numbers. To give those headers names instead, click Edit Fields to open the visual field editor. The field names are provided in the first few columns of the response output, so you can just substitute those in (and then hide those extra columns to tidy up your report).
   

Part 4: More Example API URLs

You can access the full YouTube Analytics API documentation here, but if you just want to get started, you can try the following URLs (one at a time).

• Aggregated metrics for a channel

  https://youtubeanalytics.googleapis.com/v2/reports?metrics=views,comments,likes,dislikes,estimatedMinutesWatched,averageViewDuration&ids=channel==MINE&startDate=2021-01-01&endDate=2021-12-31&maxResults=200

• Most watched videos for your channel

  https://youtubeanalytics.googleapis.com/v2/reports?dimensions=video&metrics=estimatedMinutesWatched,views,likes,subscribersGained&maxResults=10&sort=-estimatedMinutesWatched&startDate=2021-01-01&endDate=2021-12-31&maxResults=200&ids=channel==MINE

• Metrics summarized by month

  https://youtubeanalytics.googleapis.com/v2/reports?dimensions=month&metrics=views,estimatedMinutesWatched,averageViewDuration,averageViewPercentage,subscribersGained&sort=month&startDate=2021-01-01&endDate=2021-12-31&ids=channel==MINE

• Demographic breakdown

  https://youtubeanalytics.googleapis.com/v2/reports?dimensions=ageGroup,gender&metrics=viewerPercentage&startDate=2021-01-01&endDate=2021-12-31&ids=channel==MINE

• View counts and watch time by traffic source

  https://youtubeanalytics.googleapis.com/v2/reports?dimensions=day,insightTrafficSourceType&metrics=views,estimatedMinutesWatched&sort=day&startDate=2021-01-01&endDate=2021-12-31&ids=channel==MINE

Many additional sample queries are provided in YouTube's list of sample requests. In addition, they provide an API Explorer tool that simplifies the process of testing and constructing queries.

Part 5: Handle Pagination

Let's get it out of the way immediately, this section doesn't contain a real way to handle pagination. You can add maxResults=200 to the end of your API request URL, but after testing and searching through documentation, it seems that this API doesn't support paginating through results to retrieve more than 200 records at a time. If you have more than 200 videos, you can try using the filters parameter to break your data into chunks such that it can be retrieved in groups of less than 200 at a time, and then run those request URLs separately.

For example, a request filtered by video ID would include filters=video==<list of video IDs>, like this:

https://youtubeanalytics.googleapis.com/v2/reports?dimensions=video&metrics=views,estimatedMinutesWatched,likes,dislikes,averageViewPercentage,averageViewDuration&sort=-views&maxResults=200&ids=channel==MINE&startDate=2020-01-01&endDate=2021-12-31&filters=video==fbY6r12Kyyo,n84bsqaer-g,ik2uk5pHyEA,XxYv3LIJtmo

Beyond that, you would need to get clever with sorting, or just use the YouTube Public Data API instead, which does support pagination. Of course, if you find any solutions I've missed, please leave a comment below.

Part 6: YouTube Compliance

To comply with the terms of YouTube's API, requests are subject to the following conditions:

1. All saved requests to YouTube will refresh every 30 days, even if you have not set up a scheduled refresh.
2. All YouTube requests will show only the metric name rather than the full path in the header row.

Relevant Terms:

“API Clients may store all other types of Authorized Data not identified in section (III.E.4.b) for as long as is necessary for the purposes of the specific consent granted by an active user and for no longer than 30 calendar days. After 30 calendar days, the API Client must either delete or refresh the stored data”. (link)

"Your API Clients must not (i) replace API Data with similar, independently calculated data, or (ii) access or use API Data to create new or derived data or metrics." (link)

Part 7: API Documentation

YouTube provides several different APIs for extracting data from the platform:

• The YouTube Analytics API (the subject of this article) allows you to query private statistics about your channel, like video watch times and demographic breakdowns. Documentation: https://developers.google.com/youtube/analytics/data_model
• The YouTube Public Data API allows you to retrieve lists of content based on search parameters. It also provides some basic statistics like views, likes, comment counts, and subscriber counts, for all public videos. Documentation: https://developers.google.com/youtube/v3/docs
• The YouTube Reporting API is focused on reporting, and provides bulk reports of YouTube analytics data for your own channel, including detailed metrics and ad performance reports. Unlike the Analytics API, it doesn't provide filtering and sorting parameters, as these reports are designed to be downloaded and stored in a data warehouse, where you can then query the data yourself. (This table provides a summary of the differences between YouTube's Reporting and Analytics APIs). Documentation: https://developers.google.com/youtube/reporting/v1/reports