TVDB

Overview

The TVDB API offers a programmatic interface to a database of television series, movies, and anime, along with associated metadata. Founded in 2005, TheTVDB serves as a resource for developers and media enthusiasts seeking structured data about visual content. The API is designed for applications that require detailed information on titles, including episode lists, cast and crew details, production company information, and genre classifications. It supports various use cases, from populating personal media libraries with accurate metadata to powering commercial content recommendation engines.

Developers can utilize the TVDB API to enrich user experiences in applications such as media center software, mobile content guides, and streaming service companions. The API provides access to data points like artwork, ratings, plot summaries, and release dates, which can be integrated to create dynamic content displays or search functionalities. The platform is owned by Whip Media Group, which maintains the database and API infrastructure. Access is provided through an OAuth 2.0 based authentication system, requiring developers to obtain an API key and token for making authenticated requests.

The core products accessible via the API include metadata for TV series, movies, and anime. Additionally, it offers data on companies involved in production and distribution, and tools for list management, allowing users to curate and retrieve custom collections of content. This range of data points positions the TVDB API as a resource for platforms focused on content discovery and media organization. For example, a developer building a media library application might use the API to automatically fetch episode titles and descriptions for a user's local video files, enhancing the browsing experience. The API's documentation is wiki-based, offering detailed endpoint descriptions and examples for integration.

Key features

• TV series metadata API: Access comprehensive data for television shows, including episode guides, cast, crew, genres, and artwork.
• Movie metadata API: Retrieve details for films, such as release dates, plot summaries, cast lists, and poster art.
• Anime metadata API: Specialized data endpoints for anime series and films, covering specific genres and production details relevant to anime.
• Company metadata API: Obtain information about production companies, distributors, and other entities involved in media creation.
• List management API: Programmatically create, update, and retrieve custom lists of TV series, movies, or anime, enabling personalized content curation.
• OAuth 2.0 authentication: Secure access to the API using industry-standard OAuth 2.0 for token-based authorization.
• Wiki-based documentation: Detailed endpoint descriptions, request/response examples, and usage guidelines available on a comprehensive wiki.

Pricing

As of May 2026, TheTVDB offers a free developer plan and several paid subscription tiers:

For the most current pricing details and plan specifics, refer to the official TheTVDB API pricing page.

Common integrations

• Media Center Software: Integrate with applications like Plex or Kodi to automatically fetch and display metadata for local media files.
• Content Discovery Platforms: Power search and recommendation features within streaming guides or content aggregation apps.
• Personal Media Organizers: Enhance user-created media libraries with accurate show and movie details, artwork, and episode information.
• Mobile Entertainment Apps: Develop mobile applications that provide users with information about TV shows, movies, and anime on the go.

Alternatives

• TMDB (The Movie Database): Offers a community-built database primarily focused on movies, with TV show data also available, providing similar metadata services.
• OMDb API: A free API that provides movie and series information, often used for quick lookups and smaller projects.
• IMDb API (RapidAPI): Provides access to IMDb's extensive database, typically through third-party wrappers or unofficial APIs given IMDb's limited official public API.

Getting started

To begin using the TVDB API, developers first need to register for a developer account and obtain an API key. This key is used to authenticate requests and access the available metadata endpoints. The API uses an OAuth 2.0 flow for authentication, where an initial login request exchanges user credentials for an access token. This token then authorizes subsequent API calls. The following example demonstrates a basic Python script to obtain an access token and fetch a list of recent updates, assuming requests library is installed.

import requests
import json

API_KEY = "YOUR_API_KEY" # Replace with your actual API key
PIN = "YOUR_PIN"         # Replace with your actual PIN (from TheTVDB account)

AUTH_URL = "https://api4.thetvdb.com/v4/login"
HEADERS = {
    "Content-Type": "application/json",
    "Accept": "application/json"
}

# Step 1: Obtain an access token
def get_access_token(api_key, pin):
    payload = json.dumps({
        "apikey": api_key,
        "pin": pin
    })
    try:
        response = requests.post(AUTH_URL, headers=HEADERS, data=payload)
        response.raise_for_status() # Raise an exception for HTTP errors
        token_data = response.json()
        return token_data.get("data", {}).get("token")
    except requests.exceptions.RequestException as e:
        print(f"Error during authentication: {e}")
        return None

# Step 2: Make an authenticated API call (e.g., get recent updates)
def get_recent_updates(token):
    if not token:
        print("No access token available. Cannot fetch updates.")
        return

    updates_url = "https://api4.thetvdb.com/v4/updates/latest"
    auth_headers = {
        "Authorization": f"Bearer {token}",
        "Accept": "application/json"
    }
    try:
        response = requests.get(updates_url, headers=auth_headers)
        response.raise_for_status()
        return response.json()
    except requests.exceptions.RequestException as e:
        print(f"Error fetching updates: {e}")
        return None

if __name__ == "__main__":
    access_token = get_access_token(API_KEY, PIN)
    if access_token:
        print("Successfully obtained access token.")
        # Example: Fetch and print some recent updates
        updates_data = get_recent_updates(access_token)
        if updates_data:
            print("\nRecent Updates (first 3 items):")
            for item in updates_data.get("data", [])[:3]:
                print(f"  Type: {item.get('type')}, ID: {item.get('id')}, Last Modified: {item.get('lastModified')}")
        else:
            print("Failed to retrieve recent updates.")
    else:
        print("Authentication failed. Please check your API key and PIN.")

This script first defines a function get_access_token to handle the OAuth 2.0 login, then uses the returned token in get_recent_updates to fetch data. Developers should replace "YOUR_API_KEY" and "YOUR_PIN" with their actual credentials obtained from TheTVDB's developer portal. The API reference on the TVDB wiki provides detailed information on all available endpoints and data structures.