A tiny, dependency-free TypeScript client for the YouTube Data API v3.
It handles the parts you otherwise re-solve every time:
- Resolve a channel from any input — a
UC…id, an@handle, a legacy/user/…name, or a/c/…vanity URL — with a search fallback for the vanity URLs no cheap lookup resolves. - Fetch video & channel statistics, batched 50 ids per request.
- Parse ISO-8601 durations and infer Shorts from length.
- Detect "out of quota" distinctly, so you can back off gracefully.
Zero runtime dependencies. Ships ESM + type declarations. Works on Node ≥ 18 (global fetch), or bring your own fetch.
npm install @vidfora/youtube-apiYou'll need a YouTube Data API v3 key from the Google Cloud console.
import { createYouTubeClient } from "@vidfora/youtube-api";
const yt = createYouTubeClient({ apiKey: process.env.YOUTUBE_API_KEY });
// Resolve a channel and pull its recent uploads (~3 quota units).
const { channel, videos } = await yt.getChannel("@mkbhd");
console.log(channel.name, channel.subscribers);
for (const v of videos) {
console.log(v.title, v.views, v.isShort ? "(Short)" : "");
}getChannel accepts any of these interchangeably:
await yt.getChannel("@mkbhd");
await yt.getChannel("UCBJycsmduvYEL83R_U4JriQ");
await yt.getChannel("https://www.youtube.com/@mkbhd");
await yt.getChannel("https://www.youtube.com/c/mkbhd");const yt = createYouTubeClient(options);options — { apiKey?, fetch?, timeoutMs?, shortMaxSeconds?, descriptionMaxLength? }. apiKey falls back to process.env.YOUTUBE_API_KEY; fetch defaults to the global; timeoutMs is 15000; shortMaxSeconds is 60; descriptions are untruncated unless you set descriptionMaxLength.
| Method | Cost | Returns |
|---|---|---|
resolveChannel(input) |
1 unit (+100 on vanity fallback) | YouTubeChannel |
getChannel(input, { maxVideos? }) |
~3 units | { channel, videos } |
getVideos(ids) |
1 unit / 50 ids | YouTubeVideo[] |
getChannelSubscribers(ids) |
1 unit / 50 ids | Map<id, number | null> |
searchVideos(query, { searchN?, fetchN? }) |
~102 units | YouTubeVideo[] |
Also exported: isQuotaError(err), parseChannelRef(input), the YouTubeApiError class, and the YouTubeChannel / YouTubeVideo / ChannelAnalysis types.
The API is free; the daily quota is the real cost (default 10,000 units/day):
channels.list/playlistItems.list/videos.list= 1 unit each (up to 50 ids/call)search.list= 100 units
So a channel analysis is ~3 units (thousands/day), while a topic search is ~102 units (~80/day). Budget searchVideos accordingly.
import { createYouTubeClient, isQuotaError } from "@vidfora/youtube-api";
try {
await yt.searchVideos("mechanical keyboards");
} catch (err) {
if (isQuotaError(err)) {
// out of daily quota — back off / serve cached results
} else {
throw err;
}
}Any runtime without a global fetch, or when you need a proxy/interceptor:
import { createYouTubeClient } from "@vidfora/youtube-api";
import { fetch as undiciFetch } from "undici";
const yt = createYouTubeClient({ apiKey, fetch: undiciFetch });MIT