DOCSEARCHbyAlgolia
Submit Docs

Trakt API

repository·master·Indexed 43 days ago

https://github.com/trakt/trakt-api

A type-safe, Deno-based implementation for interacting with Trakt's media data services. The workspace includes the @trakt/api core library featuring Zod schemas and ts-rest contracts, a CLI playground for testing, an OpenAPI specification server, and the source for the Trakt Developer Portal.

Tokens
43.2K
Snippets
126
Records
208
Agent score
56%

What's inside Trakt

  1. Overview of the Trakt API Workspace

    master

    The Trakt API repository is a Deno-based workspace containing several interconnected projects:

    • api: The core library for interacting with the Trakt API. It uses ts-rest and zod to provide type-safe communication and data validation.
    • playground: A CLI tool designed for testing and exploring Trakt API functionality.
    • developer: The source for the Trakt Developer Portal (developer.trakt.tv), located in projects/developer. It includes Markdown guides and an interactive API Reference playground.
    • openapi: A hono server that serves the API contract as an OpenAPI specification.

  2. Introduction to the Trakt API

    master

    The Trakt API allows developers to access data about TV shows and movies. It is a RESTful API where most interactions involve making HTTP requests to specific URLs and receiving JSON responses.

    • GET requests: Used to retrieve data.
    • POST requests: Used for more complex operations, such as adding movies or episodes to a user's history, by sending JSON data to a specific endpoint.

    Important: Before making calls, you must consult the documentation for Required Headers and Authentication to ensure your requests are properly formed and authorized.

  5. Understand the Checkin feature

    master

    Checkin is a manual action designed for mobile applications to allow users to indicate what they are currently watching. It is intended for scenarios where automatic scrobbling is not possible, such as watching live TV, watching at a friend's house, or watching a movie in a theater.

    Behavioral Lifecycle:

    1. Active State: Once a user performs a checkin, the item is displayed as watching on the Trakt website.
    2. Completion State: After the duration of the content has elapsed, the status automatically switches from watching to watched.

  6. Understand Trakt Calendar behavior and parameters

    master

    The Trakt Calendar API returns shows or movies for a specified time period. Calendars can be either global (all) or user-specific (my).

    Key Parameters

    • start_date: The beginning of the calendar period. Defaults to today.
    • days: The number of days to retrieve. Defaults to 7. The maximum allowed value is 33.

    Calendar Types

    • my calendar: Displays episodes for shows that have been watched or are on the user's watchlist. It also includes individual episodes on the watchlist. Shows hidden by the user are automatically removed from this view.
    • all calendar: Displays information for all shows airing during the specified period, regardless of user history.

    Important Note on Timezones

    All dates returned by the API (including start_date and first_aired) are in UTC. Your application is responsible for applying offsets to match the user's local time zone.

  7. Important requirements for using Trakt images

    master

    When using images provided by Trakt, you must adhere to the following rules:

    1. Mandatory Caching: You are required to cache all images in your own application or server. Hotlinking directly from the Trakt CDN is not allowed and will be blocked.
    2. URL Formatting: Trakt returns image URLs without a protocol. You must prepend https:// to all image URLs to make them valid.
    3. Image Format: All images are returned in WebP format to optimize file size while maintaining quality.

  8. Understand the difference between Metadata and Activity data

    master

    Trakt API responses distinguish between two types of data which are cached and updated using different strategies:

    1. Metadata: Static or slow-changing information such as titles, overviews, taglines, images, translations, ratings, IDs, genres, and updated_at.
    2. Activity or user-specific data: Dynamic information such as watched state, favorites, plays, list counts, progress, and other counts.

    When building a client, you must account for the fact that these two data types may not be synchronized in a single response.

  9. Trakt API usage terms and best practices

    master

    When using the Trakt API, developers must adhere to several usage requirements and community standards:

    Compliance & Legal

    • Branding: All branding requirements must be followed.
    • Content Policy: Trakt data cannot be used in applications or websites that promote piracy or copyright infringement.
    • Liability: Data is provided "as is" without warranty or legal protection.
    • Account Maintenance: Keep your account email and app information up to date for communication purposes.

    Technical Best Practices

    • API Usage: Use only documented API methods. Do not scrape the Trakt website for data.
    • Rate Limiting: Do not create multiple API apps to bypass rate limits or restrictions.
    • Optimization: Effectively cache data and minimize API hits to ensure the shared API remains performant for all users.

    Community Engagement

    • Announcements: All API announcements and discussions occur in the GitHub developer community.
    • Notifications: Developers are required to watch and subscribe to notifications in the GitHub repository to stay informed of updates.

  10. Authenticate with the Trakt API using OAuth 2.0

    master

    The Trakt API uses OAuth 2.0 for user authentication. Endpoints are categorized as:

    • Public: Require only your trakt-api-key.
    • Authenticated: Require a user access token.
    • Personalized: Some public endpoints return more personalized results if an OAuth token is provided.

    Required Headers

    Every request must include your API key. For endpoints requiring OAuth, include the access token as a Bearer token.

    trakt-api-key: YOUR_API_KEY
Authorization: Bearer <access_token>

  11. Trakt API terminology and concepts

    master

    The Trakt API uses specific terms to describe user activity and organization. Understanding these terms is essential for interacting with the API correctly:

    TermDescription
    ScrobbleAutomatically track what a user is watching by sending playback events when a movie or episode starts, pauses, or stops.
    CheckinManually indicate that a user is watching a movie or episode right now. The item is marked as watched once its runtime has elapsed.
    HistoryA record of the movies and episodes a user has watched, including when they watched them and repeat viewings.
    WatchlistMovies, shows, seasons, or episodes a user wants to watch.
    ListA custom group of items organized by a user around a theme or purpose, with its own name, ordering, and privacy settings.
    FavoritesA user's most-loved movies and shows. Favorites also help improve recommendations.

  12. How authentication works in the Developer Portal

    master

    The portal is a serverless SvelteKit application that uses the OpenID Connect (OIDC) authorization code flow with PKCE for authentication.

    Key Characteristics:

    • Client Type: It acts as a public OAuth client. There is no client secret used anywhere.
    • Flow: Authentication is handled entirely in the browser by oidc-client-ts against auth.trakt.tv.
    • Token Storage: Tokens are stored in localStorage. Security is maintained via a strict Content Security Policy (CSP) defined in svelte.config.js.
    • API Requests: Requests are made directly from the browser to the Trakt API. The executeApiRequest utility ensures that requests are sent to approved HTTPS Trakt hosts and automatically attaches necessary headers (trakt-api-key, trakt-api-version, and authorization) while preventing the attachment of account tokens to OAuth endpoints.