TVDB SDKs & Libraries: Official & Community Tools (2026)

SDKs overview

The TVDB API provides programmatic access to a comprehensive database of television series, movies, anime, and company metadata. To facilitate integration for developers, various SDKs (Software Development Kits) and client libraries are available. These tools abstract the complexities of direct HTTP requests, managing aspects such as OAuth 2.0 authentication, request parameter serialization, and JSON response deserialization. Using an SDK can reduce the boilerplate code required to interact with the TVDB API, allowing developers to focus on application logic rather than API communication specifics.

The TVDB API utilizes an OAuth 2.0-based authentication system, requiring client applications to obtain an access token before making authenticated requests. SDKs typically handle the token acquisition and refresh process, simplifying secure access to data. The official documentation for the TVDB API, including its V4 API Reference, details the available endpoints and data models.

Official SDKs by language

TVDB provides official SDKs to streamline development across several popular programming languages. These SDKs are maintained by TheTVDB team and are designed to offer a consistent and reliable interface for interacting with the API. They generally align with the latest API versions and best practices for each language environment. Below is a summary of the official SDKs available:

These official SDKs are typically the recommended starting point for new projects due to their direct support from TheTVDB and adherence to API specifications. Developers can find more detailed information and usage examples within the TVDB developer wiki.

Installation

Installing TVDB SDKs typically involves using the package manager specific to the programming language. The following examples demonstrate common installation methods for the officially supported languages.

Python

To install the official Python SDK, use pip:

pip install thetvdb-api

Node.js

For Node.js environments, install the SDK using npm or yarn:

npm install thetvdb-api-v4
# or
yarn add thetvdb-api-v4

PHP

For PHP projects, use Composer to add the SDK to your dependencies:

composer require thetvdb/api

After installation, ensure that your project's dependencies are correctly configured to use the SDK. Refer to the specific SDK's documentation for any additional setup or configuration steps, such as environment variables for API keys or client secrets.

Quickstart example

The following quickstart examples illustrate how to initialize an SDK, authenticate, and make a basic API call to retrieve TV series information. These snippets assume you have already obtained an API key and, where necessary, a user key from your TVDB developer account.

Python Quickstart

This Python example demonstrates authenticating and searching for a TV series:

from thetvdb_api import TheTVDB

API_KEY = "YOUR_API_KEY"
USER_KEY = "YOUR_USER_KEY" # May not be needed for all V4 endpoints

def main():
    try:
        tvdb = TheTVDB(api_key=API_KEY, user_key=USER_KEY)
        
        # Authenticate and get a token (handled internally by some SDKs)
        # For V4, typically you'd get a JWT token first
        # This example assumes the SDK handles the initial token request
        token = tvdb.login() # Placeholder, actual V4 login might differ
        print(f"Authenticated. Token: {token[:10]}...")

        # Search for a series (example for a V4-like search)
        search_results = tvdb.search_series("The Office") # Placeholder method
        if search_results:
            print("Found series:")
            for series in search_results:
                print(f"- {series['name']} (ID: {series['id']})")
        else:
            print("No series found.")

    except Exception as e:
        print(f"An error occurred: {e}")

if __name__ == "__main__":
    main()

Node.js Quickstart

This Node.js example shows how to authenticate and fetch data:

const { TheTVDB } = require('thetvdb-api-v4');

const API_KEY = 'YOUR_API_KEY';
const PIN = 'YOUR_PIN'; // Often used for V4 authentication

async function main() {
    try {
        const client = new TheTVDB(API_KEY);
        await client.authenticate(PIN); // Authenticate with PIN
        console.log('Authenticated successfully.');

        // Search for a series
        const searchResults = await client.search('The Mandalorian', 'series');
        if (searchResults && searchResults.data.length > 0) {
            console.log('Found series:');
            searchResults.data.forEach(series => {
                console.log(`- ${series.name} (ID: ${series.id})`);
            });
        } else {
            console.log('No series found.');
        }

    } catch (error) {
        console.error('Error:', error.message);
    }
}

main();

PHP Quickstart

This PHP example demonstrates client initialization and a basic API call:

<?php

require 'vendor/autoload.php';

use TheTVDB\Client;
use TheTVDB\Auth\PinAuthenticator;

$apiKey = 'YOUR_API_KEY';
$pin = 'YOUR_PIN';

try {
    $authenticator = new PinAuthenticator($apiKey, $pin);
    $client = new Client($authenticator);

    // Authenticate and get a token (handled internally)
    $token = $client->authenticate();
    echo "Authenticated. Token: " . substr($token, 0, 10) . "...\n";

    // Search for a series
    $searchResults = $client->search->search('Game of Thrones', ['type' => 'series']);
    
    if (!empty($searchResults->data)) {
        echo "Found series:\n";
        foreach ($searchResults->data as $series) {
            echo "- " . $series->name . " (ID: " . $series->id . ")\n";
        }
    } else {
        echo "No series found.\n";
    }

} catch (Exception $e) {
    echo "An error occurred: " . $e->getMessage() . "\n";
}

?>

These examples provide a foundational understanding of how to interact with the TVDB API using its respective SDKs. For more advanced features, error handling, and specific endpoint usage, consult the TVDB V4 API Reference and the documentation for each SDK.

Community libraries

Beyond the officially supported SDKs, the TVDB ecosystem benefits from various community-contributed libraries. These libraries, developed and maintained by third-party developers, often offer support for additional programming languages or provide alternative approaches to API interaction. While not officially supported by TheTVDB, they can be valuable resources for developers working in specific environments or requiring custom functionalities.

When considering a community library, it is advisable to evaluate its active maintenance, community support, and compatibility with the latest TVDB API versions. Developers should check the library's repository for recent updates, issue tracking, and documentation. Popular platforms like GitHub and language-specific package registries (e.g., PyPI, npm, Packagist) are common places to discover these libraries.

Examples of community contributions might include:

• Ruby clients: Libraries for Ruby on Rails or other Ruby applications.
• GoLang wrappers: Implementations for Go projects.
• C#/.NET clients: SDKs for .NET framework or .NET Core applications.
• Mobile-specific libraries: Clients optimized for Android (Java/Kotlin) or iOS (Swift/Objective-C) development.

Developers are encouraged to explore these options based on their project requirements and programming language preferences. Always verify the library's licensing and security practices before integrating it into a production environment. The TVDB developer wiki or community forums may also list recommended or frequently used third-party tools.