That’s all you need to to for basic things. If you’re planning a larger project with lots and lots of data retrieval, you might want to create your own API app on trakt.tv.
1. Find things
Using a text query:
search_query("Utopia", type = "show")
#> # A tibble: 1 × 9
#> type score title year trakt slug tvdb imdb tmdb
#> <chr> <dbl> <chr> <int> <chr> <chr> <chr> <chr> <chr>
#> 1 show 98.6 Utopia 2013 46241 utopia 264991 tt2384811 46511Search using an ID:
search_id("tt2384811", id_type = "imdb", type = "show")
#> # A tibble: 1 × 9
#> type score title year trakt slug tvdb imdb tmdb
#> <chr> <dbl> <chr> <int> <chr> <chr> <chr> <chr> <chr>
#> 1 show 1000 Utopia 2013 46241 utopia 264991 tt2384811 46511Or via whatever’s popular(ish):
Another scenario would be that you’re not necessarily interested in
some specific media item, but rather a collection of items that fulfill
certain criteria, like being popular on trakt.tv and maybe being from a
specific period or genre and whatnot. While you can also filter
search_query by other criteria, it’s maybe more useful to
filter, let’s say, the most watched movies of the past week by the
release year of the movie.
The 5 most popular shows:
shows_popular(limit = 5)
#> # A tibble: 5 × 7
#> title year trakt slug tvdb imdb tmdb
#> <chr> <int> <chr> <chr> <chr> <chr> <chr>
#> 1 Game of Thrones 2011 1390 game-of-thrones 121361 tt0944947 1399
#> 2 Breaking Bad 2008 1388 breaking-bad 81189 tt0903747 1396
#> 3 The Walking Dead 2010 1393 the-walking-dead 153021 tt1520211 1402
#> 4 The Big Bang Theory 2007 1409 the-big-bang-theory 80379 tt0898266 1418
#> 5 Stranger Things 2016 104439 stranger-things 305288 tt4574334 66732The 10 most watched (during the past year) movies from 1990-2000:
library(dplyr)
movies_watched(period = "yearly", years = c(1990, 2000)) |>
select(watcher_count, title, year)
#> # A tibble: 10 × 3
#> watcher_count title year
#> <int> <chr> <int>
#> 1 1012 The Matrix 1999
#> 2 681 Fight Club 1999
#> 3 601 Toy Story 1995
#> 4 590 Forrest Gump 1994
#> 5 573 The Lion King 1994
#> 6 568 Jurassic Park 1993
#> 7 564 The Shawshank Redemption 1994
#> 8 512 Star Wars: Episode I - The Phantom Menace 1999
#> 9 494 The Truman Show 1998
#> 10 478 Gladiator 2000Finding Things (and the right amount)
Item identifiers
The id parameter is used to identify shows, movies or
people. In each of these cases, the value of the parameter must be a
valid ID of one of the following kinds:
-
Trakt ID (
trakt): A numeric ID used by trakt.tv, which is included as a variable namedtraktby every function for an output item. These IDs are unique for their respective category (ortype, e.g. shows, movies, people, …) and can be expected to have full coverage, meaning that every item will have a category-specific Trakt ID. -
Slug (
slug): A human-readable identifier used on the trakt.tv site, e.g.the-wire. While these are easy to remember, they have the risk of clashing with numeric IDs. One example is the show “24”, which has the slug24. However, the show “Presidio Med” has the Trakt ID24, so if you supplyid = 24the API assumes you meant the Trakt ID instead of the slug. This is… suboptimal. UsetraktID’s whenever possible in any sort of user-facing application or batch-processing. -
IMDb ID (
imdb): Relatively self-explanatory. You can retrieve them easily via most functions or by searching on IMDb.com. Since IMDb is an external service, these IDs should be used for linking with other data sources rather than as search parameters for the trakt API, as it can not be guaranteed that every item on trakt.tv does have an IMDb ID.
The API also returns additional IDs for TMDB and TheTVDB. These are useful for linking with other data sources like fanart.tv, but can’t be used for search with the trakt API as they are not guaranteed full coverage. The API also includes a TVRage ID, but since this site seems to not exist anymore (and therefore newer items don’t have this ID) this ID is removed from all output whether it is missing or not.
Extended Information:
The extended parameter controls the amount of
information (i.e. the number of variables) included in the output.
"min": The default option returns minimal information. For shows, movies, episodes and people, the result will only include a title or name, possibly a year, and the standard set of IDs (trakt,imdb, …). This is the fastest option as it requires less data to be sent from the API and less post-processing work to produce tabular output."full": The maximum amount of information. This option is required if you are interested in thevotesandratingvariables, as well as additional metadata like air dates, plot summaries, and a plethora of other variables depending on thetype. If you intend on retrieving data for a large number of items, e.g. viashows_popular()and other list functions, it is highly recommend to cache the output locally when usingextended = "full"and subsequently only useextended = "min", so you can merge/join the minimal data with your cached data. httr2 automatically caches requests under the hood, so you don’t need to do anything special there for regular usage.images: Images such as posters used to be available via the trakt API some years ago but where discontinued due to the associated bandwidth and storage costs. As of early 2025, images are once again available with the API but requesting them is not implemented here (yet?). If you need posters, I recommend taking a detour over to fanart.tv