Overview of the trakt.tv API Concepts and Endpoints

Published 2017-07-03, 17:24

trakt.tv offers a very comprehensive API with an amazing documentation. But thorough as it is – and the technical details like authentication, data formats, parameters etc. are really, really well covered – it can also feel a bit overwhelming when you jump in and want to get a first overview, or are only looking for some specific data or type of data.

As I just did exactly that, I went through the whole documentation and extracted the most relevant information. The order of this article, especially the API endpoints, follows the official API documentation. I only added some more headlines to group the endpoints in a better way:

Concepts
Emojis Legend
Endpoints

Concepts

The API only defines some terms in „Terminology“, but there is a lot more to understand what there is and how it is all connected:

There are Users and objects: Movies, Shows with Seasons and Episodes.
Users
- Users can watch things:
  - Users can checkin to or scrobble movies and episodes. These are then first marked as watching, later as watched after the runtime (complicated, read details in docs).
  - Users can additionally add to history for movies, shows, seasons and episodes to mark them as watched instantly.
- Users can create multiple Lists and have one Collection and one Watchlist (of movies, shows, seasons, and episodes).
- Users can write Comments on movies, shows, seasons, episodes, or lists.
  - Users can create Replies and Likes on comments and lists.
- Users can create Ratings on movies, shows, seasons and episode.
- Users have Settings and a Profile
- Users can follow other users to create Follower Requests and eventually become Followers, Following and Friends
Objects
- There is additional information for some objects:
  - Summary for movies, people, shows, seasons and episodes collect all known information about them
  - Aliases of movies and shows
  - Releases of movies
  - Translations of movies, shows and episodes
  - People are cast and crew of shows and movies
- Search can look for movies, shows, episodes, people, and lists by text or ID.
- Related objects are calculated for movies and shows.
- Stats are calculated for movies, shows, seasons, episodes and users.
Users and Objects
- History and Playback are calculated based on checkins and scrobbles (= movies and episodes watched) and manual „add to history“.
- Last Activities are collected from history and all other user activities (comments, replies, likes, ratings).
- Based on the releases of objects and the history of the user there are Calendars for shows and episodes.
- Recommendations are given to users for movies and shows.
- Collection Progress and Watch Progress is calculated for users for shows and their episodes.
- Users can create Hidden Items to hide things (movies, shows or episodes) in calendars, collection progress, watch progress and recommendations.

Use the checkboxes next to the terms to deactivate them in the list below. You can also set if they only should be deactivated or completely hidden. Hide deactivated items:

Emojis Legend

These Emojis are used in the official documentation to indicate what functionality is offered by or needed for an endpoint.

📄 = Pagination
- 📄? = optional
✨ = Extended Info
🎚 = Filters
🔒 = OAuth
- 🔒? = optional
- 🔒! = required

Data Endpoints

These return the nitty-gritty of Trakt: Lots of data about shows and movies and all the things related to them:

Calendars
- All Shows ✨ 🎚 – Returns all shows airing during the time period specified.
- All New Shows ✨ 🎚 – Returns all new show premieres (season 1, episode 1) airing during the time period specified.
- All Season Premieres ✨ 🎚 – Returns all show premieres (any season, episode 1) airing during the time period specified.
- All Movies ✨ 🎚 – Returns all movies with a release date during the time period specified.
- All DVD ✨ 🎚 – Returns all movies with a DVD release date during the time period specified.
Checkin
- n/a
Comments
- Comment
  - Get – Returns a single comment and indicates how many replies it has.
- Replies
  - Get 📄 – Returns all replies for a comment.
Movies
- Movies
  - Trending 📄 ✨ 🎚 – Returns all movies being watched right now.
  - Popular 📄 ✨ 🎚 – Returns the most popular movies.
  - Played 📄 ✨ 🎚 – Returns the most played (a single user can watch multiple times) movie.
  - Watched 📄 ✨ 🎚 – Returns the most watched (unique users) movies.
  - Collected 📄 ✨ 🎚 – Returns the most collected (unique users) movies.
  - Anticipated 📄 ✨ 🎚 – Returns the most anticipated movies based on the number of lists a movie appears on.
  - Box Office ✨ – Returns the top 10 grossing movies in the U.S. box office last weekend.
  - Updates 📄 ✨ – Returns all movies updated since the specified UTC date.
- Movie
  - Summary ✨ – Returns a single movie’s details.
  - Aliases – Returns all title aliases for a movie.
  - Releases – Returns all releases for a movie including country, certification, release date, release type, and note.
  - Translations – Returns all translations for a movie, including language and translated values for title, tagline and overview.
  - Comments 📄 – Returns all top level comments for a movie.
  - Lists 📄 – Returns all lists that contain this movie.
  - People ✨ – Returns all cast and crew for a movie.
  - Ratings – Returns rating (between 0 and 10) and distribution for a movie.
  - Related 📄 ✨ – Returns related and similar movies.
  - Stats – Returns lots of movie stats.
  - Watching ✨ – Returns all users watching this movie right now.
People
- Summary ✨ – Returns a single person’s details.
- Movies ✨ – Returns all movies where this person is in the cast or crew.
- Shows ✨ – Returns all movies where this person is in the cast or crew.
Recommendations
- n/a
Scrobble
- n/a
Search
- Text Query 📄 ✨ 🎚 – Search all text fields that a media object contains (i.e. title, overview, etc).
- ID Lookup 📄 ✨ – Lookup items by their Trakt, IMDB, TMDB, TVDB, or TVRage ID.
Shows
- Shows
  - Trending 📄 ✨ 🎚 – Returns all shows being watched right now.
  - Popular 📄 ✨ 🎚 – Returns the most popular shows.
  - Played 📄 ✨ 🎚 – Returns the most played (a single user can watch multiple episodes multiple times) shows.
  - Watched 📄 ✨ 🎚 – Returns the most watched (unique users) shows.
  - Collected 📄 ✨ 🎚 – Returns the most collected (unique users) shows.
  - Anticipated 📄 ✨ 🎚 – Returns the most anticipated shows based on the number of lists a show appears on.
  - Updates 📄 ✨ – Returns all shows updated since the specified UTC date.
- Show
  - Summary ✨ – Returns a single show’s details.
  - Aliases – Returns all title aliases for a show.
  - Translations – Returns all translations for a show, including language and translated values for title and overview.
  - Comments 📄 – Returns all top level comments for a show.
  - Lists 📄 – Returns all lists that contain this show.
  - People ✨ – Returns all cast and crew for a show.
  - Ratings – Returns rating (between 0 and 10) and distribution for a show.
  - Related 📄 ✨ – Returns related and similar shows.
  - Stats – Returns lots of show stats.
  - Watching ✨ – Returns all users watching this show right now.
  - Next Episode ✨ – Returns the next scheduled to air episode.
  - Last Episode ✨ – Returns the most recently aired episode.
Seasons
- Seasons
  - Summary ✨ – Returns all seasons for a show including the number of episodes in each season.
- Season
  - Season ✨ – Returns all episodes for a specific season of a show.
  - Comments 📄 – Returns all top level comments for a season.
  - Lists 📄 – Returns all lists that contain this season.
  - Ratings – Returns rating (between 0 and 10) and distribution for a season.
  - Stats – Returns lots of season stats.
  - Watching ✨ – Returns all users watching this season right now.
Episodes
- Episode
  - Summary ✨ – Returns a single episode’s details.
  - Translations – Returns all translations for an episode, including language and translated values for title and overview.
  - Comments 📄 – Returns all top level comments for an episode.
  - Lists 📄 – Returns all lists that contain this episode.
  - Ratings – Returns rating (between 0 and 10) and distribution for an episode.
  - Stats – Returns lots of episode stats.
  - Watching ✨ – Returns all users watching this episode right now.
Sync
- n/a
Users
- Profile 🔒? ✨ – Get a user’s profile information.
- Collection 🔒? ✨ – Get all collected items in a user’s collection.
- Comments 🔒? 📄 ✨ – Returns comments a user has posted sorted by most recent.
- Lists
  - Lists
    - Get 🔒? – Returns all custom lists for a user.
  - List
    - Get 🔒? – Returns a single custom list.
  - List Item
    - List Items 🔒? 📄? ✨ – Get all items on a custom list.
  - List comment 📄 – Returns all top level comments for a list.
- Follow
  - Followers 🔒? ✨ – Returns all followers including when the relationship began.
  - Following 🔒? ✨ – Returns all user’s they follow including when the relationship began.
  - Friends 🔒? ✨ – Returns all friends for a user including when the relationship began.
- History 🔒? 📄 ✨ – Returns movies and episodes that a user has watched, sorted by most recent.
- Ratings 🔒? 📄 – Get a user’s ratings.
- Watchlist 🔒? 📄? ✨ – Returns all items in a user’s watchlist filtered by type.
- Watching 🔒? ✨ – Returns a movie or episode if the user is currently watching something.
- Watched 🔒? ✨ – Returns all movies or shows a user has watched sorted by most plays.
- Stats 🔒? – Returns stats about the movies, shows, and episodes a user has watched, collected, and rated.

User Endoints

If it matters which user is logged in via OAuth, these endpoints are collected here:

Calendars
- My Shows 🔒! ✨ 🎚 – Returns all shows airing during the time period specified.
- My New Shows 🔒! ✨ 🎚 – Returns all new show premieres (season 1, episode 1) airing during the time period specified.
- My Season Premieres 🔒! ✨ 🎚 – Returns all show premieres (any season, episode 1) airing during the time period specified.
- My Movies 🔒! ✨ 🎚 – Returns all movies with a release date during the time period specified.
- My DVD 🔒! ✨ 🎚 – Returns all movies with a DVD release date during the time period specified.
Checkin
- Checkin 🔒! – Check into a movie or episode.
- Delete 🔒! – Removes any active checkins, no need to provide a specific item.
Comments
- Comments
  - Post a comment 🔒! – Add a new comment to a movie, show, season, episode, or list.
- Comment
  - Update 🔒! – Update a single comment created within the last hour
  - Delete 🔒! – Delete a single comment created within the last hour.
- Replies
  - Post 🔒! – Add a new reply to an existing comment.
- Like
  - Like 🔒! – Votes help determine popular comments.
  - Remove 🔒! – Remove a like on a comment.
Movies
- n/a
People
- n/a
Recommendations
- Movies 🔒! ✨ – Personalized movie recommendations for a user.
- Hide Movie 🔒! – Hide a movie from getting recommended anymore.
- Shows 🔒! ✨ – Personalized show recommendations for a user.
- Hide Show 🔒! – Hide a show from getting recommended anymore.
Scrobble
- Start 🔒! – Use this method when the video initially starts playing or is unpaused.
- Pause 🔒! – Use this method when the video is paused.
- Stop 🔒! – Use this method when the video is stopped or finishes playing on its own.
Search
- n/a
Shows
- Show
  - Collection Progress 🔒! – Returns collection progress for a show including details on all aired seasons and episodes.
  - Watched Progress 🔒! – Returns watched progress for a show including details on all aired seasons and episodes.
Seasons
- n/a
Episodes
- n/a
Sync
- Last Activities 🔒! – Returns a list of dates when the user last interacted with trakt.tv for different object types.
- Get Watched 🔒! ✨ – Returns all movies or shows a user has watched sorted by most plays.
- Playback
  - Playback 🔒! – Whenever a scrobble is paused, the playback progress is saved.
  - Remove Playback 🔒! – Remove a playback item from a user’s playback progress list.
- Collection
  - Get Collection 🔒! ✨ – Get all collected items in a user’s collection.
  - Add to Collection 🔒! – Add items to a user’s collection.
  - Remove from Collection 🔒! – Remove one or more items from a user’s collection.
- History
  - Get History 🔒! 📄 ✨ – Returns movies and episodes that a user has watched, sorted by most recent.
  - Add to History 🔒! – Add items to a user’s watch history.
  - Remove from History 🔒! – Remove items from a user’s watch history including all watches, scrobbles, and checkins.
- Ratings
  - Get Ratings 🔒! ✨ – Get a user’s ratings.
  - Add Rating 🔒! – Rate one or more items.
  - Remove Rating 🔒! – Remove ratings for one or more items.
- Watchlist
  - Get Watchlist 🔒! 📄? ✨ – Returns all items in a user’s watchlist filtered by type.
  - Add to Watchlist 🔒! – Add one of more items to a user’s watchlist.
  - Remove from Watchlist 🔒! – Remove one or more items from a user’s watchlist.
Users
- Settings 🔒! – Get the user’s settings so you can align your app’s experience with what they’re used to on the trakt website.
- Follower Requests
  - Follower Requests 🔒! ✨ – List a user’s pending follow requests so they can either approve or deny them.
  - Approve or Deny Follower Requests
    - Approve 🔒! – Approve a follower.
    - Deny 🔒! – Deny a follower.
- Hidden Items
  - Hidden Items 🔒! 📄 ✨ – Get hidden items for a section.
  - Add Hidden Items 🔒! – Hide items for a specific section.
  - Remove Hidden Items 🔒! – Unhide items for a specific section.
- Likes 🔒! 📄 – Get items a user likes.
- Profile 🔒? ✨ – Get a user’s profile information.
- Collection 🔒? ✨ – Get all collected items in a user’s collection.
- Comments 🔒? 📄 ✨ – Returns comments a user has posted sorted by most recent.
- Lists
  - Lists
    - Get 🔒? – Returns all custom lists for a user.
    - Create 🔒! – Create a new custom list.
  - List
    - Get 🔒? – Returns a single custom list.
    - Update 🔒! – Update a custom list by sending 1 or more parameters.
    - Delete 🔒! – Remove a custom list and all items it contains.
  - List Like
    - Like 🔒! – Votes help determine popular lists.
    - Remove 🔒! – Remove a like on a list.
  - List Item
    - List Items 🔒? 📄? ✨ – Get all items on a custom list.
    - Add List Item 🔒! – Add one or more items to a custom list.
    - Remove List Item 🔒! – Remove one or more items from a custom list.
- Follow
  - Follow
    - Follow 🔒! – Follow a user.
    - Unfollow 🔒! – Unfollow someone you already follow.
  - Followers 🔒? ✨ – Returns all followers including when the relationship began.
  - Following 🔒? ✨ – Returns all user’s they follow including when the relationship began.
  - Friends 🔒? ✨ – Returns all friends for a user including when the relationship began.
- History 🔒? 📄 ✨ – Returns movies and episodes that a user has watched, sorted by most recent.
- Ratings 🔒? 📄 – Get a user’s ratings.
- Watchlist 🔒? 📄? ✨ – Returns all items in a user’s watchlist filtered by type.
- Watching 🔒? ✨ – Returns a movie or episode if the user is currently watching something.
- Watched 🔒? ✨ – Returns all movies or shows a user has watched sorted by most plays.
- Stats 🔒? – Returns stats about the movies, shows, and episodes a user has watched, collected, and rated.

Master Data Endpoints

These endpoints offer mostly static data that should be retrieved once and then be cached for further use:

Certifications
- List – Get a list of all certifications, including names, slugs, and descriptions.
Genres
- List – Get a list of all genres, including names and slugs.
Networks
- List – Get a list of all TV networks, including the name.

And that’s it! All essential API endpoints of the trakt.tv API, groupd by type and explained a bit more.

Topic(s): Kram, Link, Research No comments - :(

Diskussion zum Artikel

» Selbst kommentieren

Zum Artikel Overview of the trakt.tv API Concepts and Endpoints sind noch keine Kommentare vorhanden. Deine Meinung wäre jedoch willkommen!

Selbst kommentieren

Trackback-URI, Kommentarfeed. XML-Feed

betamode