API

A show's base.json contains all of its seasons and episodes, so one request gets the whole show. Names and descriptions for the show, its seasons and its episodes are in the language files.

Files

https://api.watchittrackit.com/v1/tv/{id}/base.json
https://api.watchittrackit.com/v1/tv/{id}/{lang}.json
https://api.watchittrackit.com/v1/tv/slugs/{shard}.json

An image is an object with full and thumb paths.

base.json

Field	Type	Description
type	string	Record type.
id	number	TheTVDB id.
slug	string	URL slug, unique within the type.
popularity	number	TheTVDB popularity score; higher is more popular. Scores are comparable within a type only.
deleted	boolean	True if the record was removed. Its files stay published.
firstAired	string	Date of the first episode (YYYY-MM-DD).
lastAired	string	Date of the latest episode.
status	string	Airing status from TheTVDB, such as Continuing or Ended.
network	string	Network.
originalLanguage	string	Original language code.
originalCountry	string	Original country (three-letter code).
image	image	Main image: a poster for titles, a photo for people.
images	{ [kind]: image }	The best image of each kind: poster, background, banner, icon, clearart, clearlogo.
imagesByLang	{ [kind]: image[] }	Per kind, the best image in each language, with its language code, size and score.
cast	credit[]	Actors, in billing order.
crew	credit[]	Everyone else credited, with their job.
topBilledIds	number[]	Ids of people to feature first.
seasons	season[]	Seasons in aired order, each with its episodes.
genres	string[]	Genre slugs, as TheTVDB defines them.
languages	string[]	Languages this record has files for.
remoteIds	{ [site]: string }	Ids on other sites (imdb, tmdb, wikidata, …), keyed by site.

Example

{
  "type": "tv",
  "id": 81189,
  "slug": "breaking-bad",
  "popularity": 3287090,
  "deleted": false,
  "firstAired": "2008-01-20",
  "lastAired": "2013-09-29",
  "status": "Ended",
  "images": {
    "poster": { "full": "/images/tv/81189/1340353429.jpg", "thumb": "/images/tv/81189/1340353429.t.jpg" }
  },
  "cast": [
    { "id": 255211, "activityId": 180, "role": "Walter White", "slug": "bryan-cranston", "topBilled": false, "deleted": false }
  ],
  "seasons": [
    {
      "id": 30272, "number": 1, "deleted": false,
      "episodes": [{ "id": 349232, "number": 1, "aired": "2008-01-20", "runtime": 58, "deleted": false }]
    }
  ],
  "genres": ["drama", "crime"],
  "languages": ["de", "en", "fr"],
  "remoteIds": { "imdb": "tt0903747" }
}

Seasons

Field	Type	Description
id	number	TheTVDB id.
number	number	Season number; 0 is specials.
deleted	boolean	True if the record was removed. Its files stay published.
image	image	Main image: a poster for titles, a photo for people.
images	{ [kind]: image }	The best image of each kind: poster, background, banner, icon, clearart, clearlogo.
imagesByLang	{ [kind]: image[] }	Per kind, the best image in each language, with its language code, size and score.
episodes	episode[]	The season's episodes.

Episodes

Field	Type	Description
id	number	TheTVDB id.
number	number	Episode number within its season.
aired	string	Air date (YYYY-MM-DD).
runtime	number	Length in minutes.
image	image	Main image: a poster for titles, a photo for people.
criticalToStory	boolean	Marked as essential to the story.
specialType	string	What kind of special it is (season 0 episodes).
deleted	boolean	True if the record was removed. Its files stay published.

Credits

Each entry in cast and crew:

Field	Type	Description
id	number	Person id.
activityId	number	Credit id, unique per credit.
role	string	Character played (cast).
job	string	Job (crew): director, writer, producer, …
slug	string	The person's slug.
image	image	The person's photo.
topBilled	boolean	A featured credit.
deleted	boolean	True if the person was removed.

Language files

Field	Type	Description
type	string	Record type.
id	number	TheTVDB id.
lang	string	Language of this file.
name	string	Name in this language.
overview	string	Description in this language.
credits	{ [personId]: { name, role } }	Per person id: their name in this language and their role.
seasons	{ [seasonId]: { name, overview } }	Per season id: its name and description.
episodes	{ [episodeId]: { name, overview } }	Per episode id: its name and description.

Example

{
  "type": "tv",
  "id": 81189,
  "lang": "en",
  "name": "Breaking Bad",
  "overview": "When Walter White, a chemistry teacher, …",
  "credits": { "255211": { "name": "Bryan Cranston", "role": "Walter White" } },
  "seasons": { "30272": { "overview": "High school chemistry teacher Walter White…" } },
  "episodes": { "349232": { "name": "Pilot", "overview": "When an unassuming high school chemistry teacher…" } }
}

Finding a title by its slug

Show and movie URLs use slugs (breaking-bad). The slug index maps each slug to its id, split into 256 small files: a slug's file is named by the first two hex characters of the SHA-1 of the slug.

// Node.js
import { createHash } from "node:crypto"

const slug = "breaking-bad"
const shard = createHash("sha1").update(slug, "utf8").digest("hex").slice(0, 2)
const index = await fetch(`https://api.watchittrackit.com/v1/tv/slugs/${shard}.json`).then((r) => r.json())
const id = index[slug]
const record = await fetch(`https://api.watchittrackit.com/v1/tv/${id}/base.json`).then((r) => r.json())