Regions, Languages & Categories

Fetch supported YouTube regions, languages, and video categories

Overview

YouTube groups content by region and language. The SDK provides three related APIs:

  • Regions — countries/territories YouTube operates in (used as regionCode in other methods)
  • Languages — UI languages YouTube supports (used as hl in other methods)
  • Video Categories — content categories (Music, Gaming, Education, etc.) that vary by region

All three are accessible from the main yt() client and cost 1 quota unit per call.


Regions

client.regions(hl?)

List all regions where YouTube is available. Each region has a gl code (ISO 3166-1 alpha-2) used as the regionCode parameter in videoCategoriesByRegion() and other API methods.

const regions = await client.regions()

for (const region of regions) {
  console.log(`${region.gl}${region.name}`)
}
// US — United States
// GB — United Kingdom
// IN — India
// ...

Response

Returns an array of I18nRegion:

PropertyTypeDescription
idstringYouTube's internal region ID
glstringISO 3166-1 alpha-2 country code
namestringRegion display name

Localized names

Pass a hl parameter to get region names in a specific language:

const regions = await client.regions('fr')
// { gl: 'US', name: 'États-Unis' }
// { gl: 'DE', name: 'Allemagne' }

Languages

client.languages(hl?)

List all languages YouTube supports. Each language has an hl code (BCP-47) used as the hl parameter in other methods.

const languages = await client.languages()

for (const lang of languages) {
  console.log(`${lang.hl}${lang.name}`)
}
// en — English
// fr — French
// zh-Hans — Chinese (Simplified)
// ...

Response

Returns an array of I18nLanguage:

PropertyTypeDescription
idstringYouTube's internal language ID
hlstringBCP-47 language code
namestringLanguage display name

Localized names

const languages = await client.languages('ja')
// { hl: 'en', name: '英語' }
// { hl: 'fr', name: 'フランス語' }

Video Categories

Video categories are region-specific. The categories available in the US differ from those in Japan or India.

client.videoCategoriesByRegion(regionCode, hl?)

Fetch all video categories available in a region.

const categories = await client.videoCategoriesByRegion('US')

for (const cat of categories) {
  const badge = cat.assignable ? '' : ' (not assignable)'
  console.log(`${cat.id}: ${cat.title}${badge}`)
}

client.videoCategory(id)

Fetch a single video category by ID.

const music = await client.videoCategory('10')
console.log(music.title)      // "Music"
console.log(music.assignable) // true

client.videoCategories(ids)

Fetch multiple categories by ID.

const categories = await client.videoCategories(['1', '10', '20'])
// [
//   { id: '1', title: 'Film & Animation', assignable: true, ... },
//   { id: '10', title: 'Music', assignable: true, ... },
//   { id: '20', title: 'Gaming', assignable: true, ... }
// ]

Response

Returns VideoCategory objects:

PropertyTypeDescription
idstringCategory ID
titlestringCategory name
assignablebooleanWhether videos can be assigned this category
channelIdstringChannel that created the category

Category IDs

Common category IDs (US region):

IDTitleAssignable
1Film & AnimationYes
2Autos & VehiclesYes
10MusicYes
15Pets & AnimalsYes
17SportsYes
19Travel & EventsYes
20GamingYes
22People & BlogsYes
23ComedyYes
24EntertainmentYes
25News & PoliticsYes
26Howto & StyleYes
27EducationYes
28Science & TechnologyYes
29Nonprofits & ActivismYes

Non-assignable categories (30–44) include Movies, Shows, and Trailers — reserved by YouTube.


The hl parameter

The hl parameter controls the language of text values in API responses. It's accepted by regions(), languages(), and videoCategoriesByRegion().

How hl connects everything

Discover languages

Call client.languages() to get all valid hl values.

const languages = await client.languages()
// [{ hl: 'en', name: 'English' }, { hl: 'fr', name: 'French' }, ...]

Discover regions

Call client.regions() to get all valid regionCode values.

const regions = await client.regions()
// [{ gl: 'US', name: 'United States' }, { gl: 'JP', name: 'Japan' }, ...]

Fetch localized categories

Combine a regionCode and hl to get categories in a specific language for a specific region.

const categories = await client.videoCategoriesByRegion('JP', 'ja')
// [{ id: '10', title: '音楽', ... }, { id: '20', title: 'ゲーム', ... }]

Cross-reference example

// Get all regions with Japanese names
const regions = await client.regions('ja')

// Get all languages with Japanese names
const languages = await client.languages('ja')

// Get Japanese categories for Japan
const categories = await client.videoCategoriesByRegion('JP', 'ja')

Error handling

import { yt, NotFoundError, AuthError } from 'lyra-sdk'

const client = yt(process.env.YOUTUBE_API_KEY!)

try {
  const category = await client.videoCategory('99999')
} catch (error) {
  if (error instanceof NotFoundError) {
    console.log('Category not found')
  }
}
ErrorWhen it's thrown
NotFoundErrorCategory ID does not exist
AuthErrorInvalid or missing API key
YTErrorGeneral API failure (quota, network, etc.)

On this page