@datafire/thetvdb

Client library for TheTVDB API v3

Installation and Usage

npm install --save @datafire/thetvdb

let thetvdb = require('@datafire/thetvdb').create({
  jwtToken: ""
});

.then(data => {
  console.log(data);
});

Description

API v3 targets v2 functionality with a few minor additions. The API is accessible via https://api.thetvdb.com and provides the following REST endpoints in JSON format.

How to use this API documentation

You may browse the API routes without authentication, but if you wish to send requests to the API and see response data, then you must authenticate.

1. Obtain a JWT token by POSTing to the /login route in the Authentication section with your API key and credentials.
2. Paste the JWT token from the response into the "JWT Token" field at the top of the page and click the 'Add Token' button.

You will now be able to use the remaining routes to send requests to the API and get a response.

Language Selection

Language selection is done via the Accept-Language header. At the moment, you may only pass one language abbreviation in the header at a time. Valid language abbreviations can be found at the /languages route..

Authentication

Authentication to use the API is similar to the How-to section above. Users must POST to the /login route with their API key and credentials in the following format in order to obtain a JWT token.

{"apikey":"APIKEY","username":"USERNAME","userkey":"USERKEY"}

Note that the username and key are ONLY required for the /user routes. The user's key is labled Account Identifier in the account section of the main site. The token is then used in all subsequent requests by providing it in the Authorization header. The header will look like: Authorization: Bearer <yourJWTtoken>. Currently, the token expires after 24 hours. You can GET the /refresh_token route to extend that expiration date.

Versioning

You may request a different version of the API by including an Accept header in your request with the following format: Accept:application/vnd.thetvdb.v$VERSION. This documentation automatically uses the version seen at the top and bottom of the page.

Actions

episodes.id.get

Returns the full information for a given episode id. Deprecation Warning: The director key will be deprecated in favor of the new directors key in a future release.

thetvdb.episodes.id.get({
  "id": 0
}, context)

Input

• input object
  • id required integer: ID of the episode
  • Accept-Language string: Records are returned with the some fields in the desired language, if it exists. If there is no translation for the given language, then the record is still returned but with empty values for the translated fields.

Output

• output EpisodeRecordData

languages.get

All available languages. These language abbreviations can be used in the Accept-Language header for routes that return translation records.

thetvdb.languages.get(null, context)

Input

This action has no parameters

Output

• output LanguageData

languages.id.get

Information about a particular language, given the language ID.

thetvdb.languages.id.get({
  "id": ""
}, context)

Input

• input object
  • id required string: ID of the language

Output

• output Language

login.post

Returns a session token to be included in the rest of the requests. Note that API key authentication is required for all subsequent requests and user auth is required for routes in the User section

thetvdb.login.post({
  "Authentication string": null
}, context)

Input

• input object
  • Authentication string required Auth

Output

• output Token

movies.id.get

Returns a movies records that contains all information known about a particular movies id.

thetvdb.movies.id.get({
  "id": 0
}, context)

Input

• input object
  • id required integer: ID of the movie
  • Accept-Language string: Records are returned with the some fields in the desired language, if it exists. If there is no translation for the given language, then the record is still returned but with empty values for the translated fields.

Output

• output Movie

movieupdates.get

Returns all movies ids updated since a given timestamp.

thetvdb.movieupdates.get({
  "since": ""
}, context)

Input

• input object
  • since required string: Epoch time to start your date range.

Output

• output UpdatedMovies

refresh_token.get

Refreshes your current, valid JWT token and returns a new token. Hit this route so that you do not have to post to /login with your API key and credentials once you have already been authenticated.

thetvdb.refresh_token.get(null, context)

Input

This action has no parameters

Output

• output Token

search.series.get

Allows the user to search for a series based on the following parameters.

thetvdb.search.series.get({}, context)

Input

• input object
  • name string: Name of the series to search for.
  • imdbId string: IMDB id of the series
  • zap2itId string: Zap2it ID of the series to search for.
  • slug string: Slug from site URL of series (https://www.thetvdb.com/series/$SLUG)
  • Accept-Language string: Records are returned with the some fields in the desired language, if it exists. If there is no translation for the given language, then the record is still returned but with empty values for the translated fields.

Output

• output SeriesSearchResults

search.series.params.get

Returns an array of parameters to query by in the /search/series route.

thetvdb.search.series.params.get(null, context)

Input

This action has no parameters

Output

• output EpisodeDataQueryParams

series.id.get

Returns a series records that contains all information known about a particular series id.

thetvdb.series.id.get({
  "id": 0
}, context)

Input

• input object
  • id required integer: ID of the series
  • Accept-Language string: Records are returned with the some fields in the desired language, if it exists. If there is no translation for the given language, then the record is still returned but with empty values for the translated fields.

Output

• output SeriesData

series.id.head

Returns header information only about the given series ID.

thetvdb.series.id.head({
  "id": 0
}, context)

Input

• input object
  • id required integer: ID of the series
  • Accept-Language string: Records are returned with the some fields in the desired language, if it exists. If there is no translation for the given language, then the record is still returned but with empty values for the translated fields.

Output

Output schema unknown

series.id.actors.get

Returns actors for the given series id

thetvdb.series.id.actors.get({
  "id": 0
}, context)

Input

• input object
  • id required integer: ID of the series

Output

• output SeriesActors

series.id.episodes.get

All episodes for a given series. Paginated with 100 results per page.

thetvdb.series.id.episodes.get({
  "id": 0
}, context)

Input

• input object
  • id required integer: ID of the series
  • page string: Page of results to fetch. Defaults to page 1 if not provided.

Output

• output SeriesEpisodes

series.id.episodes.query.get

This route allows the user to query against episodes for the given series. The response is a paginated array of episode records.

thetvdb.series.id.episodes.query.get({
  "id": 0
}, context)

Input

• input object
  • id required integer: ID of the series
  • absoluteNumber string: Absolute number of the episode
  • airedSeason string: Aired season number
  • airedEpisode string: Aired episode number
  • dvdSeason string: DVD season number
  • dvdEpisode string: DVD episode number
  • imdbId string: IMDB id of the series
  • page string: Page of results to fetch. Defaults to page 1 if not provided.
  • Accept-Language string: Records are returned with the some fields in the desired language, if it exists. If there is no translation for the given language, then the record is still returned but with empty values for the translated fields.

Output

• output SeriesEpisodesQuery

series.id.episodes.query.params.get

Returns the allowed query keys for the /series/{id}/episodes/query route

thetvdb.series.id.episodes.query.params.get({
  "id": 0
}, context)

Input

• input object
  • id required integer: ID of the series

Output

• output SeriesEpisodesQueryParams

series.id.episodes.summary.get

Returns a summary of the episodes and seasons available for the series.

Note: Season "0" is for all episodes that are considered to be specials.

thetvdb.series.id.episodes.summary.get({
  "id": 0
}, context)

Input

• input object
  • id required integer: ID of the series

Output

• output SeriesEpisodesSummary

series.id.filter.get

Returns a series records, filtered by the supplied comma-separated list of keys. Query keys can be found at the /series/{id}/filter/params route.

thetvdb.series.id.filter.get({
  "id": 0,
  "keys": ""
}, context)

Input

• input object
  • id required integer: ID of the series
  • keys required string: Comma-separated list of keys to filter by
  • Accept-Language string: Records are returned with the some fields in the desired language, if it exists. If there is no translation for the given language, then the record is still returned but with empty values for the translated fields.

Output

• output SeriesData

series.id.filter.params.get

Returns the list of keys available for the /series/{id}/filter route

thetvdb.series.id.filter.params.get({
  "id": 0
}, context)

Input

• input object
  • id required integer: ID of the series
  • Accept-Language string: Records are returned with the some fields in the desired language, if it exists. If there is no translation for the given language, then the record is still returned but with empty values for the translated fields.

Output

• output FilterKeys

series.id.images.get

Returns a summary of the images for a particular series

thetvdb.series.id.images.get({
  "id": 0
}, context)

Input

• input object
  • id required integer: ID of the series
  • Accept-Language string: Records are returned with the some fields in the desired language, if it exists. If there is no translation for the given language, then the record is still returned but with empty values for the translated fields.

Output

• output SeriesImagesCounts

series.id.images.query.get

Query images for the given series ID.

thetvdb.series.id.images.query.get({
  "id": 0
}, context)

Input

• input object
  • id required integer: ID of the series
  • keyType string: Type of image you're querying for (fanart, poster, etc. See ../images/query/params for more details).
  • resolution string: Resolution to filter by (1280x1024, for example)
  • subKey string: Subkey for the above query keys. See /series/{id}/images/query/params for more information
  • Accept-Language string: Records are returned with the some fields in the desired language, if it exists. If there is no translation for the given language, then the record is still returned but with empty values for the translated fields.

Output

• output SeriesImageQueryResults

series.id.images.query.params.get

Returns the allowed query keys for the /series/{id}/images/query route. Contains a parameter record for each unique keyType, listing values that will return results.

thetvdb.series.id.images.query.params.get({
  "id": 0
}, context)

Input

• input object
  • id required integer: ID of the series
  • Accept-Language string: Records are returned with the some fields in the desired language, if it exists. If there is no translation for the given language, then the record is still returned but with empty values for the translated fields.

Output

• output SeriesImagesQueryParams

updated.query.get

Returns an array of series that have changed in a maximum of one week blocks since the provided fromTime.

The user may specify a toTime to grab results for less than a week. Any timespan larger than a week will be reduced down to one week automatically.

thetvdb.updated.query.get({
  "fromTime": ""
}, context)

Input

• input object
  • fromTime required string: Epoch time to start your date range.
  • toTime string: Epoch time to end your date range. Must be one week from fromTime.
  • Accept-Language string: Records are returned with the some fields in the desired language, if it exists. If there is no translation for the given language, then the record is still returned but with empty values for the translated fields.

Output

• output UpdateData

updated.query.params.get

Returns an array of valid query keys for the /updated/query/params route.

thetvdb.updated.query.params.get(null, context)

Input

This action has no parameters

Output

• output UpdateDataQueryParams

user.get

Returns basic information about the currently authenticated user.

thetvdb.user.get(null, context)

Input

This action has no parameters

Output

• output UserData

user.favorites.get

Returns an array of favorite series for a given user, will be a blank array if no favorites exist.

thetvdb.user.favorites.get(null, context)

Input

This action has no parameters

Output

• output UserFavoritesData

user.favorites.id.delete

Deletes the given series ID from the user’s favorite’s list and returns the updated list.

thetvdb.user.favorites.id.delete({
  "id": 0
}, context)

Input

• input object
  • id required integer: ID of the series

Output

• output UserFavoritesData

user.favorites.id.put

Adds the supplied series ID to the user’s favorite’s list and returns the updated list.

thetvdb.user.favorites.id.put({
  "id": 0
}, context)

Input

• input object
  • id required integer: ID of the series

Output

• output UserFavoritesData

user.ratings.get

Returns an array of ratings for the given user.

thetvdb.user.ratings.get(null, context)

Input

This action has no parameters

Output

• output UserRatingsData

user.ratings.query.get

Returns an array of ratings for a given user that match the query.

thetvdb.user.ratings.query.get({}, context)

Input

• input object
  • itemType string: Item to query. Can be either 'series', 'episode', or 'banner'

Output

• output UserRatingsData

user.ratings.query.params.get

Returns a list of query params for use in the /user/ratings/query route.

thetvdb.user.ratings.query.params.get(null, context)

Input

This action has no parameters

Output

• output UserRatingsQueryParams

user.ratings.itemType.itemId.delete

This route deletes a given rating of a given type.

thetvdb.user.ratings.itemType.itemId.delete({
  "itemType": "",
  "itemId": 0
}, context)

Input

• input object
  • itemType required string: Item to update. Can be either 'series', 'episode', or 'image'
  • itemId required integer: ID of the ratings record that you wish to modify

Output

• output UserRatingsDataNoLinksEmptyArray

user.ratings.itemType.itemId.itemRating.put

This route updates a given rating of a given type.

thetvdb.user.ratings.itemType.itemId.itemRating.put({
  "itemType": "",
  "itemId": 0,
  "itemRating": 0
}, context)

Input

• input object
  • itemType required string: Item to update. Can be either 'series', 'episode', or 'image'
  • itemId required integer: ID of the ratings record that you wish to modify
  • itemRating required integer: The updated rating number

Output

• output UserRatingsDataNoLinks

Definitions

Auth

• Auth object
  • apikey string
  • userkey string
  • username string

BasicEpisode

• BasicEpisode object
  • absoluteNumber integer
  • airedEpisodeNumber integer
  • airedSeason integer
  • dvdEpisodeNumber integer
  • dvdSeason integer
  • episodeName string
  • firstAired string
  • id integer
  • language EpisodeLanguageInfo
  • lastUpdated integer
  • overview string

Conflict

• Conflict object
  • Error string

Episode

• Episode object
  • absoluteNumber integer
  • airedEpisodeNumber integer
  • airedSeason integer
  • airsAfterSeason integer
  • airsBeforeEpisode integer
  • airsBeforeSeason integer
  • director string
  • directors array
    • items string
  • dvdChapter number
  • dvdDiscid string
  • dvdEpisodeNumber number
  • dvdSeason integer
  • episodeName string
  • filename string
  • firstAired string
  • guestStars array
    • items string
  • id integer
  • imdbId string
  • lastUpdated integer
  • lastUpdatedBy string
  • overview string
  • productionCode string
  • seriesId string
  • showUrl string
  • siteRating number
  • siteRatingCount integer
  • thumbAdded string
  • thumbAuthor integer
  • thumbHeight string
  • thumbWidth string
  • writers array
    • items string

EpisodeDataQueryParams

• EpisodeDataQueryParams object
  • data array
    • items string

EpisodeLanguageInfo

• EpisodeLanguageInfo object
  • episodeName string
  • overview string

EpisodeRecordData

• EpisodeRecordData object
  • data Episode
  • errors JSONErrors

FilterKeys

• FilterKeys object
  • data array
    • items string

InvalidQueryParams

• InvalidQueryParams object
  • Error string

JSONErrors

• JSONErrors object
  • invalidFilters array: Invalid filters passed to route
    • items string
  • invalidLanguage string: Invalid language or translation missing
  • invalidQueryParams array: Invalid query params passed to route
    • items string

Language

• Language object
  • abbreviation string
  • englishName string
  • id integer
  • name string

LanguageData

• LanguageData object
  • data array
    • items Language

Links

• Links object
  • first integer
  • last integer
  • next integer
  • previous integer

Movie

• Movie object
  • artworks array
    • items MovieArtwork
  • genres array
    • items MovieGenre
  • id integer
  • people object
    • actors array
      • items MoviePeople
    • directors array
      • items MoviePeople
    • producers array
      • items MoviePeople
    • writers array
      • items MoviePeople
  • release_dates array
    • items MovieReleaseDate
  • remoteids array
    • items MovieRemoteId
  • runtime integer
  • trailers array
    • items MovieTrailer
  • translations array
    • items MovieTranslation
  • url string

MovieArtwork

• MovieArtwork object
  • artwork_type string
  • height integer
  • id string
  • is_primary boolean
  • tags string
  • thumb_url string
  • url string
  • width integer

MovieGenre

• MovieGenre object
  • id integer
  • name string
  • url string

MoviePeople

• MoviePeople object
  • id string
  • imdb_id string
  • is_featured boolean
  • name string
  • people_facebook string
  • people_id string
  • people_image string
  • people_instagram string
  • people_twitter string
  • role string
  • role_image string

MovieReleaseDate

• MovieReleaseDate object
  • country string
  • date string
  • type string

MovieRemoteId

• MovieRemoteId object
  • id string
  • source_id integer
  • source_name string
  • source_url string
  • url string

MovieTrailer

• MovieTrailer object
  • name string
  • url string

MovieTranslation

• MovieTranslation object
  • is_primary boolean
  • language_code string
  • name string
  • overview string
  • tagline string

NotAuthorized

• NotAuthorized object
  • Error string

NotFound

• NotFound object
  • Error string

Series

• Series object
  • added string
  • airsDayOfWeek string
  • airsTime string
  • aliases array
    • items string
  • banner string
  • firstAired string
  • genre array
    • items string
  • id integer
  • imdbId string
  • lastUpdated integer
  • network string
  • networkId string
  • overview string
  • rating string
  • runtime string
  • seriesId string
  • seriesName string
  • siteRating number
  • siteRatingCount integer
  • slug string
  • status string
  • zap2itId string

SeriesActors

• SeriesActors object
  • data array
    • items SeriesActorsData
  • errors JSONErrors

SeriesActorsData

• SeriesActorsData object
  • id integer
  • image string
  • imageAdded string
  • imageAuthor integer
  • lastUpdated string
  • name string
  • role string
  • seriesId integer
  • sortOrder integer

SeriesData

• SeriesData object
  • data Series
  • errors JSONErrors

SeriesEpisodes

• SeriesEpisodes object
  • data array
    • items Episode
  • errors JSONErrors
  • links Links

SeriesEpisodesQuery

• SeriesEpisodesQuery object
  • data array
    • items Episode
  • errors JSONErrors
  • links Links

SeriesEpisodesQueryParams

• SeriesEpisodesQueryParams object
  • data array
    • items string

SeriesEpisodesSummary

• SeriesEpisodesSummary object
  • airedEpisodes string: Number of all aired episodes for this series
  • airedSeasons array
    • items string
  • dvdEpisodes string: Number of all dvd episodes for this series
  • dvdSeasons array
    • items string

SeriesImageQueryResult

• SeriesImageQueryResult object
  • fileName string
  • id integer
  • keyType string
  • languageId integer
  • ratingsInfo object
    • average number: Average rating for the given record.
    • count integer: Number of ratings for the given record.
  • resolution string
  • subKey string
  • thumbnail string

SeriesImageQueryResults

• SeriesImageQueryResults object
  • data array
    • items SeriesImageQueryResult
  • errors JSONErrors

SeriesImagesCount

• SeriesImagesCount object
  • fanart integer
  • poster integer
  • season integer
  • seasonwide integer
  • series integer

SeriesImagesCounts

• SeriesImagesCounts object
  • data SeriesImagesCount

SeriesImagesQueryParam

• SeriesImagesQueryParam object
  • keyType string
  • languageId string
  • resolution array
    • items string
  • subKey array
    • items string

SeriesImagesQueryParams

• SeriesImagesQueryParams object
  • data array
    • items SeriesImagesQueryParam

SeriesSearchResult

• SeriesSearchResult object
  • aliases array
    • items string
  • banner string
  • firstAired string
  • id integer
  • image string
  • network string
  • overview string
  • poster string
  • seriesName string
  • slug string
  • status string

SeriesSearchResults

• SeriesSearchResults object
  • data array
    • items SeriesSearchResult

Token

• Token object
  • token string

Update

• Update object
  • id integer
  • lastUpdated integer

UpdateData

• UpdateData object
  • data array
    • items Update
  • errors JSONErrors

UpdateDataQueryParams

• UpdateDataQueryParams object
  • data array
    • items string

UpdatedMovies

• UpdatedMovies object
  • movies array
    • items integer

User

• User object
  • favoritesDisplaymode string
  • language string
  • userName string

UserData

• UserData object
  • data User

UserFavorites

• UserFavorites object
  • favorites array
    • items string

UserFavoritesData

• UserFavoritesData object
  • data UserFavorites
  • errors JSONErrors

UserRatings

• UserRatings object
  • rating integer
  • ratingItemId integer
  • ratingType string

UserRatingsData

• UserRatingsData object
  • data array
    • items UserRatings
  • errors JSONErrors
  • links Links

UserRatingsDataNoLinks

• UserRatingsDataNoLinks object
  • data array
    • items UserRatings

UserRatingsDataNoLinksEmptyArray

• UserRatingsDataNoLinksEmptyArray object
  • data array

UserRatingsQueryParams

• UserRatingsQueryParams object
  • data array
    • items string