@watchmode/api-client

Official TypeScript/JavaScript SDK for the Watchmode Streaming Availability API.

Find where movies and TV shows are streaming across Netflix, Hulu, Disney+, HBO Max, Prime Video, and 200+ other services in 50+ countries.

Installation

npm install @watchmode/api-client

yarn add @watchmode/api-client

pnpm add @watchmode/api-client

Quick Start

import { WatchmodeClient } from '@watchmode/api-client';

const client = new WatchmodeClient({
  apiKey: 'your-api-key' // Get one free at https://api.watchmode.com
});

// Get title details
const { data: title } = await client.title.getDetails('3173903');
console.log(title?.title); // "Breaking Bad"

// Get streaming sources
const { data: sources } = await client.title.getSources('3173903', { regions: 'US' });
console.log(sources); // [{ source_id: 203, name: "Netflix", ... }]

// Search for titles
const { data: results } = await client.search.byName('inception');
console.log(results?.title_results);

API Reference

Authentication

The SDK handles authentication from the apiKey value you pass to WatchmodeClient.

For direct REST API calls outside the SDK, send your key in the X-API-Key header. Authorization: Bearer <api-key> is also supported. The apiKey query parameter remains available for backwards compatibility, but headers are recommended for new integrations because URLs are commonly stored in logs, browser history, analytics, and referrer headers.

Client Configuration

const client = new WatchmodeClient({
  apiKey: 'your-api-key',        // Required
  baseUrl: 'https://...',        // Optional, defaults to production
  fetch: customFetch             // Optional, for Node.js or testing
});

Title API

Get Title Details

// By Watchmode ID (1 credit)
const { data } = await client.title.getDetails('3173903');

// By IMDB ID (2 credits)
const { data } = await client.title.getDetails('tt0903747');

// By TMDB format (2 credits)
const { data } = await client.title.getDetails('tv-1396');

// With additional data appended
const { data } = await client.title.getDetails('3173903', {
  appendToResponse: 'sources,cast-crew,seasons,episodes',
  regions: 'US,CA',
  language: 'en'
});

Get Streaming Sources

const { data: sources } = await client.title.getSources('3173903', {
  regions: 'US,GB,CA'
});

// Response includes: subscription, rental, purchase, and free options
sources?.forEach(source => {
  console.log(`${source.name} (${source.type}): ${source.web_url}`);
});

Get TV Seasons & Episodes

const { data: seasons } = await client.title.getSeasons('3173903');
const { data: episodes } = await client.title.getEpisodes('3173903');

Get Cast & Crew

const { data: credits } = await client.title.getCastCrew('3173903');

List Titles with Filtering

// Horror movies streaming on Netflix in the US
const { data } = await client.title.list({
  types: 'movie',
  genres: '12',           // Horror genre ID
  sourceIds: '203',       // Netflix
  regions: 'US',
  sortBy: 'popularity_desc',
  page: 1,
  limit: 50
});

// All available filter options:
const { data } = await client.title.list({
  types: 'movie,tv_series',
  regions: 'US',
  sourceTypes: 'sub,free',
  sourceIds: '203,26',
  genres: '4,7',
  networkIds: '1,8',
  languages: 'en,es',
  releaseDateStart: 20200101,
  releaseDateEnd: 20231231,
  userRatingLow: 7,
  userRatingHigh: 10,
  criticScoreLow: 70,
  criticScoreHigh: 100,
  personId: 7110004,
  sortBy: 'release_date_desc',
  page: 1,
  limit: 250
});

Search API

// Search by name
const { data } = await client.search.byName('Breaking Bad');

// Search by IMDB ID
const { data } = await client.search.byImdbId('tt0903747');

// Search by TMDB ID
const { data } = await client.search.byTmdbMovieId(278);
const { data } = await client.search.byTmdbTvId(1396);
const { data } = await client.search.byTmdbPersonId(17419);

// Autocomplete (for typeahead UI)
const { data } = await client.search.autocomplete('break', {
  searchType: 2 // 1=all, 2=titles, 3=movies, 4=TV, 5=people
});

Person API

const { data: person } = await client.person.getDetails(7110004);
console.log(person?.full_name); // "Brad Pitt"
console.log(person?.known_for); // [1132806, 1336708, ...]

Sources API

// Get all streaming services
const { data: sources } = await client.sources.list();

// Filter by region and type
const { data: sources } = await client.sources.list({
  regions: 'US,CA',
  types: 'sub,free' // subscription and free services
});

Releases API

// Get recent/upcoming releases
const { data } = await client.releases.getRecent({
  startDate: 20240101,
  endDate: 20240131,
  limit: 100
});

// Get upcoming release dates (paid plans only)
const { data } = await client.releases.getUpcoming({
  startDate: 20240101,
  endDate: 20240331
});

Changes API (Paid Plans Only)

Track changes for keeping your database in sync.

// Get newly added titles
const { data } = await client.changes.getNewTitles({
  startDate: 20240101,
  endDate: 20240107,
  types: 'movie,tv_series',
  page: 1,
  limit: 250
});

// Get titles with changed streaming sources
const { data } = await client.changes.getTitlesWithSourceChanges({
  startDate: 20240101,
  endDate: 20240107,
  regions: 'US'
});

// Get titles with updated metadata
const { data } = await client.changes.getTitlesWithDetailChanges({
  startDate: 20240101,
  endDate: 20240107
});

// Get titles with new/changed episodes
const { data } = await client.changes.getTitlesWithEpisodeChanges({
  startDate: 20240101,
  endDate: 20240107
});

// Get newly added people
const { data } = await client.changes.getNewPeople({
  startDate: 20240101,
  endDate: 20240107
});

Reference Data API

// Get supported regions
const { data: regions } = await client.reference.getRegions();

// Get TV networks
const { data: networks } = await client.reference.getNetworks();

// Get genres
const { data: genres } = await client.reference.getGenres();

Account API

const { data: status } = await client.account.getStatus();
console.log(`Used ${status?.quotaUsed} of ${status?.quota} API calls this month`);

TypeScript Support

All types are fully exported:

import type {
  TitleDetails,
  TitleSource,
  Person,
  Source,
  Region,
  Genre,
  Network,
  SearchResponse,
  AutocompleteResponse
} from '@watchmode/api-client';

Error Handling

const { data, error } = await client.title.getDetails('invalid-id');

if (error) {
  console.error(`Error ${error.statusCode}: ${error.statusMessage}`);
} else {
  console.log(data?.title);
}

Node.js Usage

For Node.js versions before 18, you may need to provide a fetch implementation:

import fetch from 'node-fetch';

const client = new WatchmodeClient({
  apiKey: 'your-api-key',
  fetch: fetch as unknown as typeof globalThis.fetch
});

Rate Limits

API requests are limited based on your plan. The client automatically includes your API key with each request.

License

MIT

Links

• Watchmode API Documentation
• Get an API Key
• API Explorer