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,
		autocomplete_paths: 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. It can also opt in to rewriting relative image paths in API responses to full URLs.

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

With autocomplete_paths: true, fields like poster_path are returned as complete URLs instead of TMDB-relative paths. See the Images configuration reference for supported fields, defaults, and examples.

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.

logger

Type: boolean | TMDBLoggerFn · Optional

Enables logging for every HTTP request, response, and network error made by the client.

• Pass true to use the built-in console logger.
• Pass a TMDBLoggerFn callback to handle log entries yourself.
• Omit the option (or pass false) to disable logging entirely.

// Built-in logger
const tmdb = new TMDB(apiKey, { logger: true });

// Custom logger
const tmdb = new TMDB(apiKey, {
	logger: (entry) => {
		console.log(`[${entry.type}] ${entry.method} ${entry.endpoint}`);
	},
});

See the Logging guide for more examples and integration patterns.

deduplication

Type: boolean · Default: true

When true, concurrent calls with the same endpoint and parameters share a single in-flight fetch. All callers resolve from the same Promise — no duplicate network requests are made.

// Default behaviour — one fetch for all three concurrent calls
const [a, b, c] = await Promise.all([
	tmdb.movies.details({ movie_id: 550 }),
	tmdb.movies.details({ movie_id: 550 }),
	tmdb.movies.details({ movie_id: 550 }),
]);

Set to false to make every call trigger its own fetch regardless of concurrency. Useful for polling loops, force-refreshes after mutations, or independent SSR data loaders.

const tmdb = new TMDB(apiKey, { deduplication: false });

See the Features guide for a full explanation.

interceptors

Type: { request?: RequestInterceptor | RequestInterceptor[]; response?: { onSuccess?, onError? } } · Optional

Hooks into the request and response lifecycle. request interceptors run before every API call; response.onSuccess runs after a successful response for side effects (logging, caching) — the original data is always returned unchanged; response.onError runs after an error is normalised into a TMDBError and always re-throws.

const tmdb = new TMDB(apiKey, {
	interceptors: {
		request: (ctx) => {
			console.log(`[TMDB] ${ctx.method} ${ctx.endpoint}`, ctx.params);
		},
		response: {
			onSuccess: (data) => {
				myCache.store(data);
			},
			onError: (error) => {
				Sentry.captureException(error);
			},
		},
	},
});

See the Interceptors guide for full details and examples.

rate_limit

Type: boolean | RateLimitOptions · Default: false

Enables the built-in sliding-window rate limiter. When set, outgoing requests that exceed the configured budget are queued in FIFO order and dispatched as slots become available.

• Pass true to use the defaults (~40 requests per second).
• Pass a RateLimitOptions object to set a custom max_requests and/or per_ms.

// Default limits (~40 req / s)
const tmdb = new TMDB(apiKey, { rate_limit: true });

// Custom budget
const tmdb = new TMDB(apiKey, {
	rate_limit: { max_requests: 20, per_ms: 1_000 },
});

See the Rate Limiting guide for full details.

retry

Type: boolean | RetryOptions · Default: false

Enables automatic retry with exponential back-off for transient errors. When set, failed requests are retried up to max_retries times using a jittered exponential delay.

• Pass true to use the defaults (3 retries, 500 ms base delay, 30 s cap).
• Pass a RetryOptions object to customise retry count, delays, or supply a shouldRetry predicate.

By default, only transient server-side errors are retried — HTTP 5xx responses and network errors. 4xx client errors are never retried.

// Default settings (3 retries)
const tmdb = new TMDB(apiKey, { retry: true });

// Custom options
const tmdb = new TMDB(apiKey, {
	retry: { max_retries: 5, base_delay_ms: 200 },
});

See the Retry guide for full details.

cache

Type: boolean | CacheOptions · Default: false

Enables the built-in in-memory response cache. Repeated identical GET requests are served from memory without hitting the network. Mutations are never cached.

• Pass true to use the defaults (5-minute TTL, no size limit).
• Pass a CacheOptions object to set a custom ttl, cap max_size, or exclude specific endpoints.

// Default TTL (5 minutes)
const tmdb = new TMDB(apiKey, { cache: true });

// Custom options
const tmdb = new TMDB(apiKey, {
	cache: {
		ttl: 60_000,
		max_size: 500,
		excluded_endpoints: ["/trending", /\/discover\//],
	},
});

See the Response Caching guide for full details.