youtube-search-api

Youtube Search API

Youtube Search API is an API for getting Youtube search results.

Installation

npm install youtube-search-api

Usage (import)

const youtubesearchapi = require("youtube-search-api");

import youtubesearchapi from "youtube-search-api";

GetListByKeywords (Promise)

youtubesearchapi.GetListByKeyword("<keywords>",[playlist boolean],[limit number],[options JSONArray])

GetListByKeywords Result

{items:[],nextPage:{nextPageToken:"xxxxxxxx",nextPageContext:{}}}

"items" is the array from youtube, "nextPage" needs to pass when going to the next page. If playlist arg is true, will return type:'playlist' but the videos:[] property will not return the whole videos in the list, need to call GetPlaylistData to get real playlist's videos. Item with Video type will return isLive=[true/false] to identify live video or not.

Options added, this version only support return result type, e.g. [{type:'video'}].

Parameters

Parameter	Type	Value
keywords	String	up to you
playlist	boolean	true/false
limit	number	integer
options	JSON Array	[{type:"video/channel/playlist/movie"}]

NextPage (Promise)

youtubesearchapi.NextPage(<nextPage from GetListByKeywords result>,[playlist boolean],[limit number])

NextPage Result

{items:[],nextPage:{nextPageToken:"xxxxxxxx",nextPageContext:{}}}

Item with Video type will return isLive=[true/false] to identify live video or not.

Playlist with ID (Promise)

youtubesearchapi.GetPlaylistData(<Playlist Id>,[limit number])

Playlist Result

{items:[],metadata:{}}

Get Suggest Data (Promise)

youtubesearchapi.GetSuggestData([limit number])

Suggest Data Result

{
  items: [];
}

Item with Video type will return isLive=[true/false] to identify live video or not.

Get Channel by channel Id (Promise)

youtubesearchapi.GetChannelById(<channel ID>)

Channel Data Results

[[{ title: "[title]", content: [Object] }]];

Will return tabs in array format.

Get Video Details with suggestion

GetVideoDetails

youtubesearchapi.GetVideoDetails(<video ID>)

Get Video Details Results

{
  id:"",
  title: "",
  thumbnail:[],
  isLive: [true/false],
  channel: "",
  channelId:"",
  description: "",
  keywords:[],
  suggestion: [
    {id: "",
      type: 'video',
      thumbnail: [],
      title: "",
      channelTitle: "",
      shortBylineText: "",
      length: [Object],
      isLive: [true/false]
    } ...
  ]
}

Will return video details in Json format.

Get Short Video List (Beta)

Only return short video from suggestion.

GetShortVideo

youtubesearchapi.GetShortVideo();

Get Short Video List Results

[
  {
    id: "",
    type: "reel",
    thumbnail: {
      url: "",
      width: 405, //only return 405
      height: 720, //only return 720
    },
    title: "",
    inlinePlaybackEndpoint: {}, //may not return all the time
  },
];

Will return Short Video list in Json Array format.

Limitation:

• Only return short video from suggestion.
• inlinePlaybackEndpoint facing async issue.
• Only return first page of short video.

Error Handling

The library provides comprehensive error handling with custom error classes and error codes.

For detailed information about error messages and their translations, see ERROR_MESSAGES.md.

Error Classes

const {
  YouTubeAPIError,
  ErrorHandler,
  ErrorCodes,
} = require("youtube-search-api");

Error Codes

Error Code	Description
NETWORK_ERROR	Network connection issues
INIT_DATA_ERROR	Cannot get YouTube initialization data
PLAYER_DATA_ERROR	Cannot get YouTube player data
INVALID_PLAYLIST	Invalid playlist ID
INVALID_VIDEO_ID	Invalid video ID
INVALID_CHANNEL_ID	Invalid channel ID
RATE_LIMIT_ERROR	Rate limit exceeded
PARSE_ERROR	Data parsing error
UNKNOWN_ERROR	Unknown error

Basic Error Handling

try {
  const result = await youtubesearchapi.GetVideoDetails("invalid_video_id");
} catch (error) {
  if (error instanceof YouTubeAPIError) {
    console.log(`Error Code: ${error.code}`);
    console.log(`Error Message: ${error.message}`);
    console.log(`Status Code: ${error.statusCode}`);
  }
}

Custom Error Logger

const errorHandler = ErrorHandler.getInstance();
errorHandler.setErrorLogger((error) => {
  console.log(`[${new Date().toISOString()}] ${error.code}: ${error.message}`);
  // Send to your logging service
});

Error Handling Examples

// Handle specific error types
try {
  await youtubesearchapi.GetPlaylistData("invalid_playlist");
} catch (error) {
  if (error instanceof YouTubeAPIError) {
    switch (error.code) {
      case ErrorCodes.INVALID_PLAYLIST:
        console.log("Please check the playlist ID");
        break;
      case ErrorCodes.NETWORK_ERROR:
        console.log("Please check your internet connection");
        break;
      case ErrorCodes.RATE_LIMIT_ERROR:
        console.log("Please try again later");
        break;
      default:
        console.log("An unknown error occurred");
    }
  }
}

See example/error-handling-example.js for more detailed examples.

Docker:

Docker Image

Message

If you want to work with me to fix bug or implement new idea. You are available to send me some new idea of this project.

Contributing

Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.

Please make sure to update tests as appropriate.

TODO

• Web app with show case
• Support front-end (Vue, React) (Still on going ...)

Bug fixed

Update

• Search for shorts (Limitation)

License

MIT

Support me

https://www.buymeacoffee.com/damonwcw

Contact me

[e-mail]