API Reference

Welcome to Watchmode's API! Watchmode is the most complete API for finding out what movies & shows are available on each streaming service, as well as many other useful features built for creating applications built around movies & shows. You can use this API to access all our API endpoints, such as the Title API to get details on a specific title, or the List Titles API to get a listing of movies & shows that match a certain criteria.

The API is organized around REST. All requests should be made over SSL. All request and response bodies, including errors, are encoded in JSON.

Simply pass your apiKey as a GET or POST parameter to the API to authenticate. You can use the test key provided in the examples to test, however be advised the testing apiKey is limited to certain queries and will only return responses to the example requests shown below.

Get API Key

API keys are free, request one here.

API Root URL

https://api.watchmode.com/v1/

ID Mapping

Watchmode IDs for movies, tv shows and for people (actors, directors, etc) are universally unique and cannot collide with each other. So you don't have to worry that the ID for an actor can collide with the ID for a movie, or that an ID for a TV show can collide with a movie ID and so forth.

When you first integrate your application with the Watchmode API, you may want to import all of the Watchmode IDs for titles and people. To get a list of all Watchmode IDs, and their corresponding IMDB/TMDB ids, you can download the following files (updated daily):

https://api.watchmode.com/datasets/title_id_map.csv

https://api.watchmode.com/datasets/person_id_map.csv

Errors

HTTP Status codes

Code	Title	Description
200	OK	The request was successful.
400	Bad request	Bad request
401	Unauthorized	No valid API key provided.
403	Forbidden	The API key doesn't have permissions to perform the request.
404	Not Found	The requested resource doesn't exist.
429	Too Many Requests	Too many requests hit the API too quickly.
500, 502, 503, 504	Server Errors	Something went wrong on Watchmode's end.

Error Response

{"success":false,"statusCode":400,"statusMessage":"Please set a valid change type method."}

All errors are returned in the form of JSON with a type and optional message.

Rate Limiting

API requests are limited by your plan. You can make up to your plan's limit per minute. We recommend that you cache API responses on your end to minimize the number of API calls needed.

You can check the headers of any API response to see your current rate limit status:

X-RateLimit-Limit: The maximum number of requests you're permitted to make per minute.
X-RateLimit-Remaining: The number of requests remaining in the current rate limit window.
X-Account-Quota: The maximum number of requests you can make for the month.
X-Account-Quota-Used: The number of requests you've made so far this month.

Sources API

https://api.watchmode.com/v1/sources/

Returns a list of all the streaming sources (streaming services, networks, etc.) that are supported. This includes subscription services (like Netflix), rental/purchase services (like iTunes), and free services. Each source has details about supported regions, logos, and app store links.

curl -i 'https://api.watchmode.com/v1/sources/?apiKey=YOUR_API_KEY'

<?php
// Set your API key here
$apiKey = 'YOUR_API_KEY';
$url = "https://api.watchmode.com/v1/sources/?apiKey={$apiKey}";

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_FOLLOWLOCATION, 1);
$response = curl_exec($ch);
curl_close($ch);

$json = json_decode($response);
print_r($json);

import urllib.request
import json

# Set your API key here
api_key = 'YOUR_API_KEY'
url = f'https://api.watchmode.com/v1/sources/?apiKey={api_key}'

with urllib.request.urlopen(url) as response:
    data = json.loads(response.read().decode())
    print(data)

// Set your API key here
const apiKey = 'YOUR_API_KEY';
const url = `https://api.watchmode.com/v1/sources/?apiKey=${apiKey}`;

const response = await fetch(url);
const json = await response.json();
console.log(json);

Response

[
  {
    "id": 203,
    "name": "Netflix",
    "type": "sub",
    "logo_100px": "https://cdn.watchmode.com/logos/203_logo_100px.jpg",
    "ios_appstore_url": "https://apps.apple.com/app/id363590051",
    "android_playstore_url": "https://play.google.com/store/apps/details?id=com.netflix.mediaclient",
    "regions": ["US", "GB", "AU"]
  },
  {
    "id": 26,
    "name": "Amazon Prime",
    "type": "sub",
    "logo_100px": "https://cdn.watchmode.com/logos/26_logo_100px.jpg",
    "ios_appstore_url": "https://apps.apple.com/app/id545519333",
    "android_playstore_url": "https://play.google.com/store/apps/details?id=com.amazon.avod.thirdpartyclient",
    "regions": ["US", "GB", "AU", "CA"]
  }
]

Regions API

https://api.watchmode.com/v1/regions/

Return a listing of all regions (countries) that Watchmode currently supports. Each region includes information about data quality tier and plan availability.

curl -i 'https://api.watchmode.com/v1/regions/?apiKey=YOUR_API_KEY'

<?php
// Set your API key here
$apiKey = 'YOUR_API_KEY';
$url = "https://api.watchmode.com/v1/regions/?apiKey={$apiKey}";

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_FOLLOWLOCATION, 1);
$response = curl_exec($ch);
curl_close($ch);

$json = json_decode($response);
print_r($json);

import urllib.request
import json

# Set your API key here
api_key = 'YOUR_API_KEY'
url = f'https://api.watchmode.com/v1/regions/?apiKey={api_key}'

with urllib.request.urlopen(url) as response:
    data = json.loads(response.read().decode())
    print(data)

// Set your API key here
const apiKey = 'YOUR_API_KEY';
const url = `https://api.watchmode.com/v1/regions/?apiKey=${apiKey}`;

const response = await fetch(url);
const json = await response.json();
console.log(json);

Response

[
  {
    "country": "US",
    "name": "USA",
    "flag": "https://cdn.watchmode.com/misc_images/icons/usFlag2.png",
    "data_tier": 1,
    "plan_enabled": true
  },
  {
    "country": "CA",
    "name": "Canada",
    "flag": "https://cdn.watchmode.com/misc_images/icons/flagCA.png",
    "data_tier": 1,
    "plan_enabled": true
  },
  {
    "country": "GB",
    "name": "Great Britain",
    "flag": "https://cdn.watchmode.com/misc_images/icons/flagGB.png",
    "data_tier": 1,
    "plan_enabled": true
  }
]

Networks API

https://api.watchmode.com/v1/networks/

Return a listing of all TV networks that may be returned for a title in the /title endpoint.

curl -i 'https://api.watchmode.com/v1/networks/?apiKey=YOUR_API_KEY'

<?php
// Set your API key here
$apiKey = 'YOUR_API_KEY';
$url = "https://api.watchmode.com/v1/networks/?apiKey={$apiKey}";

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_FOLLOWLOCATION, 1);
$response = curl_exec($ch);
curl_close($ch);

$json = json_decode($response);
print_r($json);

import urllib.request
import json

# Set your API key here
api_key = 'YOUR_API_KEY'
url = f'https://api.watchmode.com/v1/networks/?apiKey={api_key}'

with urllib.request.urlopen(url) as response:
    data = json.loads(response.read().decode())
    print(data)

// Set your API key here
const apiKey = 'YOUR_API_KEY';
const url = `https://api.watchmode.com/v1/networks/?apiKey=${apiKey}`;

const response = await fetch(url);
const json = await response.json();
console.log(json);

Response

[
  { "id": 1, "name": "HBO", "origin_country": "US", "tmdb_id": 49 },
  { "id": 2, "name": "National Geographic", "origin_country": "US", "tmdb_id": 43 },
  { "id": 7, "name": "ABC", "origin_country": "US", "tmdb_id": 2 },
  { "id": 8, "name": "AMC", "origin_country": "US", "tmdb_id": 174 }
]

Genres API

https://api.watchmode.com/v1/genres/

Return a mapping of genre names and IDs. Some genres have a tmdb_id, which is the corresponding genre ID on TheMovieDB.org API.

curl -i 'https://api.watchmode.com/v1/genres/?apiKey=YOUR_API_KEY'

<?php
// Set your API key here
$apiKey = 'YOUR_API_KEY';
$url = "https://api.watchmode.com/v1/genres/?apiKey={$apiKey}";

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_FOLLOWLOCATION, 1);
$response = curl_exec($ch);
curl_close($ch);

$json = json_decode($response);
print_r($json);

import urllib.request
import json

# Set your API key here
api_key = 'YOUR_API_KEY'
url = f'https://api.watchmode.com/v1/genres/?apiKey={api_key}'

with urllib.request.urlopen(url) as response:
    data = json.loads(response.read().decode())
    print(data)

// Set your API key here
const apiKey = 'YOUR_API_KEY';
const url = `https://api.watchmode.com/v1/genres/?apiKey=${apiKey}`;

const response = await fetch(url);
const json = await response.json();
console.log(json);

Response

[
  { "id": 4, "name": "Comedy", "tmdb_id": 35 },
  { "id": 6, "name": "Documentary", "tmdb_id": 99 },
  { "id": 33, "name": "Anime", "tmdb_id": null }
]

Search API

https://api.watchmode.com/v1/search/

Search for titles or people using an external ID (IMDB, TheMovieDB.org), or by name. Returns an array of results objects, that can either be a title or a person. Useful for getting the Watchmode IDs for titles and people. For example, you can set the parameters to search_value=Breaking%20Bad and search_field=name to get all of the titles named "Breaking bad", and then use the IDs returned in other endpoints such as /v1/title/

Parameter	Required	Description
search_field	required	string The field for us to search in, either a 3rd party ID or "name" which will search for a movie/show title or a person's name depending on the type(s) set. Must be one of the following options: imdb_id, tmdb_person_id, tmdb_movie_id, tmdb_tv_id, name.
search_value	required	string The value we should search for. For example, if you set search_field to imdb_id, this would be the IMDB title/person ID, eg. tt0944947.
types	optional	string Pass one of the following values, or multiple comma separated values to only return certain types: tv, movie, person.

curl -i 'https://api.watchmode.com/v1/search/?apiKey=YOUR_API_KEY&search_field=name&search_value=Ed%20Wood'

require 'net/http'
require 'uri'
require 'json'

uri = URI('https://api.watchmode.com/v1/search/?apiKey=YOUR_API_KEY&search_field=name&search_value=Ed%20Wood')
json = Net::HTTP.get(uri)
result = JSON(json)
print(result)

<?php
// Set your API key here
$apiKey = 'YOUR_API_KEY';
$searchField = 'name';
$searchValue = 'Ed Wood';
$url = "https://api.watchmode.com/v1/search/?apiKey={$apiKey}&search_field={$searchField}&search_value=" . urlencode($searchValue);

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_FOLLOWLOCATION, 1);
$response = curl_exec($ch);
curl_close($ch);

$json = json_decode($response);
print_r($json);

import urllib.request
import json
from urllib.parse import urlencode

# Set your API key here
api_key = 'YOUR_API_KEY'
search_field = 'name'
search_value = 'Ed Wood'

params = {
    'apiKey': api_key,
    'search_field': search_field,
    'search_value': search_value
}

url = f'https://api.watchmode.com/v1/search/?{urlencode(params)}'

with urllib.request.urlopen(url) as response:
    data = json.loads(response.read().decode())
    print(data)

// Set your API key here
const apiKey = 'YOUR_API_KEY';
const searchField = 'name';
const searchValue = 'Ed Wood';
const url = `https://api.watchmode.com/v1/search/?apiKey=${apiKey}&search_field=${searchField}&search_value=${encodeURIComponent(searchValue)}`;

const response = await fetch(url);
const json = await response.json();
console.log(json);

Response

{
  "title_results": [
    {
      "id": 1114888,
      "name": "Ed Wood",
      "type": "movie",
      "year": 1994,
      "imdb_id": "tt0109707",
      "tmdb_id": 522,
      "tmdb_type": "movie"
    }
  ],
  "people_results": [
    {
      "id": 710125611,
      "name": "Ed Wood",
      "main_profession": "cinematographer",
      "imdb_id": "nm7903892",
      "tmdb_id": 2901757
    }
  ]
}

Autocomplete API

https://api.watchmode.com/v1/autocomplete-search/

Search for titles/and or people by name or a partial name. Useful for building an autocomplete search of titles and/or people. The results include the field result_type to indicate which type of result it is (title or person). For titles, the movie poster will be returned in image_url, for a person a headshot will be returned in image_url.

Parameter	Required	Description
search_value	required	string The phrase to search for, can be a full title or person name, or a partial phrase. For example searching for "The sha" will find the movie "The Shawshank Redemption".
search_type	optional	int Set this to 1 to include titles and people in results. Set this to 2 to include titles only. Set this to 3 to include movies only. Set this to 4 to include TV only. Set this to 5 to include people only. By default this is set to 1.

curl -i 'https://api.watchmode.com/v1/autocomplete-search/?apiKey=YOUR_API_KEY&search_value=Breaking%20bad&search_type=1'

require 'net/http'
require 'uri'
require 'json'

uri = URI('https://api.watchmode.com/v1/autocomplete-search/?apiKey=YOUR_API_KEY&search_value=Breaking%20bad&search_type=1')
json = Net::HTTP.get(uri)
result = JSON(json)
print(result)

<?php
// Set your API key here
$apiKey = 'YOUR_API_KEY';
$searchValue = 'Breaking bad';
$searchType = 1; // 1 = include titles and people in results
$url = "https://api.watchmode.com/v1/autocomplete-search/?apiKey={$apiKey}&search_value=" . urlencode($searchValue) . "&search_type={$searchType}";

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_FOLLOWLOCATION, 1);
$response = curl_exec($ch);
curl_close($ch);

$json = json_decode($response);
print_r($json);

import urllib.request
import json
from urllib.parse import urlencode

# Set your API key here
api_key = 'YOUR_API_KEY'
search_value = 'Breaking bad'
search_type = 1  # 1 = include titles and people in results

params = {
    'apiKey': api_key,
    'search_value': search_value,
    'search_type': search_type
}

url = f'https://api.watchmode.com/v1/autocomplete-search/?{urlencode(params)}'

with urllib.request.urlopen(url) as response:
    data = json.loads(response.read().decode())
    print(data)

// Set your API key here
const apiKey = 'YOUR_API_KEY';
const searchValue = 'Breaking bad';
const searchType = 1; // 1 = include titles and people in results
const url = `https://api.watchmode.com/v1/autocomplete-search/?apiKey=${apiKey}&search_value=${encodeURIComponent(searchValue)}&search_type=${searchType}`;

const response = await fetch(url);
const json = await response.json();
console.log(json);

Response

{
  "results": [
    {
      "name": "Breaking Bad",
      "relevance": 445.23,
      "type": "tv_series",
      "id": 3173903,
      "year": 2008,
      "result_type": "title",
      "tmdb_id": 1396,
      "tmdb_type": "tv",
      "image_url": "https://cdn.watchmode.com/posters/03173903_poster_w185.jpg"
    },
    {
      "name": "El Camino: A Breaking Bad Movie",
      "relevance": 169.83,
      "type": "movie",
      "id": 1586594,
      "year": 2019,
      "result_type": "title",
      "tmdb_id": 559969,
      "tmdb_type": "movie",
      "image_url": "https://cdn.watchmode.com/posters/01586594_poster_w185.jpg"
    }
  ]
}

Title Details API

https://api.watchmode.com/v1/title/{title_id}/details/

Get the details for a specific title, using the Watchmode universal ID, TMDB ID, or IMDB ID. You can optionally append other title APIs to this response, using the append_to_response parameter.

Parameter	Required	Description
{title_id}	required	string Replace {title_id} in the URL with the title ID you want details for. This can be a numerical Watchmode title ID, or an IMDB ID, or you can use the TMDB type and id combination. For example, the TMDB combination for The Shawshank Redemption is movie-278 and for Breaking Bad is tv-1396. Using the Watchmode ID costs 1 against your quota, using IMDB or TMDB costs 2.
append_to_response	optional	string To add the results from one of the other /title/ endpoints to this request, pass one (or multiple comma separated) of the following values: sources, seasons, episodes, cast-crew. Each value you add will cost 1 additional credit.
language	optional	string Two letter iso_639_1 language code. Return the title and plot overview in the language of your choosing (default is EN). If this is set, and not to EN, then an additional field called english_title will be returned with the title in English if available.
regions	optional	string Pass one of the 2 character country codes from the /regions/ endpoint to filter the streaming source results to certain countries when using append_to_response=sources. Pass multiple countries by submitting them comma separated.

curl -i 'https://api.watchmode.com/v1/title/345534/details/?apiKey=YOUR_API_KEY'

<?php
// Set your API key here
$apiKey = 'YOUR_API_KEY';
$titleId = '345534';
$url = "https://api.watchmode.com/v1/title/{$titleId}/details/?apiKey={$apiKey}";

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_FOLLOWLOCATION, 1);
$response = curl_exec($ch);
curl_close($ch);

$json = json_decode($response);
print_r($json);

import urllib.request
import json

# Set your API key here
api_key = 'YOUR_API_KEY'
title_id = '345534'
url = f'https://api.watchmode.com/v1/title/{title_id}/details/?apiKey={api_key}'

with urllib.request.urlopen(url) as response:
    data = json.loads(response.read().decode())
    print(data)

// Set your API key here
const apiKey = 'YOUR_API_KEY';
const titleId = '345534';
const url = `https://api.watchmode.com/v1/title/${titleId}/details/?apiKey=${apiKey}`;

const response = await fetch(url);
const json = await response.json();
console.log(json);

Response

{
  "id": 3173903,
  "title": "Breaking Bad",
  "original_title": "Breaking Bad",
  "plot_overview": "When Walter White, a New Mexico chemistry teacher, is diagnosed with Stage III cancer and given a prognosis of only two years left to live. He becomes filled with a sense of fearlessness and an unrelenting desire to secure his family's financial future at any cost as he enters the dangerous world of drugs and crime.",
  "type": "tv_series",
  "runtime_minutes": 45,
  "year": 2008,
  "end_year": 2013,
  "release_date": "2008-01-20",
  "imdb_id": "tt0903747",
  "tmdb_id": 1396,
  "tmdb_type": "tv",
  "genres": [7],
  "genre_names": ["Drama"],
  "user_rating": 9.2,
  "critic_score": 85,
  "us_rating": "TV-MA",
  "poster": "https://cdn.watchmode.com/posters/03173903_poster_w185.jpg",
  "backdrop": "https://cdn.watchmode.com/backdrops/03173903_bd_w780.jpg",
  "original_language": "en",
  "networks": [8],
  "network_names": ["AMC"],
  "relevance_percentile": 98.92
}

Title Streaming Sources API

https://api.watchmode.com/v1/title/{title_id}/sources/

Get the streaming availability for a specific title. This endpoint will return all the sources (streaming services, digital purchase, rental services) where a title is currently available in the region specified. For TV shows, you can optionally filter to see what sources are available for specific seasons and episodes.

Parameter	Required	Description
{title_id}	required	string Replace {title_id} in the URL with the title ID you want sources for. This can be a numerical Watchmode title ID, an IMDB ID, or you can use the TMDB type and id combination. For example, the TMDB combination for The Shawshank Redemption is movie-278 and for Breaking Bad is tv-1396. Using the Watchmode ID costs 1 against your quota, using IMDB or TMDB costs 2.
regions	optional	string Pass one of the 2 character country codes from the /regions/ endpoint to filter the streaming source results to certain countries. By default the API will return all regions. Pass multiple countries by submitting them comma separated.

curl -i 'https://api.watchmode.com/v1/title/345534/sources/?apiKey=YOUR_API_KEY'

<?php
// Set your API key here
$apiKey = 'YOUR_API_KEY';
$titleId = '345534';
$url = "https://api.watchmode.com/v1/title/{$titleId}/sources/?apiKey={$apiKey}";

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_FOLLOWLOCATION, 1);
$response = curl_exec($ch);
curl_close($ch);

$json = json_decode($response);
print_r($json);

import urllib.request
import json

# Set your API key here
api_key = 'YOUR_API_KEY'
title_id = '345534'
url = f'https://api.watchmode.com/v1/title/{title_id}/sources/?apiKey={api_key}'

with urllib.request.urlopen(url) as response:
    data = json.loads(response.read().decode())
    print(data)

// Set your API key here
const apiKey = 'YOUR_API_KEY';
const titleId = '345534';
const url = `https://api.watchmode.com/v1/title/${titleId}/sources/?apiKey=${apiKey}`;

const response = await fetch(url);
const json = await response.json();
console.log(json);

Response

[
  {
    "source_id": 203,
    "name": "Netflix",
    "type": "sub",
    "region": "US",
    "ios_url": "https://www.netflix.com/title/123456",
    "android_url": "https://www.netflix.com/title/123456",
    "web_url": "https://www.netflix.com/title/123456",
    "format": "HD",
    "price": null,
    "seasons": null,
    "episodes": null
  }
]

Title Seasons API

https://api.watchmode.com/v1/title/{title_id}/seasons/

Return all of the seasons for a TV show or mini-series.

curl -i 'https://api.watchmode.com/v1/title/345534/seasons/?apiKey=YOUR_API_KEY'

<?php
// Set your API key here
$apiKey = 'YOUR_API_KEY';
$titleId = '345534';
$url = "https://api.watchmode.com/v1/title/{$titleId}/seasons/?apiKey={$apiKey}";

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_FOLLOWLOCATION, 1);
$response = curl_exec($ch);
curl_close($ch);

$json = json_decode($response);
print_r($json);

import urllib.request
import json

# Set your API key here
api_key = 'YOUR_API_KEY'
title_id = '345534'
url = f'https://api.watchmode.com/v1/title/{title_id}/seasons/?apiKey={api_key}'

with urllib.request.urlopen(url) as response:
    data = json.loads(response.read().decode())
    print(data)

// Set your API key here
const apiKey = 'YOUR_API_KEY';
const titleId = '345534';
const url = `https://api.watchmode.com/v1/title/${titleId}/seasons/?apiKey=${apiKey}`;

const response = await fetch(url);
const json = await response.json();
console.log(json);

Response

[
  {
    "season_number": 1,
    "name": "Season 1",
    "plot_overview": "Season 1 description...",
    "date_created": "2021-01-01",
    "tmdb_id": 12345
  }
]

Title Episodes API

https://api.watchmode.com/v1/title/{title_id}/episodes/

Return all of the episodes for a TV series or mini-series, as well as the streaming sources each episode is available on. Set &append_to_response=episodes to the title details endpoint above to get these results added to the title details response.

curl -i 'https://api.watchmode.com/v1/title/345534/episodes/?apiKey=YOUR_API_KEY'

<?php
// Set your API key here
$apiKey = 'YOUR_API_KEY';
$titleId = '345534';
$url = "https://api.watchmode.com/v1/title/{$titleId}/episodes/?apiKey={$apiKey}";

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_FOLLOWLOCATION, 1);
$response = curl_exec($ch);
curl_close($ch);

$json = json_decode($response);
print_r($json);

import urllib.request
import json

# Set your API key here
api_key = 'YOUR_API_KEY'
title_id = '345534'
url = f'https://api.watchmode.com/v1/title/{title_id}/episodes/?apiKey={api_key}'

with urllib.request.urlopen(url) as response:
    data = json.loads(response.read().decode())
    print(data)

// Set your API key here
const apiKey = 'YOUR_API_KEY';
const titleId = '345534';
const url = `https://api.watchmode.com/v1/title/${titleId}/episodes/?apiKey=${apiKey}`;

const response = await fetch(url);
const json = await response.json();
console.log(json);

Response

[
  {
    "id": 1234567,
    "title": "Pilot",
    "season_number": 1,
    "episode_number": 1,
    "air_date": "2008-01-20",
    "plot_overview": "Episode description...",
    "tmdb_id": 54321
  }
]

Title Cast/Crew API

https://api.watchmode.com/v1/title/{title_id}/cast-crew/

Return all people associated with the title, the "cast" (actors), and "crew" (directors, writers, cinematographers, etc). For more details on a person, pass the person-id to the /person/ endpoint. Set &append_to_response=cast-crew to the title details endpoint above to get these results added to the title details response.

curl -i 'https://api.watchmode.com/v1/title/345534/cast-crew/?apiKey=YOUR_API_KEY'

<?php
// Set your API key here
$apiKey = 'YOUR_API_KEY';
$titleId = '345534';
$url = "https://api.watchmode.com/v1/title/{$titleId}/cast-crew/?apiKey={$apiKey}";

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_FOLLOWLOCATION, 1);
$response = curl_exec($ch);
curl_close($ch);

$json = json_decode($response);
print_r($json);

import urllib.request
import json

# Set your API key here
api_key = 'YOUR_API_KEY'
title_id = '345534'
url = f'https://api.watchmode.com/v1/title/{title_id}/cast-crew/?apiKey={api_key}'

with urllib.request.urlopen(url) as response:
    data = json.loads(response.read().decode())
    print(data)

// Set your API key here
const apiKey = 'YOUR_API_KEY';
const titleId = '345534';
const url = `https://api.watchmode.com/v1/title/${titleId}/cast-crew/?apiKey=${apiKey}`;

const response = await fetch(url);
const json = await response.json();
console.log(json);

Response

{
  "cast": [
    {
      "id": 7110004,
      "name": "Johnny Depp",
      "character_name": "Ed Wood",
      "is_male": true,
      "tmdb_id": 85
    }
  ],
  "crew": [
    {
      "id": 7110005,
      "name": "Tim Burton",
      "job": "Director",
      "is_male": true,
      "tmdb_id": 510
    }
  ]
}

List Titles API

https://api.watchmode.com/v1/list-titles/

Get a listing of titles that match certain parameters. This powerful endpoint can allow you to find many combinations of titles. For example you could search for something as granular "Horror Movies Streaming on Netflix in the USA" by using the genres, types, source_ids and regions parameters.

Results are paginated, and return 250 pages per query by default. Useful for mapping all Watchmode title IDs in your app, and finding in bulk what titles are available in different countries, different sources or source types.

Parameter	Required	Description
types	optional	stringFilter result to only include certain types of titles. Pass a single type or pass multiple types comma delimited. Possible values: movie, tv_series, tv_special, tv_miniseries, short_film
regions	optional	stringPass one of the region values (eg. US), or multiple regions comma delimited to only return sources active in those regions. For a full list of supported regions see the: Regions Endpoint Note: If you populate the source_ids or source_types you can only set a single region, and if you set no region US will be set by default. Each additional region will cost 1 API credit.
languages	optional	stringPass one 2 character ISO 639 language codes (eg. en), or multiple languages comma delimited to only return titles with the primary language matching your selected languages.
source_types	optional	stringFilter results to only include titles that are available on a specific type(s) of source (such a subscription, or TV Everywhere channel apps, etc). By default all are selected, pass one or multiple (comma delimited) of these values: sub, rent, buy, free, tve Note: If you populate this you can only set a single region, and if you set no region US will be set by default.
source_ids	optional	stringPass an individual ID for a source (returned from the /sources/ endpoint) to filter the results to titles available on that source. Pass multiple values comma separated to return titles available on one of the sources you pass in. Note: If you populate this you can only set a single region, and if you set no region US will be set by default.
genres	optional	stringFilter results to only include certain genre(s). Pass in a single genre id (which you would get from the /v1/genres/ endpoint, or multiple comma separated.
network_ids	optional	stringPass an individual ID for a TV network (returned from the /networks/ endpoint) to filter the results to titles the originally aired on that TV network. Pass multiple values comma separated to return titles that aired on one of the networks you passed in.
sort_by	optional	stringSort order of results, possible values: relevance_desc, relevance_asc, popularity_desc, popularity_asc, release_date_desc, release_date_asc, title_desc, title_asc. Default value is: relevance_desc.
release_date_start	optional	intSet the start of a range for when the title was released (the initial release of the movie or show, not necessarily when it was released on a streaming service). For example, to only include releases on or after January 1, 2001 set this to 20010101
release_date_end	optional	intSet the end of a range for when the title was released (the initial release of the movie or show, not necessarily when it was released on a streaming service). For example, to only include releases on or before December 11, 2020 set this to 20201211
user_rating_high	optional	intOn a scale of 0-10, this parameter can limit the titles to those with user ratings including or below this number.
user_rating_low	optional	intOn a scale of 0-10, this parameter can limit the titles to those with user ratings including or above this number.
critic_score_high	optional	intOn a scale of 0-100, this parameter can limit the titles to those with critic scores including or below this number.
critic_score_low	optional	intOn a scale of 0-100, this parameter can limit the titles to those with critic scores including or above this number.
page	optional	intSet the page of results you want to return, if this isn't set you will always get page 1 returned.
limit	optional	intSet how many titles to return per page, default and maximum is 250.

curl -i 'https://api.watchmode.com/v1/list-titles/?apiKey=YOUR_API_KEY&source_ids=203,57'

require 'net/http'
require 'uri'
require 'json'

uri = URI('https://api.watchmode.com/v1/list-titles/?apiKey=YOUR_API_KEY&source_ids=203,57')
json = Net::HTTP.get(uri)
result = JSON(json)
print(result)

<?php
// Set your API key here
$apiKey = 'YOUR_API_KEY';
$sourceIds = '203,57';
$url = "https://api.watchmode.com/v1/list-titles/?apiKey={$apiKey}&source_ids={$sourceIds}";

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_FOLLOWLOCATION, 1);
$response = curl_exec($ch);
curl_close($ch);

$json = json_decode($response);
print_r($json);

import urllib.request
import json

# Set your API key here
api_key = 'YOUR_API_KEY'
source_ids = '203,57'
url = f'https://api.watchmode.com/v1/list-titles/?apiKey={api_key}&source_ids={source_ids}'

with urllib.request.urlopen(url) as response:
    data = json.loads(response.read().decode())
    print(data)

// Set your API key here
const apiKey = 'YOUR_API_KEY';
const sourceIds = '203,57';
const url = `https://api.watchmode.com/v1/list-titles/?apiKey=${apiKey}&source_ids=${sourceIds}`;

const response = await fetch(url);
const json = await response.json();
console.log(json);

Response

{
  "titles": [
    {
      "id": 1337513,
      "title": "Secret in Their Eyes",
      "year": 2015,
      "imdb_id": "tt1741273",
      "tmdb_id": 290751,
      "tmdb_type": "movie",
      "type": "movie"
    },
    {
      "id": 1247225,
      "title": "Spy Cat",
      "year": 2018,
      "imdb_id": "tt5746054",
      "tmdb_id": 509733,
      "tmdb_type": "movie",
      "type": "movie"
    }
  ],
  "page": 1,
  "total_results": 4592,
  "total_pages": 19
}

Streaming Releases API

/v1/releases/

Get a listing of recently released or coming soon releases on the major streaming services. Only major services and US releases dates included, however most of the major services (Netflix, Hulu, etc) release original content on the same days in all countries they support. We return is_original field to indicate whether the title is an original release on that streaming service.

curl -i 'https://api.watchmode.com/v1/releases/?apiKey=YOUR_API_KEY'

<?php
// Set your API key here
$apiKey = 'YOUR_API_KEY';
$url = "https://api.watchmode.com/v1/releases/?apiKey={$apiKey}";

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_FOLLOWLOCATION, 1);
$response = curl_exec($ch);
curl_close($ch);

$json = json_decode($response);
print_r($json);

import urllib.request
import json

# Set your API key here
api_key = 'YOUR_API_KEY'
url = f'https://api.watchmode.com/v1/releases/?apiKey={api_key}'

with urllib.request.urlopen(url) as response:
    data = json.loads(response.read().decode())
    print(data)

// Set your API key here
const apiKey = 'YOUR_API_KEY';
const url = `https://api.watchmode.com/v1/releases/?apiKey=${apiKey}`;

const response = await fetch(url);
const json = await response.json();
console.log(json);

Response

{
  "releases": [
    {
      "id": 3165490,
      "title": "Slow Horses",
      "type": "tv_series",
      "tmdb_id": 95480,
      "tmdb_type": "tv",
      "imdb_id": "tt5875444",
      "season_number": 1,
      "poster_url": "https://cdn.watchmode.com/posters/03165490_poster_w185.jpg",
      "source_release_date": "2022-04-01",
      "source_id": 371,
      "source_name": "AppleTV+",
      "is_original": 1
    },
    {
      "id": 3175997,
      "title": "Luxe Listings Sydney",
      "type": "tv_series",
      "tmdb_id": 128912,
      "tmdb_type": "tv",
      "imdb_id": "tt14344354",
      "season_number": 2,
      "poster_url": "https://cdn.watchmode.com/posters/03175997_poster_w185.jpg",
      "source_release_date": "2022-04-01",
      "source_id": 26,
      "source_name": "Amazon Prime",
      "is_original": 1
    },
    {
      "id": 1623745,
      "title": "The Bubble",
      "type": "movie",
      "tmdb_id": 765119,
      "tmdb_type": "movie",
      "imdb_id": "tt13610562",
      "season_number": null,
      "poster_url": "https://cdn.watchmode.com/posters/01623745_poster_w185.jpg",
      "source_release_date": "2022-04-01",
      "source_id": 203,
      "source_name": "Netflix",
      "is_original": 0
    }
  ]
}

Person API

https://api.watchmode.com/v1/person/{id}/

Get detailed information about a person including their biographical data, filmography, and known titles. Returns information about actors, directors, writers, and other industry professionals.

curl -i 'https://api.watchmode.com/v1/person/7110004?apiKey=YOUR_API_KEY'

<?php
// Set your API key here
$apiKey = 'YOUR_API_KEY';
$personId = '7110004';
$url = "https://api.watchmode.com/v1/person/{$personId}?apiKey={$apiKey}";

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_FOLLOWLOCATION, 1);
$response = curl_exec($ch);
curl_close($ch);

$json = json_decode($response);
print_r($json);

import urllib.request
import json

# Set your API key here
api_key = 'YOUR_API_KEY'
person_id = '7110004'
url = f'https://api.watchmode.com/v1/person/{person_id}?apiKey={api_key}'

with urllib.request.urlopen(url) as response:
    data = json.loads(response.read().decode())
    print(data)

// Set your API key here
const apiKey = 'YOUR_API_KEY';
const personId = '7110004';
const url = `https://api.watchmode.com/v1/person/${personId}?apiKey=${apiKey}`;

const response = await fetch(url);
const json = await response.json();
console.log(json);

Response

{
  "id": 7110004,
  "full_name": "Brad Pitt",
  "first_name": "Brad",
  "last_name": "Pitt",
  "tmdb_id": 287,
  "imdb_id": "nm0000093",
  "main_profession": "actor",
  "secondary_profession": "producer",
  "tertiary_profession": "soundtrack",
  "date_of_birth": "1963-12-18",
  "date_of_death": null,
  "place_of_birth": "Shawnee, Oklahoma, USA",
  "gender": "m",
  "headshot_url": "https://cdn.watchmode.com/profiles/07110004_profile_185.jpg",
  "known_for": [1132806, 1336708, 1183315, 1387087],
  "relevance_percentile": 100
}

New Titles

/v1/changes/new_titles/

Get a listing of the title IDs of new titles added to Watchmode within the date range. Useful for keeping your database of titles in sync with Watchmode's as we add new movies & shows to the database.

curl -i 'https://api.watchmode.com/v1/changes/new_titles?apiKey=YOUR_API_KEY&types=movie,tv_series'

require 'net/http'
require 'uri'
require 'json'

uri = URI('https://api.watchmode.com/v1/changes/new_titles?apiKey=YOUR_API_KEY&types=movie,tv_series')
json = Net::HTTP.get(uri)
result = JSON(json)
print(result)

<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://api.watchmode.com/v1/changes/new_titles?apiKey=YOUR_API_KEY&types=movie,tv_series');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_FOLLOWLOCATION, 1);
$response = curl_exec($ch);
curl_close($ch);

$json = json_decode($response);
print_r($json);

import urllib.request
import json
with urllib.request.urlopen("https://api.watchmode.com/v1/changes/new_titles?apiKey=YOUR_API_KEY&types=movie,tv_series") as url:
    data = json.loads(url.read().decode())
    print(data)

// Set your API key here
const apiKey = 'YOUR_API_KEY';
const types = 'movie,tv_series';
const url = `https://api.watchmode.com/v1/changes/new_titles?apiKey=${apiKey}&types=${types}`;

const response = await fetch(url);
const json = await response.json();
console.log(json);

Response

{
  "titles": [
    1138,
    1668,
    1867,
    11029,
    11045,
    11173,
    11394
  ],
  "page": 1,
  "total_results": 6513,
  "total_pages": 27
}

New People

/v1/changes/new_people/

Get a listing of the ids of new people added to Watchmode within the date range. Useful if you have your own database of people and want to keep the Watchmode IDs in sync in your database.

curl -i 'https://api.watchmode.com/v1/changes/new_people/?apiKey=YOUR_API_KEY'

<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://api.watchmode.com/v1/changes/new_people/?apiKey=YOUR_API_KEY');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_FOLLOWLOCATION, 1);
$response = curl_exec($ch);
curl_close($ch);

$json = json_decode($response);
print_r($json);

import urllib.request
import json
with urllib.request.urlopen("https://api.watchmode.com/v1/changes/new_people/?apiKey=YOUR_API_KEY") as url:
    data = json.loads(url.read().decode())
    print(data)

// Set your API key here
const apiKey = 'YOUR_API_KEY';
const url = `https://api.watchmode.com/v1/changes/new_people/?apiKey=${apiKey}`;

const response = await fetch(url);
const json = await response.json();
console.log(json);

Response

{
  "people": [
    710203130,
    73333445,
    710203131,
    710203132,
    710203133,
    710203134,
    710203135
  ],
  "page": 1,
  "total_results": 15113,
  "total_pages": 61
}

Titles with Changed Sources

/v1/changes/titles_sources_changed/

Get a listing of titles that have changed to their streaming sources within the date range.

curl -i 'https://api.watchmode.com/v1/changes/titles_sources_changed/?apiKey=YOUR_API_KEY'

require 'net/http'
require 'uri'
require 'json'

uri = URI('https://api.watchmode.com/v1/changes/titles_sources_changed/?apiKey=YOUR_API_KEY')
json = Net::HTTP.get(uri)
result = JSON(json)
print(result)

<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://api.watchmode.com/v1/changes/titles_sources_changed/?apiKey=YOUR_API_KEY');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_FOLLOWLOCATION, 1);
$response = curl_exec($ch);
curl_close($ch);

$json = json_decode($response);
print_r($json);

import urllib.request
import json
with urllib.request.urlopen("https://api.watchmode.com/v1/changes/titles_sources_changed/?apiKey=YOUR_API_KEY") as url:
    data = json.loads(url.read().decode())
    print(data)

// Set your API key here
const apiKey = 'YOUR_API_KEY';
const url = `https://api.watchmode.com/v1/changes/titles_sources_changed/?apiKey=${apiKey}`;

const response = await fetch(url);
const json = await response.json();
console.log(json);

Response

{
  "titles": [
    12490,
    115801,
    144030,
    144341,
    160295,
    160558,
    163623,
    164792,
    193679
  ],
  "page": 1,
  "total_results": 488,
  "total_pages": 2
}

Titles with Changed Details

/v1/changes/titles_details_changed/

Get a listing of titles that have had a change to their basic details (overview, cast, genres, ratings, etc) within the date range.

curl -i 'https://api.watchmode.com/v1/changes/titles_details_changed/?apiKey=YOUR_API_KEY'

require 'net/http'
require 'uri'
require 'json'

uri = URI('https://api.watchmode.com/v1/changes/titles_details_changed/?apiKey=YOUR_API_KEY')
json = Net::HTTP.get(uri)
result = JSON(json)
print(result)

<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://api.watchmode.com/v1/changes/titles_details_changed/?apiKey=YOUR_API_KEY');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_FOLLOWLOCATION, 1);
$response = curl_exec($ch);
curl_close($ch);

$json = json_decode($response);
print_r($json);

import urllib.request
import json
with urllib.request.urlopen("https://api.watchmode.com/v1/changes/titles_details_changed/?apiKey=YOUR_API_KEY") as url:
    data = json.loads(url.read().decode())
    print(data)

// Set your API key here
const apiKey = 'YOUR_API_KEY';
const url = `https://api.watchmode.com/v1/changes/titles_details_changed/?apiKey=${apiKey}`;

const response = await fetch(url);
const json = await response.json();
console.log(json);

Response

{
  "titles": [
    3171655,
    3127447,
    3146794,
    340763,
    361062,
    345333,
    3171642,
    3102697,
    3168127,
    3168998,
    536562
  ],
  "page": 1,
  "total_results": 14,
  "total_pages": 1
}

Titles with Changed Episodes

/v1/changes/titles_episodes_changed/

Get a listing of titles that have changes to their episodes (new episodes, episode details changed, etc) within the date range.

curl -i 'https://api.watchmode.com/v1/changes/titles_episodes_changed/?apiKey=YOUR_API_KEY'

require 'net/http'
require 'uri'
require 'json'

uri = URI('https://api.watchmode.com/v1/changes/titles_episodes_changed/?apiKey=YOUR_API_KEY')
json = Net::HTTP.get(uri)
result = JSON(json)
print(result)

<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://api.watchmode.com/v1/changes/titles_episodes_changed/?apiKey=YOUR_API_KEY');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_FOLLOWLOCATION, 1);
$response = curl_exec($ch);
curl_close($ch);

$json = json_decode($response);
print_r($json);

import urllib.request
import json
with urllib.request.urlopen("https://api.watchmode.com/v1/changes/titles_episodes_changed/?apiKey=YOUR_API_KEY") as url:
    data = json.loads(url.read().decode())
    print(data)

// Set your API key here
const apiKey = 'YOUR_API_KEY';
const url = `https://api.watchmode.com/v1/changes/titles_episodes_changed/?apiKey=${apiKey}`;

const response = await fetch(url);
const json = await response.json();
console.log(json);

Response

{
  "titles": [
    3123402,
    3165766,
    3107530,
    3117639,
    329319,
    3124749,
    3145191,
    3163842,
    3165473,
    371881
  ],
  "page": 1,
  "total_results": 130,
  "total_pages": 1
}