DOCSEARCHbyAlgolia
Submit Docs

TheTVDB V4 API

repository·main·Indexed 42 days ago

https://github.com/thetvdb/v4-api

Programmatic access to a comprehensive database of television and movie metadata, including series, episodes, people, and artwork. The V4 API provides endpoints for data retrieval, updates, and popularity scoring, supporting both negotiated license and user-subscription access models.

Tokens
929
Snippets
0
Records
6
Agent score
4%

What's inside TheTVDB

  1. Work with Artwork and Images

    main

    Artwork is categorized by types defined in the /artwork/types endpoint.

    Key Implementation Details:

    • Base Records: Most base records (like Movies) already include the most popular artwork (e.g., the best poster), so you may not need to call the full artwork set.
    • Entity Differences: series, movies, and seasons may have multiple artworks of a type. episodes, companies, and people typically have only one.
    • People: If a person has a role-specific image, the system falls back to the default headshot. Using the default headshot is recommended for most use cases.
    • Episode Aspect Ratios: Episode images may be in 4:3 or 16:9 formats. UI designs should account for both to match the original broadcast format.

  2. Understand Scores and Popularity

    main

    Most entities include a score field. This is an arbitrary number representing the relative popularity of a record.

    Usage Notes:

    • Use scores for sorting or biasing search results within a specific entity type.
    • Warning: Do not compare scores across different entity types (e.g., comparing a Person score to a Movie score); the results are meaningless.

  3. Understand Season Types and Ordering

    main

    Series can have multiple season types (e.g., 'Aired Order' vs. 'Netflix Order').

    Key Concepts:

    • Default Order: The series base record includes the ID of the default season order (usually 'Aired Order').
    • Episode Context: The episode base record contains the season and episode number relative to the default season order.
    • Custom Names: Season types can have custom names (e.g., a season type named 'Netflix' instead of 'Alternate Order'). This information is available when retrieving seasons for a series.

  4. Obtain a TVDB API Key

    main

    To access the TVDB V4 API, you must create an account and generate an API key. There are two primary access models:

    1. Negotiated License Model: For commercial companies to negotiate specific access terms.
    2. User-Subscription Model: For end users who have a TVDB subscription.

    You can manage and create your keys via the API keys page on your dashboard.

  5. Implement Data Retrieval Best Practices

    main

    To ensure reliability and performance, TheTVDB recommends one of the following data retrieval strategies:

    1. Maintaining a Full Database Copy

    Iterate all records in each endpoint and ingest them into your own database.

    • Syncing: Monitor the /updates endpoint to keep your database current.
    • Handling Deletions: Some deletion updates include mergeToType and mergeToId. If a record was deleted due to a duplicate, use these fields to migrate data (like ratings or follower counts) to the surviving record.

    2. Providing a Caching Proxy

    Use an intermediary like squid to sit between your users and TheTVDB.

    • Benefits: Protects against TVDB outages, reduces bandwidth, and allows you to use your own authentication model for users while using your API key for TVDB requests.
    • TTL: Set Time To Live (TTL) based on data volatility (e.g., series records may need low TTL, while person records can be cached for a week).
    • Cache Warmer: Consider a background process to iterate popular records and pre-populate your proxy cache.

    3. Direct API Access

    Users can access the API directly, but you must either negotiate a contract (often requiring attribution) or ensure each user has a $12/year TVDB subscription.

  6. Identify Endpoints to Cache Heavily

    main

    Certain metadata endpoints change infrequently and are safe to cache for a week or longer. It is recommended not to hard-code these values, but to fetch them and cache them instead:

    • artwork/types
    • award/categories
    • content/ratings
    • entity/types
    • genders
    • genres
    • inspiration/types
    • languages
    • movie/statuses
    • people/types
    • series/statuses
    • source/types