Intro to the YouTube APIs: searching for videos

TL;DR:

Sure, you may be using data APIs from Google Cloud (GCP), utility APIs from Google Workspace (GWS), or AI/ML APIs from GCP or Google AI, but at some point, you may want to programmatically interact with the YouTube platform, whether you're talking videos, playlists, data & analytics, captions, or livestreams. Today's post introduces those YouTube APIs and gives you an idea of what you can do with them, so stick around to learn more!

Introduction

Welcome to the blog that covers everything you need to know about using Google APIs, whether they're hot topics, corners of Google you've never explored before, or other insightful content that you'll not likely find in any developer documentation from Google. You'll find content here diving into authorization schemes like API keys and OAuth client IDs. Readers get to explore product families like Google Cloud (GCP), which features Vertex AI/ML "building block" APIs and serverless platforms like Google App Engine.

Beyond Cloud, you may want to explore automating office productivity tools like those in Google Workspace (GWS), featuring the Google Docs API. Curious about the Geocoding, Time Zone, and Directions APIs found in the Google Maps Platform (GMP)? I've got you covered as well. And since generative AI is everywhere these days, you'll find content on the Gemini API as well!

This post introduces another product group, YouTube, its APIs, and how you can do those things advertised above in the TL;DR. The samples featured below demonstrate use of the YouTube Data API querying for (public) videos on the platform.

📝 NOTE: Seen this sample before?
The same sample is featured in another post on API keys in case it seems familiar. If you saw that, this is where you'll dive deeper, and if you're new to YouTube APIs, welcome! Regardless of whether you've seen this sample, review the posts on using API keys first because you'll be using them here.

YouTube APIs

While Cloud/GCP and Workspace/GWS get a lot of attention on this blog because I focus on those products, it's sometimes fun to explore other Google products like Maps, Firebase, and today, YouTube. YouTube provides several APIs for developers who want to access or manage video content:

YouTube API	Description
Data	First & original YouTube API allowing developers to query YouTube content, upload videos, create and manage playlists, and more
Analytics & Reporting	Lets developers & content creators better understand their viewers and how they interact with your channel and videos
Livestream	Allows developers to set up and manage YouTube broadcasts/livestreams

Authentication and authorization

Your app's end-users need to log in to Google (federated sign-on is also supported). Once authenticated, they must authorize/grant you (and your app) access to their data via the API(s) your code uses. Learn more about authentication and authorization from the first post on Google API usage. That post helps you differentiate the three supported credentials types: API keys, OAuth client IDs, and service accounts. Also see the "Authentication methods at Google" page in the documentation.

In this "Hello World!" introduction to YouTube APIs, you'll see an app that searches for public content: published/listed and non-private videos on YouTube. Querying for public data only requires API keys. Accessing (human) user-owned data such as playlists requires authorized access, and that'll be covered in future posts. For now, let's get started with public queries.

☝️ COST: YouTube APIs free to use
Billing is not required for YouTube APIs, meaning it's "free" up to certain limits/quotas. This page also features a link to request additional quota if your usage grows beyond the defaults. YouTube also provides a quota calculator to help you gauge usage.

Prerequisites

The first step is to complete the Google developer project requirements:

Go to the cloud console ("CloudConsole") and...
- Create a new developer project or select an existing one.
Go to developers' console ("DevConsole"), specifically its credentials page
- Select an existing API key or click + Create Credentials for a new one.
Save API key to a local file (see below; after creation, may have to refresh page and click Show key)
- Node.js: Save as API_KEY = YOUR_API_KEY to .env
- Python: Save as API_KEY = 'YOUR_API_KEY' to settings.py, or alternatively, save as .env and use python-dotenv to more closely mirror Node.js version

The next step is to enable APIs as most are disabled by default. Here are three common ways to enable APIs:

DevConsole manually -- Enable the API manually from the DevConsole by following these steps:
- Go to DevConsole
- Click on Library tab in the left-nav; search for "YouTube", select "YouTube Data API" (v3), and enable
DevConsole link -- You may be new to Google APIs or don't have experience enabling APIs manually in the DevConsole. If this is you...
- Check out the API listing page to learn more about the API and enable it from there.
- Alternatively, skip the API info and click this link for the enable button.
Command-line (gcloud) -- Those who prefer working in a terminal can enable APIs with a single command in the Cloud Shell or locally on your computer if you installed the Cloud SDK which includes the gcloud command-line tool (CLI) and initialized its use.
- If this is you, issue this command to enable the API: gcloud services enable youtube.googleapis.com
- Confirm all the APIs you've enabled with this command: gcloud services list

Using Google APIs means you need the appropriate client libraries. Install the required packages with the following commands:

Node.js: npm i dotenv googleapis
Python: pip install -U pip google-api-python-client (or pip3)

Confirm the client libraries installed correctly by running the following commands and observing no error output:

Node.js: node -e "require('googleapis')"
Python: python -c "import googleapiclient"

Similar steps can also be found in the documentation. When set, you're ready to look at code.

Google APIs require credentials and authorization
Before apps can access Google APIs, it needs to have appropriate credentials. The one you need depends on the API and what kind of data it accesses. But even if you have those credentials, your app still needs to be authorized to make API calls.

If it's an API key like in our example, it has to be a valid API key, serving as both credentials as well as the authorization mechanism.

If it's OAuth client ID, your users must authorize or give you/your app permission to access their data, with those permissions represented by OAuth2 scopes.

If it's a service account, that service account must have the proper role(s), and its public-private key-pair should have the appropriate IAM permissions.

Searching YouTube for videos

As discussed, APIs accessing public data such as videos on YouTube only need API key credentials. Of course, videos can be published but set as private and unlisted, and those won't show up. Only public videos are returned by the API. (Learn more about video settings on the YouTube privacy help page.)

Beyond the prerequisites executed above, use of Google APIs in code requires:

Importing one or more client libraries
Creating API clients

To use the client libraries to create API clients, beyond the credentials, your app also needs to be authorized (see sidebar above). Only once you have both will you be able to call APIs, and you'll see this "boilerplate" in all the code samples. Let's start with Python.

Python

The yt_video_query.py Python script is available in the repo:

from __future__ import print_function
from googleapiclient import discovery
from settings import API_KEY

QUERY = 'python -snake'
YOUTUBE = discovery.build('youtube', 'v3', developerKey=API_KEY)

print('\n** Searching for %r videos...' % QUERY)
res = YOUTUBE.search().list(q=QUERY, type='video',
        part='id,snippet').execute().get('items', [])
for item in res:
    print('http://youtu.be/%s\t%s' % (
            item['id']['videoId'], item['snippet']['title'][:48]))

The imports at the top...

Ensure Python 2-compatibility (replaces 2.x print statement with 3.x print() function)
Bring in Google APIs client library functionality
Fetch API key you saved locally

After setting a generic query for Python videos (but only those without a snake), the client library is used to create an API endpoint for v3 of the YouTube Data API. If you did not provide an actual and valid API key, the script will throw an exception, and execution terminates. If all goes well, execution moves to the main part of the application where YouTube is queried via API, specifically the list() method (part of the search collection of methods).

The list() method defaults to returning (at most) five videos that match your query. Pass in a maxResults parameter to change that... it accepts values from one to fifty. Two other parameters that you do see are q for the query and type indicating the YouTube content you're querying for. Another important parameter for list() is part, which gets a comma-separated value, 'id, snippet'.

The API can access different groups of fields, and part asks for only the id and snippet field groups. Videos are identified by ID strings, and those are found in the id group, and video titles are in the snippet group. Those are the resulting values displayed (if there are results). Learn more in the list() method documentation as well as the guide on using the part parameter.

When the API call to list() with these parameters returns via the response's items field, the resulting payload is looped over and displayed. For each video, its ID, extracted from the id group of fields via videoId, is assembled into a short link and displayed along with the first forty-eight (48) characters of the video title, extracted from the snippet group. Here's the output I got running this script shortly after I got it working:

$ python yt_video_query.py

** Searching for 'python -snake' videos...
http://youtu.be/rfscVS0vtbw     Learn Python - Full Course for Beginners [Tutori
http://youtu.be/_uQrJ0TkZlc     Python Tutorial - Python for Beginners [Full Cou
http://youtu.be/G2q6PUUDdRw     Crear un VIDEOJUEGO con PYTHON en 10 minutos | ¿
http://youtu.be/SjKEV8sDIAA     CS50 2021 - Lecture 6 - Python
http://youtu.be/t8pPdKYpowI     Python Tutorial for Beginners - Learn Python in

Your output will likely vary as YouTube contents change often. As the script is Python 2 & 3-compatible, you'll see similar output regardless of which version you run. Feel free to explore other queries that suit your interest(s). Now let's look at JavaScript.

Node.js

The yt_video_query.js CommonJS script is also available in the repo and is behaviorally identical to its Python cousin:

require('dotenv').config();
const {google} = require('googleapis');

const QUERY = 'python -snake';
const YOUTUBE = google.youtube({ version: 'v3', auth: process.env.API_KEY });

async function listVideos() {
  console.log(`\n** Searching for '${QUERY} videos...`);
  const vids = await YOUTUBE.search.list({ part: 'id,snippet', q: QUERY, type: 'video' });
  vids.data.items.forEach(vid => {
    console.log(`http://youtu.be/${vid.id.videoId}\t${vid.snippet.title.substring(0, 48)}`);
  });
}

listVideos().catch(console.error);

The first part sets things up, imports the Google APIs client library, creates a constant for the search QUERY, and instantiates the API client with the help of the dotenv package that reads API_KEY from the .env you saved. After initialization, the async function is called with an exception catch to the console. It passes the query to the list() API call along with the same parameters and displays the results, all just like the Python version. However, since I built this one well after Python's, running it produced different output, although some of the videos are the same:

$ node yt_video_query.js

** Searching for 'python -snake videos...
http://youtu.be/kqtD5dpn9C8     Python for Beginners - Learn Python in 1 Hour
http://youtu.be/b093aqAZiPU     👩‍💻 Python for Beginners Tutorial
http://youtu.be/_uQrJ0TkZlc     Python Tutorial - Python Full Course for Beginne
http://youtu.be/rfscVS0vtbw     Learn Python - Full Course for Beginners [Tutori
http://youtu.be/t8pPdKYpowI     Python Tutorial for Beginners - Learn Python in

For those who prefer a modern ECMAscript module, a few tweaks swapping require()s for imports are all you need to come up with an equivalent .mjs sibling, also in the repo:

import 'dotenv/config';
import { google } from 'googleapis';

const QUERY = 'python -snake';
const YOUTUBE = google.youtube({ version: 'v3', auth: process.env.API_KEY });

async function listVideos() {
  console.log(`\n** Searching for '${QUERY} videos...`);
  const vids = await YOUTUBE.search.list({ part: 'id,snippet', q: QUERY, type: 'video' });
  vids.data.items.forEach(vid => {
    console.log(`http://youtu.be/${vid.id.videoId}\t${vid.snippet.title.substring(0, 48)}`);
  });
}

listVideos().catch(console.error);

The output will be similar to the others, and an optional conversion to TypeScript should be straightforward. With that, your intro to the YouTube APIs, featuring its Data API, is now complete.

Summary and next steps

While it's great that you now have code that searches for YouTube videos, it's limiting in terms of what kinds of apps you can build with it. More than likely, you'll want to create something more ambitious, needing to leverage other functionality found in YouTube APIs. You may want to build apps that translate closed captions, analyze the efficacy of your content, or manage playlists or livestreams. For this functionality, an API key no longer suffices.

API keys are fine when querying public data like videos, but playlists and video captions are not public data... they belong to a user, the owner of the playlist or content creator, respectively. Accessing this data requires user authorization, meaning OAuth client IDs. In the next post in this YouTube API series, we'll explore authorized access and other YouTube functionality, so stay tuned for that.

If you found an error in this post, bug in the code, or have a topic you want me to cover in the future, drop a note in the comments below or file an issue at the repo. Thanks for reading, and I hope to meet you if I come through your community... see the travel calendar on my consulting page.

References

Below are various resources related to this post which you may find useful.

Blog post code samples

YouTube Data API

General YouTube APIs

Google APIs client libraries

Other Google APIs using API keys

Gemini API (post series)
Google Maps APIs (post)
AI-enhanced text processing (post; GCP Cloud Natural Language & Cloud Translation APIs)

Blog