Options

When creating a new TMDB client instance, you can pass a TMDBOptions object to customize its default behavior. All options are optional — omitting them falls back to TMDB's global defaults.

import { TMDB } from "tmdb-ts";

const tmdb = new TMDB("your-api-key", {
	language: "it-IT",
	region: "IT",
	timezone: "Europe/Rome",
	images: {
		secure_images_url: true,
		default_image_sizes: {
			posters: "w500",
			backdrops: "w1280",
		},
	},
});

Available Options

language

Type: Language · Optional

Controls the language of text data returned by TMDB — titles, overviews, taglines, and more. Accepts either a primary translation code (e.g., "it-IT", "en-US") or a bare ISO 639-1 code (e.g., "it", "en").

const tmdb = new TMDB(apiKey, { language: "it-IT" });

When unset, TMDB defaults to English. See the Language reference for the full list of supported values.

region

Type: CountryISO3166_1 · Optional

Sets the default region for requests. Region codes follow ISO 3166-1 alpha-2 (e.g., "IT", "US", "JP").

The region influences:

• Release dates and theatrical availability
• Age certifications
• Watch provider listings
• Filtered movie lists (e.g., now playing, upcoming)

const tmdb = new TMDB(apiKey, { region: "IT" });

If not set, TMDB may fall back to global (non-regionalized) data. See the Region reference for all supported country codes.

images

Type: ImagesConfig · Optional

Configures how image URLs are generated. Includes options to toggle HTTPS and set default sizes for each image category so you don't need to pass sizes on every individual request.

const tmdb = new TMDB(apiKey, {
	images: {
		secure_images_url: true,
		default_image_sizes: {
			posters: "w500",
			backdrops: "w1280",
			logos: "w300",
		},
	},
});

See the Images configuration reference for all available size options per category.

timezone

Type: Timezone · Optional

Sets the default timezone used for TV series queries that accept a timezone parameter. TMDB uses this to determine what counts as "today" when fetching currently airing shows.

Timezones are mapped per country — each country code corresponds to one or more IANA timezone identifiers (e.g., "Europe/Rome", "America/New_York").

const tmdb = new TMDB(apiKey, { timezone: "Europe/Rome" });

Note: This only affects TV series endpoints that support the timezone parameter, such as "airing today" and "on the air" queries. Movie endpoints are not affected.

See the Timezone reference for the full list of supported values grouped by country.