---
title: "Finding things (and the right amount)"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Finding things (and the right amount)}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
```

# 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 named `trakt` by every function for an output item. These
IDs are unique for their respective category (or `type`, 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 slug `24`.
However, the show "Presidio Med" has the **Trakt ID** `24`, so if you supply
`id = 24` the API assumes you meant the Trakt ID instead of the slug.
This is... suboptimal. Use `trakt` ID'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](https://www.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 does return some additional IDs, notably for [the tvdb](https://www.thetvdb.com).
These are useful for linking with other data sources like
[fanart.tv](https://fanart.tv/).
They are not used as search parameters for the trakt API. 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.

# 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 (see section above). This is the fastest option as it requires
less content 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 the `votes` and `rating` variables, as well as additional metadata like air dates, plot summaries, and a plethora of other variables depending on the `type`. 
If you intend on retrieving data for a large number of items, e.g. via [popular_media], it is highly recommend to cache the output locally when using `extended = "full"` and subsequently only use `extended = "min"`. 
Then you can merge or [`dplyr::left_join()`] the minimal data with your
cached data.