Skip to content

About

Tiny, dependency-free TypeScript client for the YouTube Data API v3 — channel resolution, quota-aware batching, video & channel stats.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

1 Commit

Folders and files

Repository files navigation

@vidfora/youtube-api

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.

Install

npm install @vidfora/youtube-api

You'll need a YouTube Data API v3 key from the Google Cloud console.

Quick start

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");

API

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.

Quota

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.

Handling quota errors

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;
  }
}

Custom fetch

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 });

License

MIT

About

Tiny, dependency-free TypeScript client for the YouTube Data API v3 — channel resolution, quota-aware batching, video & channel stats.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages