Television

Interfaces to all of the TV objects offered by the Trakt.tv API

trakt.tv.dismiss_recommendation(*args, **kwargs)

Dismiss the show matching the specified criteria from showing up in recommendations.

Get a list of TVShow’s recommended based on your watching history and your friends. Results are returned with the top recommendation first.

trakt.tv.genres(*args, **kwargs)

A list of all possible TVShow Genres

trakt.tv.popular_shows(*args, **kwargs)
trakt.tv.trending_shows(*args, **kwargs)

All TVShow’s being watched right now

trakt.tv.updated_shows(*args, **kwargs)

All TVShow’s updated since timestamp (PST). To establish a baseline timestamp, you can use the server/time method. It’s recommended to store the timestamp so you can be efficient in using this method.

class trakt.tv.TVShow(title='', slug=None, **kwargs)

A Class representing a TV Show object

add_to_collection()

Add this TVShow to your library.

add_to_library()

Add this TVShow to your library.

add_to_watchlist()

Add this TVShow to your watchlist

aliases

A list of Alias objects representing all of the other titles that this TVShow is known by, and the countries where they go by their alternate titles

cast

All of the cast members that worked on this TVShow

comment(comment_body, spoiler=False, review=False)

Add a comment (shout or review) to this Move on trakt.

comments

All comments (shouts and reviews) for this TVShow. Most recent comments returned first.

crew

All of the crew members that worked on this TVShow

dismiss()

Dismiss this movie from showing up in Movie Recommendations

ext
ext_full
get_translations(**kwargs)

Returns all Translation’s for a movie, including language and translated values for title, tagline and overview.

Parameters:country_code – The 2 character country code to search from
Returns:a list of Translation objects
ids

Accessor to the trakt, imdb, and tmdb ids, as well as the trakt.tv slug

images

All of the artwork associated with this TVShow

images_ext

Uri to retrieve additional image information

mark_as_seen(watched_at=None)

Add this TVShow, watched outside of trakt, to your library.

mark_as_unseen()

Remove this TVShow, watched outside of trakt, from your library.

people

A list of all of the People involved in this TVShow, including both cast and crew

rate(rating)

Rate this TVShow on trakt. Depending on the current users settings, this may also send out social updates to facebook, twitter, tumblr, and path.

ratings

Ratings (between 0 and 10) and distribution for a movie.

related

The top 10 TVShow’s related to this TVShow

remove_from_collection()

Remove this TVShow from your library.

remove_from_library()

Remove this TVShow from your library.

remove_from_watchlist()
classmethod search(title, year=None)

Perform a search for the specified title

Parameters:title – The title to search for
seasons

A list of TVSeason objects representing all of this show’s seasons

to_json()
watching_now

A list of all User’s watching a movie.

class trakt.tv.TVEpisode(show, season, number=-1, **kwargs)

Container for TV Episodes

add_to_collection()

Add this TVEpisode to your Trakt.tv library

add_to_library()

Add this TVEpisode to your Trakt.tv library

add_to_watchlist()

Add this TVEpisode to your watchlist

comment(comment_body, spoiler=False, review=False)

Add a comment (shout or review) to this TVEpisode on trakt.

comments

All comments (shouts and reviews) for this TVEpisode. Most recent comments returned first.

ext
ext_full
first_aired_date

Python datetime object representation of the first_aired date of this TVEpisode

get_description()

backwards compatible function that returns this TVEpisode’s overview ‘

ids

Accessor to the trakt, imdb, and tmdb ids, as well as the trakt.tv slug

images

All of the artwork associated with this TVEpisode

images_ext

Uri to retrieve additional image information

mark_as_seen(watched_at=None)

Mark this episode as seen

mark_as_unseen()

Remove this TVEpisode from your list of watched episodes

rate(rating)

Rate this TVEpisode on trakt. Depending on the current users settings, this may also send out social updates to facebook, twitter, tumblr, and path.

ratings

Ratings (between 0 and 10) and distribution for a movie.

remove_from_collection()

Remove this TVEpisode from your library

remove_from_library()

Remove this TVEpisode from your library

remove_from_watchlist()

Remove this TVEpisode from your watchlist

scrobble(progress, app_version, app_date)

Scrobble this TVEpisode via the TraktTV Api

Parameters:
  • progress – % progress, integer 0-100. It is recommended to call the watching API every 15 minutes, then call the scrobble API near the end of the movie to lock it in.
  • app_version – Version number of the media center, be as specific as you can including nightly build number, etc. Used to help debug your plugin.
  • app_date – Build date of the media center. Used to help debug your plugin.
classmethod search(title, year=None)

Perform a search for an episode with a title matching title

Parameters:
  • title – The title to search for
  • year – Optional year to limit results to
to_json()

Return this TVEpisode as a trakt recognizable JSON object

watching_now

A list of all User’s watching a movie.

class trakt.tv.TVSeason(show, season=1, slug=None, **kwargs)

Container for TV Seasons

add_to_collection()

Add this TVSeason to your library.

add_to_library()

Add this TVSeason to your library.

comments

All comments (shouts and reviews) for this TVSeason. Most recent comments returned first.

episodes

A list of TVEpisode objects representing all of the Episodes in this TVSeason. Because there is no “Get all episodes for a season” endpoint on the trakt api

ratings

Ratings (between 0 and 10) and distribution for a movie.

remove_from_collection()

Remove this TVSeason from your library.

remove_from_library()

Remove this TVSeason from your library.

to_json()

Return this TVSeason as a Trakt consumable API blob

watching_now

A list of all User’s watching a movie.

class trakt.tv.Translation(title, overview, language)
language

Alias for field number 2

overview

Alias for field number 1

title

Alias for field number 0

Example Usage

The trakt.tv module has interfaces to all of the TV resources mentioned above and is almost a direct port of the trakt.movies module. It has the same interfaces to dismiss shows from recommendations, getting recommendations, rating a list of shows, rating a list of episodes, getting a list of valid show genres, a list of trending shows, and getting a list of recently updated shows and dealing with specific shows, seasons, and episodes.

For our first example let’s start by grabbing a specific show

>>> from trakt.tv import TVShow
>>> it_crowd = TVShow('The IT Crowd')

Well that was pretty painless. Ok, now let’s pull some data out of our it_crowd object

>>> it_crowd.people
[<Person>: Chris O'Dowd, <Person>: Katherine Parkinson, <Person>: None,
<Person>: Richard Ayoade, <Person>: Chris Morris, <Person>: Matt Berry, <Person>: Noel Fielding]
>>> it_crowd.top_episodes
[<TVEpisode>: The IT Crowd S1E1 Yesterday's Jam, <TVEpisode>: The IT Crowd S1E2 Calamity Jen,
 <TVEpisode>: The IT Crowd S2E1 The Work Outing, <TVEpisode>: The IT Crowd S1E4 The Red Door,...
>>> it_crowd.top_watchers
[<User>: b'Vaelek', <User>: b'Governa', <User>: b'shanos404', <User>: b'b_jammin666',
<User>: b'pavvoc', <User>: b'heartbraden', <User>: b'tressal', <User>: b'hherrera',...
>>> it_crowd.genres
[Genre(name='Comedy', slug='comedy')]

Now that we’ve gotten some information on the show, let’s start doing something interesting and interacting with the API via the TVShow’s methods

>>> it_crowd.add_to_library()
>>> it_crowd.comment('Wow, I REALLY love this show')
>>> it_crowd.comment('They should never have given Jen the internet.',
                     spoiler=True, review=True)

Now that we’ve gotten some information on the show, let’s dive down and get some information on the show’s seasons and episodes

>>> s1 = it_crowd.seasons[1]
>>> s1.episodes
[<TVEpisode>: The IT Crowd S1E-1 Yesterday's Jam, <TVEpisode>: The IT Crowd S1E-1 Calamity Jen,
<TVEpisode>: The IT Crowd S1E-1 Fifty-Fifty, <TVEpisode>: The IT Crowd S1E-1 The Red Door,
<TVEpisode>: The IT Crowd S1E-1 The Haunting of Bill Crouse, <TVEpisode>: The IT Crowd S1E-1 Aunt Irma Visits]
>>> pilot = s1.episodes[0]
>>> pilot.title
'Yesterday's Jam'
>>> pilot.overview
'Jen is hired as the manager Reynholm Industries although she doesn't know the first thing about computers.'