YouTube API Client

A TypeScript client library for the YouTube API. This library provides easy access to YouTube search, video details, channel information, and trending content.

Installation

Install the package using npm:

npm install youtube-api-v2

Quick Start

import { YouTubeClient } from "youtube-api-v2";

// Initialize the client with your API key
// Get your API key from: https://rapidapi.com/zilodata12-zilodata-default/api/youtube-scraper-api-v21
const client = new YouTubeClient({
  apiKey: "your-api-key-here",
});

// Search for videos
const searchResults = await client.explore.search({
  keyword: "funny videos",
  gl: "US",
  hl: "en",
});

// Get video details
const videoDetails = await client.video.getDetail({
  videoId: "kJQP7kiw5Fk",
});

// Get channel information
const channelInfo = await client.channel.getDetail({
  channelId: "UCxoq-PAQeAdk_zyg8YS0JqA",
});

Configuration

Configure the YouTube client with your API credentials:

const client = new YouTubeClient({
  apiKey: "your-api-key", // Required: Your API subscription key
  timeout: 30000, // Optional: Request timeout in milliseconds (default: 30000)
});

Get your API key: RapidAPI - YouTube Scraper API API Documentation: ZiloData API Docs :::note The API endpoint is hardcoded and cannot be changed. :::

API Structure

The library is organized into modules, each providing specific functionality:

YouTubeClient
├── explore
│   ├── search(keyword, gl?, hl?, uploadDate?, type?, continuation?)
│   └── suggestions(keyword, gl?, hl?)
├── video
│   ├── getDetail(videoId, gl?, hl?)
│   ├── getComments(videoId, sortBy?, continuation?, gl?, hl?)
│   └── getReplyComments(continuation, gl?, hl?)
├── channel
│   ├── getDetail(channelId, gl?, hl?)
│   ├── getVideos(channelId, continuation?, gl?, hl?)
│   ├── getPlaylists(channelId, continuation?, gl?, hl?)
│   ├── getReleases(channelId, continuation?, gl?, hl?)
│   ├── getPosts(channelId, continuation?, gl?, hl?)
│   ├── getShorts(channelId, continuation?, gl?, hl?)
│   ├── getStore(channelId, continuation?, gl?, hl?)
│   └── search(channelId, keyword, continuation?, gl?, hl?)
└── trending
    ├── getVideo(countryCode?, gl?, hl?)
    ├── getTopVideo(filterByType?, filterByDate?, countryCode?, gl?, hl?)
    ├── getSong(countryCode?, filterByDate?, gl?, hl?)
    ├── getArtist(countryCode?, filterByDate?, gl?, hl?)
    └── getTopShortSong(countryCode?, filterByType?, filterByDate?, gl?, hl?)

API Reference

Explore Module

The explore module provides search and suggestion functionality for discovering YouTube content.

Search

Search for videos, movies, and other content on YouTube. Method: client.explore.search() Parameters:

Parameter	Type	Required	Description
`keyword`	`string`	Yes	Search keyword
`gl`	`string`	No	Geo location code (e.g., “US”)
`hl`	`string`	No	Language code (e.g., “en”)
`uploadDate`	`"1_HOUR_AGO" \| "TODAY" \| "THIS_WEEK" \| "THIS_MONTH" \| "THIS_YEAR"`	No	Filter by upload date
`type`	`"VIDEO" \| "MOVIE"`	No	Content type filter
`continuation`	`string`	No	Pagination token

Example:

await client.explore.search({
  keyword: "funny videos",
  gl: "US", // Optional: Geo location code
  hl: "en", // Optional: Language code
  uploadDate: "THIS_WEEK", // Optional
  type: "VIDEO", // Optional
  continuation: "token", // Optional: For pagination
});

Example Response:

{
  "message": "Success",
  "statusCode": 200,
  "pagination": {
    "total": 100,
    "hasMore": true,
    "continuation": "CDsQ8FsiEwje95_F1pmRAxXlsykDHUX"
  },
  "data": {
    "contents": [
      {
        "author": {
          "avatar": {
            "url": "https://yt3.ggpht.com/Lw8D7ol21pLxWEDvnIwcV0DsXIA1d_6DK4_wlkTtaP7SEGBg-2FLRDvs57NPnE1DcNarWPkQpvs=s88-c-k-c0x00ffffff-no-rj",
            "width": 68,
            "height": 68
          },
          "badges": [
            {
              "type": "AUDIO_BADGE",
              "text": "Official Artist Channel"
            }
          ],
          "name": "Luis Fonsi"
        },
        "videoId": "kJQP7kiw5Fk",
        "channelId": "UCxoq-PAQeAdk_zyg8YS0JqA",
        "thumbnails": [
          {
            "url": "https://i.ytimg.com/vi/kJQP7kiw5Fk/hq720.jpg",
            "width": 360,
            "height": 202
          }
        ],
        "publishedTimeText": "8 years ago",
        "title": "Luis Fonsi - Despacito ft. Daddy Yankee",
        "views": 8871198622,
        "duration": "4:42",
        "url": "https://www.youtube.com/watch?v=kJQP7kiw5Fk"
      }
    ],
    "refinements": ["video", "music", "image"]
  }
}

Suggestions

Get search suggestions based on a keyword to help users discover related content. Method: client.explore.suggestions() Parameters:

Parameter	Type	Required	Description
`keyword`	`string`	Yes	Search keyword
`gl`	`string`	No	Geo location code
`hl`	`string`	No	Language code

Example:

await client.explore.suggestions({
  keyword: "funny videos",
  gl: "US", // Optional
  hl: "en", // Optional
});

Example Response:

{
  "message": "Success",
  "statusCode": 200,
  "data": [
    "funny videos",
    "funny videos try not to laugh",
    "funny videos 2025",
    "funny videos for kids",
    "funny videos animals",
    "funny videos impossible",
    "funny videos clean",
    "funny videos on youtube",
    "funny videos cats",
    "funny videos peppa pig",
    "funny videos dogs",
    "funny videos baby",
    "funny videos shorts",
    "funny videos bluey"
  ]
}

Video Module

The video module provides comprehensive access to video details, comments, and replies.

Get Detail

Get detailed information about a YouTube video including metadata, statistics, and download links. Method: client.video.getDetail() Parameters:

Parameter	Type	Required	Description
`videoId`	`string`	Yes	YouTube video ID
`gl`	`string`	No	Geo location code
`hl`	`string`	No	Language code

Example:

await client.video.getDetail({
  videoId: "kJQP7kiw5Fk",
  gl: "US", // Optional
  hl: "en", // Optional
});

Example Response:

{
  "message": "Success",
  "statusCode": 200,
  "data": {
    "videoId": "kJQP7kiw5Fk",
    "title": "Luis Fonsi - Despacito ft. Daddy Yankee",
    "description": "Official video for \"Despacito\" by Luis Fonsi featuring Daddy Yankee",
    "author": {
      "id": "UCxoq-PAQeAdk_zyg8YS0JqA",
      "name": "Luis Fonsi",
      "thumbnails": [
        {
          "url": "https://yt3.ggpht.com/...",
          "width": 68,
          "height": 68
        }
      ],
      "subscriberCount": 1000000,
      "verified": true
    },
    "thumbnails": [
      {
        "url": "https://i.ytimg.com/vi/kJQP7kiw5Fk/hq720.jpg",
        "width": 360,
        "height": 202
      }
    ],
    "viewCount": 8871198622,
    "likeCount": 50000000,
    "published": "2017-01-13",
    "lengthSeconds": 282,
    "duration": "4:42",
    "isLive": false,
    "keywords": ["music", "despacito", "luis fonsi"],
    "downloadLinks": [
      {
        "itag": 18,
        "quality": "360p",
        "mime": "video/mp4; codecs=\"avc1.42001E, mp4a.40.2\"",
        "hasAudio": true,
        "url": "https://rr8---sn-42u-i5olk.googlevideo.com/videoplayback?..."
      }
    ]
  }
}

Get Comments

Retrieve comments for a YouTube video with support for sorting and pagination. Method: client.video.getComments() Parameters:

Parameter	Type	Required	Description
`videoId`	`string`	Yes	YouTube video ID
`sortBy`	`"TOP_COMMENTS" \| "NEWEST_FIRST"`	No	Sort order for comments
`continuation`	`string`	No	Pagination token
`gl`	`string`	No	Geo location code
`hl`	`string`	No	Language code

Example:

await client.video.getComments({
  videoId: "kJQP7kiw5Fk",
  sortBy: "TOP_COMMENTS", // Optional: "TOP_COMMENTS" | "NEWEST_FIRST"
  continuation: "token", // Optional: For pagination
  gl: "US", // Optional
  hl: "en", // Optional
});

Example Response:

{
  "message": "Success",
  "statusCode": 200,
  "pagination": {
    "total": 1000,
    "hasMore": true,
    "continuation": "UgyD..."
  },
  "data": {
    "comments": [
      {
        "id": "UgyD...",
        "author": {
          "id": "UCxoq-PAQeAdk_zyg8YS0JqA",
          "name": "John Doe",
          "thumbnails": [
            {
              "url": "https://yt3.ggpht.com/...",
              "width": 68,
              "height": 68
            }
          ],
          "verified": false
        },
        "text": "Great video!",
        "likeCount": 1000,
        "published": "2024-01-01",
        "publishedText": "2 days ago",
        "isPinned": false,
        "replyCount": 5,
        "continuationCommand": "Eg0SC0d5ckg2eGlGaVQwGAYygwEaUBIaVWd4djFBcjJ4TTJDZ0liZVJhVjRBYUFCQWciAggAKhhVQ3dKRHZ4NVlib3VDRVFfUlB3LU9SQlEyC0d5ckg2eGlGaVQwQAFICoIBAggBQi9jb21tZW50LXJlcGxpZXMtaXRlbS1VZ3h2MUFyMnhNMkNnSWJlUmFWNEFhQUJBZw%3D%3D"
      }
    ]
  }
}

Get Reply Comments

Retrieve reply comments for a specific parent comment. Method: client.video.getReplyComments() Parameters:

Parameter	Type	Required	Description
`continuation`	`string`	Yes	Continuation token from parent comment
`gl`	`string`	No	Geo location code
`hl`	`string`	No	Language code

Example:

await client.video.getReplyComments({
  continuation: "token", // Required: From parent comment
  gl: "US", // Optional
  hl: "en", // Optional
});

Channel Module

The channel module provides access to channel information, videos, playlists, and other channel-related content.

Get Detail

Get comprehensive information about a YouTube channel including statistics, metadata, and verification status. Method: client.channel.getDetail() Parameters:

Parameter	Type	Required	Description
`channelId`	`string`	Yes	YouTube channel ID
`gl`	`string`	No	Geo location code
`hl`	`string`	No	Language code

Example:

await client.channel.getDetail({
  channelId: "UCxoq-PAQeAdk_zyg8YS0JqA",
  gl: "US", // Optional
  hl: "en", // Optional
});

Example Response:

{
  "message": "Success",
  "statusCode": 200,
  "data": {
    "channelId": "UC0IpGYsi1KVorZ7QVCHfdax",
    "title": "Loci Da Poet",
    "description": "Loci (24/05/1988) - singer/songwriter/rapper/producer...",
    "thumbnails": [
      {
        "url": "https://yt3.googleusercontent.com/...",
        "width": 900,
        "height": 900
      }
    ],
    "subscriberCount": 1880000,
    "videoCount": 167,
    "viewCount": 663779872,
    "verified": true,
    "channelUrl": "https://www.youtube.com/channel/UC0IpGYsi1KVorZ7QVCHfdax",
    "vanityChannelUrl": "http://www.youtube.com/@LociDaPoet",
    "keywords": ["Loci", "Loci official", "Loci le"],
    "stats": {
      "subscribers": 1880000,
      "subscribersText": "1.88M subscribers",
      "videos": 167,
      "views": 663779872,
      "viewsText": "104.582.145 views"
    },
    "username": "@LociDaPoet"
  }
}

Get Videos

Retrieve all videos from a channel with pagination support. Method: client.channel.getVideos() Parameters:

Parameter	Type	Required	Description
`channelId`	`string`	Yes	YouTube channel ID
`continuation`	`string`	No	Pagination token
`gl`	`string`	No	Geo location code
`hl`	`string`	No	Language code

Example:

await client.channel.getVideos({
  channelId: "UCxoq-PAQeAdk_zyg8YS0JqA",
  continuation: "token", // Optional: For pagination
  gl: "US", // Optional
  hl: "en", // Optional
});

Get Playlists

Get all playlists created by a channel. Method: client.channel.getPlaylists() Parameters:

Parameter	Type	Required	Description
`channelId`	`string`	Yes	YouTube channel ID
`continuation`	`string`	No	Pagination token
`gl`	`string`	No	Geo location code
`hl`	`string`	No	Language code

Example:

await client.channel.getPlaylists({
  channelId: "UCxoq-PAQeAdk_zyg8YS0JqA",
  continuation: "token", // Optional
  gl: "US", // Optional
  hl: "en", // Optional
});

Get Releases

Retrieve music releases and albums from a channel. Method: client.channel.getReleases() Parameters:

Parameter	Type	Required	Description
`channelId`	`string`	Yes	YouTube channel ID
`continuation`	`string`	No	Pagination token
`gl`	`string`	No	Geo location code
`hl`	`string`	No	Language code

Example:

await client.channel.getReleases({
  channelId: "UCxoq-PAQeAdk_zyg8YS0JqA",
  continuation: "token", // Optional
  gl: "US", // Optional
  hl: "en", // Optional
});

Get Posts

Get community posts from a channel. Method: client.channel.getPosts() Parameters:

Parameter	Type	Required	Description
`channelId`	`string`	Yes	YouTube channel ID
`continuation`	`string`	No	Pagination token
`gl`	`string`	No	Geo location code
`hl`	`string`	No	Language code

Example:

await client.channel.getPosts({
  channelId: "UCxoq-PAQeAdk_zyg8YS0JqA",
  continuation: "token", // Optional
  gl: "US", // Optional
  hl: "en", // Optional
});

Get Shorts

Retrieve YouTube Shorts from a channel. Method: client.channel.getShorts() Parameters:

Parameter	Type	Required	Description
`channelId`	`string`	Yes	YouTube channel ID
`continuation`	`string`	No	Pagination token
`gl`	`string`	No	Geo location code
`hl`	`string`	No	Language code

Example:

await client.channel.getShorts({
  channelId: "UCxoq-PAQeAdk_zyg8YS0JqA",
  continuation: "token", // Optional
  gl: "US", // Optional
  hl: "en", // Optional
});

Get Store

Get store items and merchandise from a channel. Method: client.channel.getStore() Parameters:

Parameter	Type	Required	Description
`channelId`	`string`	Yes	YouTube channel ID
`continuation`	`string`	No	Pagination token
`gl`	`string`	No	Geo location code
`hl`	`string`	No	Language code

Example:

await client.channel.getStore({
  channelId: "UCxoq-PAQeAdk_zyg8YS0JqA",
  continuation: "token", // Optional
  gl: "US", // Optional
  hl: "en", // Optional
});

Search

Search for content within a specific channel. Method: client.channel.search() Parameters:

Parameter	Type	Required	Description
`channelId`	`string`	Yes	YouTube channel ID
`keyword`	`string`	Yes	Search keyword
`continuation`	`string`	No	Pagination token
`gl`	`string`	No	Geo location code
`hl`	`string`	No	Language code

Example:

await client.channel.search({
  channelId: "UCxoq-PAQeAdk_zyg8YS0JqA",
  keyword: "search term",
  continuation: "token", // Optional
  gl: "US", // Optional
  hl: "en", // Optional
});

The trending module provides access to trending videos, songs, artists, and charts from YouTube.

Get Video

Get trending videos for a specific country. Method: client.trending.getVideo() Parameters:

Parameter	Type	Required	Description
`countryCode`	`string`	No	ISO country code (e.g., “us”)
`gl`	`string`	No	Geo location code
`hl`	`string`	No	Language code

Example:

await client.trending.getVideo({
  countryCode: "us", // Optional
  gl: "US", // Optional
  hl: "en", // Optional
});

Example Response:

{
  "message": "Success",
  "statusCode": 200,
  "data": {
    "contents": [
      {
        "author": {
          "avatar": {
            "url": "https://i.ytimg.com/vi/JednRKQYhC4/default.jpg",
            "width": 120,
            "height": 90
          },
          "name": "Alofoke Music"
        },
        "videoId": "JednRKQYhC4",
        "channelId": "UCeDlzhpU8NZAlL1rsXp54zQ",
        "thumbnails": [
          {
            "url": "https://i.ytimg.com/vi/JednRKQYhC4/default.jpg",
            "width": 120,
            "height": 90
          }
        ],
        "publishedTimeText": "2 days ago",
        "releaseDate": {
          "year": 2025,
          "month": 11,
          "day": 29
        },
        "title": "MICHAEL FLORES X DANI BARRANCO X ALOFOKE MUSIC - AGUITA E COCO",
        "duration": "2:22",
        "songwriters": [],
        "songProducers": [],
        "url": "https://www.youtube.com/watch?v=JednRKQYhC4"
      }
    ]
  }
}

Get Top Video

Get top trending videos with chart positions and rankings. Method: client.trending.getTopVideo() Parameters:

Parameter	Type	Required	Description
`filterByType`	`"DAILY" \| "WEEKLY"`	No	Chart type filter
`filterByDate`	`string`	No	Date filter in YYYYMMDD format
`countryCode`	`string`	No	ISO country code
`gl`	`string`	No	Geo location code
`hl`	`string`	No	Language code

Example:

await client.trending.getTopVideo({
  filterByType: "DAILY", // Optional: "DAILY" | "WEEKLY"
  filterByDate: "20251106", // Optional: Format YYYYMMDD
  countryCode: "us", // Optional
  gl: "US", // Optional
  hl: "en", // Optional
});

Get Song

Retrieve trending songs from YouTube Music charts. Method: client.trending.getSong() Parameters:

Parameter	Type	Required	Description
`countryCode`	`string`	No	ISO country code
`filterByDate`	`string`	No	Date filter in YYYYMMDD format
`gl`	`string`	No	Geo location code
`hl`	`string`	No	Language code

Example:

await client.trending.getSong({
  countryCode: "us", // Optional
  filterByDate: "20251106", // Optional: Format YYYYMMDD
  gl: "US", // Optional
  hl: "en", // Optional
});

Get Artist

Get trending artists from YouTube Music charts. Method: client.trending.getArtist() Parameters:

Parameter	Type	Required	Description
`countryCode`	`string`	No	ISO country code
`filterByDate`	`string`	No	Date filter in YYYYMMDD format
`gl`	`string`	No	Geo location code
`hl`	`string`	No	Language code

Example:

await client.trending.getArtist({
  countryCode: "us", // Optional
  filterByDate: "20251106", // Optional: Format YYYYMMDD
  gl: "US", // Optional
  hl: "en", // Optional
});

Get Top Short Song

Get top trending short songs (YouTube Shorts music). Method: client.trending.getTopShortSong() Parameters:

Parameter	Type	Required	Description
`countryCode`	`string`	No	ISO country code
`filterByType`	`"DAILY" \| "WEEKLY"`	No	Chart type filter
`filterByDate`	`string`	No	Date filter in YYYYMMDD format
`gl`	`string`	No	Geo location code
`hl`	`string`	No	Language code

Example:

await client.trending.getTopShortSong({
  countryCode: "us", // Optional
  filterByType: "DAILY", // Optional: "DAILY" | "WEEKLY"
  filterByDate: "20251106", // Optional: Format YYYYMMDD
  gl: "US", // Optional
  hl: "en", // Optional
});

Error Handling

The client uses axios for HTTP requests. Errors will be thrown as axios errors with detailed information:

try {
  const result = await client.explore.search({ keyword: "test" });
} catch (error) {
  if (error.response) {
    // The request was made and the server responded with a status code
    // that falls out of the range of 2xx
    console.error("Error status:", error.response.status);
    console.error("Error data:", error.response.data);
  } else if (error.request) {
    // The request was made but no response was received
    console.error("No response received");
  } else {
    // Something happened in setting up the request
    console.error("Error:", error.message);
  }
}

Getting started

SDKs

YouTube API

Spotify API

YouTube SDK

YouTube API Client

Installation

Quick Start

Configuration

API Structure

API Reference

Explore Module

Search

Suggestions

Video Module

Get Detail

Get Comments

Get Reply Comments

Channel Module

Get Detail

Get Videos

Get Playlists

Get Releases

Get Posts

Get Shorts

Get Store

Search

Get Video

Get Top Video

Get Song

Get Artist

Get Top Short Song

Error Handling

Additional Resources

Getting started

SDKs

YouTube API

Spotify API

​YouTube API Client

​Installation

​Quick Start

​Configuration

​API Structure

​API Reference

​Explore Module

​Search

​Suggestions

​Video Module

​Get Detail

​Get Comments

​Get Reply Comments

​Channel Module

​Get Detail

​Get Videos

​Get Playlists

​Get Releases

​Get Posts

​Get Shorts

​Get Store

​Search

​Trending Module

​Get Video

​Get Top Video

​Get Song

​Get Artist

​Get Top Short Song

​Error Handling

​Additional Resources

YouTube API Client

Installation

Quick Start

Configuration

API Structure

API Reference

Explore Module

Search

Suggestions

Video Module

Get Detail

Get Comments

Get Reply Comments

Channel Module

Get Detail

Get Videos

Get Playlists

Get Releases

Get Posts

Get Shorts

Get Store

Search

Trending Module

Get Video

Get Top Video

Get Song

Get Artist

Get Top Short Song

Error Handling

Additional Resources