@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

``bash
npm install @watchmode/api-client
`

`bash
yarn add @watchmode/api-client
`

`bash
pnpm add @watchmode/api-client
`

Quick Start

`typescript
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

$3

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

$3

#### Get Title Details

`typescript
// 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

`typescript
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

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

#### Get Cast & Crew

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

#### List Titles with Filtering

`typescript
// 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
});
`

$3

`typescript
// 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
});
`

$3

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

$3

`typescript
// 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
});
`

$3

`typescript
// 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
});
`

$3

Track changes for keeping your database in sync.

`typescript
// 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
});
`

$3

`typescript
// 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();
`

$3

`typescript
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:

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

Error Handling

`typescript
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:

`typescript
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