@watchmode/api-client

@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

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