Package com.github.m0nk3y2k4.thetvdb.api

Interface TheTVDBApi.Extended

Enclosing interface:

TheTVDBApi

public static interface TheTVDBApi.Extended

Interface representing the API's Extended layout.

This layout may be used for slightly advance API integration. Like the common layout it'll take care of parsing the received JSON into Java DTO's but it will also provide access to any additional contextual information. Methods of this layout will always return a single APIResponse object which consists of the actual data, parsed as DTO, as well as all additional information which is available in the given context, like additional error or pagination information. This layout does not provide any shortcut-methods.

See Also:

TheTVDBApi.extended()

Method Summary

Modifier and Type	Method	Description
APIResponse<List<String>>	addToFavorites(long seriesId)	Adds the supplied series ID to the user’s favorite’s list and returns a response object containing the updated list as plain Strings.
APIResponse<List<Rating>>	addToRatings(String itemType, long itemId, long itemRating)	Updates a given rating of a given type and return a response object containing the modified rating, mapped as Java DTO.
APIResponse<List<String>>	deleteFromFavorites(long seriesId)	Deletes the given series ID from the user’s favorite’s list and returns a response object containing the updated list as plain Strings.
void	deleteFromRatings(String itemType, long itemId)	Deletes a given rating of a given type.
APIResponse<Series>	filterSeries(long seriesId, QueryParameters queryParameters)	Returns a response object containing a filtered series record based on the given parameters, mapped as Java DTO.
APIResponse<List<Actor>>	getActors(long seriesId)	Returns a response object containing a list of actors for a specific series mapped as Java DTO.
APIResponse<List<String>>	getAvailableEpisodeQueryParameters(long seriesId)	Returns a response object containing a list of keys which are valid parameters for querying episodes, as plain Strings.
APIResponse<List<ImageQueryParameter>>	getAvailableImageQueryParameters(long seriesId)	Returns a response object containing a list of valid parameters for querying a series images, mapped as Java DTO.
APIResponse<List<Language>>	getAvailableLanguages()	Returns a response object containing a list of all supported languages mapped as Java DTO.
APIResponse<List<String>>	getAvailableLastUpdatedQueryParameters()	Returns a response object containing a list of valid parameters for querying series which have been updated lately, as plain Strings.
APIResponse<List<String>>	getAvailableRatingsQueryParameters()	Returns a response object containing a list of valid parameters for querying user ratings, as plain Strings.
APIResponse<List<String>>	getAvailableSeriesFilterParameters(long seriesId)	Returns a response object containing a list of keys which are valid parameters for filtering series, as plain Strings.
APIResponse<List<String>>	getAvailableSeriesSearchParameters()	Returns a response object containing possible query parameters, which can be used to search for series, mapped as Java DTO.
APIResponse<Episode>	getEpisode(long episodeId)	Returns a response object containing the full information for a given episode id as mapped Java DTO.
APIResponse<List<Episode>>	getEpisodes(long seriesId, QueryParameters queryParameters)	Returns a response object containing all episodes of a specific series mapped as Java DTO.
APIResponse<List<String>>	getFavorites()	Returns a response object containing a list of favorite series for a given user, as plain Strings.
APIResponse<Language>	getLanguage(long languageId)	Returns a response object containing further language information for a given language ID mapped as Java DTO.
APIResponse<Movie>	getMovie(long movieId)	Returns a response object containing detailed information for a specific movie mapped as Java DTO.
APIResponse<List<Long>>	getMovieUpdates(long since)	Returns a response object containing a list of ID's of all movies, that have been updated since the given epoch timestamp, mapped as Java DTO.
APIResponse<List<Rating>>	getRatings()	Returns a response object containing a list of ratings for the given user, mapped as Java DTO.
APIResponse<Series>	getSeries(long seriesId)	Returns a response object containing detailed information for a specific series mapped as Java DTO.
APIResponse<SeriesSummary>	getSeriesEpisodesSummary(long seriesId)	Returns a response object containing a summary of the episodes and seasons available for a series, mapped as Java DTO.
APIResponse<Map<String,String>>	getSeriesHeaderInformation(long seriesId)	Returns a response object containing header information for a specific series as key/value pairs.
APIResponse<ImageSummary>	getSeriesImagesSummary(long seriesId)	Returns a response object containing a summary of the images types and counts available for a particular series, mapped as Java DTO.
APIResponse<User>	getUser()	Returns a response object containing basic information about the currently authenticated user, mapped as Java DTO.
APIResponse<List<Episode>>	queryEpisodes(long seriesId, QueryParameters queryParameters)	Returns a response object containing all matching episodes of a specific series mapped as Java DTO.
APIResponse<List<Image>>	queryImages(long seriesId, QueryParameters queryParameters)	Returns a response object containing the matching result of querying images for a specific series, mapped as Java DTO.
APIResponse<Map<Long,Long>>	queryLastUpdated(QueryParameters queryParameters)	Returns a response object containing a map of series that have changed in a maximum of one week blocks since the provided fromTime query parameter, as plain Strings.
APIResponse<List<Rating>>	queryRatings(QueryParameters queryParameters)	Returns a response object containing a list of ratings for a given user that match the query, mapped as Java DTO.
APIResponse<List<SeriesSearchResult>>	searchSeries(QueryParameters queryParameters)	Returns a response object containing a list of series search results based on the given query parameters mapped as Java DTO.

Method Detail

getEpisode

APIResponse<Episode> getEpisode(long episodeId)
                         throws APIException

Returns a response object containing the full information for a given episode id as mapped Java DTO.

Corresponds to remote API route: [GET] /episodes/{id}

Parameters:

episodeId - The ID of the episode

Returns:

Extended API response containing the actually requested data as well as optional, additional error and paging information. Please note that not all API routes provide additional information so this type of data might be empty.

Throws:

APIException - If an exception with the remote API occurs, e.g. authentication failure, IO error, the given episode ID does not exist, etc.

See Also:

TheTVDBApi.JSON.getEpisode(episodeId), TheTVDBApi.getEpisode(episodeId)

getAvailableLanguages

APIResponse<List<Language>> getAvailableLanguages()
                                           throws APIException

Returns a response object containing a list of all supported languages mapped as Java DTO. These language abbreviations can be used to set the preferred language for the communication with the remote service (see TheTVDBApi.setLanguage(String).

Corresponds to remote API route: [GET] /languages

Returns:

Extended API response containing the actually requested data as well as optional, additional error and paging information. Please note that not all API routes provide additional information so this type of data might be empty.

Throws:

APIException - If an exception with the remote API occurs, e.g. authentication failure, IO error, resource not found, etc.

See Also:

TheTVDBApi.JSON.getAvailableLanguages(), TheTVDBApi.getAvailableLanguages()

getLanguage

APIResponse<Language> getLanguage(long languageId)
                           throws APIException

Returns a response object containing further language information for a given language ID mapped as Java DTO. The language abbreviation can be used to set the preferred language for the communication with the remote service (see TheTVDBApi.setLanguage(String).

Corresponds to remote API route: [GET] /languages/{id}

Parameters:

languageId - The ID of the language

Returns:

Extended API response containing the actually requested data as well as optional, additional error and paging information. Please note that not all API routes provide additional information so this type of data might be empty.

Throws:

APIException - If an exception with the remote API occurs, e.g. authentication failure, IO error, resource not found, etc. or if the given language ID does not exist.

See Also:

TheTVDBApi.JSON.getLanguage(languageId), TheTVDBApi.getLanguage(languageId)

getMovie

APIResponse<Movie> getMovie(long movieId)
                     throws APIException

Returns a response object containing detailed information for a specific movie mapped as Java DTO.

Corresponds to remote API route: [GET] /movies/{id}

Parameters:

movieId - The TheTVDB.com movie ID

Returns:

Extended API response containing the actually requested data as well as optional, additional error and paging information. Please note that not all API routes provide additional information so this type of data might be empty.

Throws:

APIException - If an exception with the remote API occurs, e.g. authentication failure, IO error, the given movie ID does not exist, etc.

See Also:

TheTVDBApi.JSON.getMovie(movieId), TheTVDBApi.getMovie(movieId)

getMovieUpdates

APIResponse<List<Long>> getMovieUpdates(long since)
                                 throws APIException

Returns a response object containing a list of ID's of all movies, that have been updated since the given epoch timestamp, mapped as Java DTO.

Corresponds to remote API route: [GET] /movieupdates

Parameters:

since - Epoch time to start your date range

Returns:

Extended API response containing the actually requested data as well as optional, additional error and paging information. Please note that not all API routes provide additional information so this type of data might be empty.

Throws:

APIException - If an exception with the remote API occurs, e.g. authentication failure, IO error, resource not found, etc.

See Also:

TheTVDBApi.JSON.getMovieUpdates(since), TheTVDBApi.getMovieUpdates(since)

searchSeries

APIResponse<List<SeriesSearchResult>> searchSeries(QueryParameters queryParameters)
                                            throws APIException

Returns a response object containing a list of series search results based on the given query parameters mapped as Java DTO. The list contains basic information of all series matching the query parameters.

Corresponds to remote API route: [GET] /search/series

Parameters:

queryParameters - Object containing key/value pairs of query search parameters. For a complete list of possible search parameters see the API documentation or use getAvailableSeriesSearchParameters().

Returns:

Extended API response containing the actually requested data as well as optional, additional error and paging information. Please note that not all API routes provide additional information so this type of data might be empty.

Throws:

APIException - If an exception with the remote API occurs, e.g. authentication failure, IO error, resource not found, etc. or if no records are found that match your query.

See Also:

TheTVDBApi.JSON.searchSeries(queryParameters), TheTVDBApi.searchSeries(queryParameters)

getAvailableSeriesSearchParameters

APIResponse<List<String>> getAvailableSeriesSearchParameters()
                                                      throws APIException

Returns a response object containing possible query parameters, which can be used to search for series, mapped as Java DTO.

Corresponds to remote API route: [GET] /search/series/params

Returns:

Extended API response containing the actually requested data as well as optional, additional error and paging information. Please note that not all API routes provide additional information so this type of data might be empty.

Throws:

APIException - If an exception with the remote API occurs, e.g. authentication failure, IO error, resource not found, etc.

See Also:

TheTVDBApi.JSON.getAvailableSeriesSearchParameters(), TheTVDBApi.getAvailableSeriesSearchParameters(), TheTVDBApi.JSON.searchSeries(queryParams), TheTVDBApi.searchSeries(queryParams)

getSeries

APIResponse<Series> getSeries(long seriesId)
                       throws APIException

Returns a response object containing detailed information for a specific series mapped as Java DTO.

Corresponds to remote API route: [GET] /series/{id}

Parameters:

seriesId - The TheTVDB.com series ID

Returns:

Extended API response containing the actually requested data as well as optional, additional error and paging information. Please note that not all API routes provide additional information so this type of data might be empty.

Throws:

APIException - If an exception with the remote API occurs, e.g. authentication failure, IO error, the given series ID does not exist, etc.

See Also:

TheTVDBApi.JSON.getSeries(seriesId), TheTVDBApi.getSeries(seriesId)

getSeriesHeaderInformation

APIResponse<Map<String,String>> getSeriesHeaderInformation(long seriesId)
                                                    throws APIException

Returns a response object containing header information for a specific series as key/value pairs. Good for getting the Last-Updated header to find out when the series was last modified.

Corresponds to remote API route: [HEAD] /series/{id}

Parameters:

seriesId - The TheTVDB.com series ID

Returns:

Extended API response containing the actually requested data as well as optional, additional error and paging information. Please note that not all API routes provide additional information so this type of data might be empty.

Throws:

APIException - If an exception with the remote API occurs, e.g. authentication failure, IO error, the given series ID does not exist, etc.

See Also:

TheTVDBApi.JSON.getSeriesHeaderInformation(seriesId), TheTVDBApi.getSeriesHeaderInformation(seriesId)

getActors

APIResponse<List<Actor>> getActors(long seriesId)
                            throws APIException

Returns a response object containing a list of actors for a specific series mapped as Java DTO.

Corresponds to remote API route: [GET] /series/{id}/actors

Parameters:

seriesId - The TheTVDB.com series ID

Returns:

Extended API response containing the actually requested data as well as optional, additional error and paging information. Please note that not all API routes provide additional information so this type of data might be empty.

Throws:

APIException - If an exception with the remote API occurs, e.g. authentication failure, IO error, the given series ID does not exist, etc.

See Also:

TheTVDBApi.JSON.getActors(seriesId), TheTVDBApi.getActors(seriesId)

getEpisodes

APIResponse<List<Episode>> getEpisodes(long seriesId,
                                       QueryParameters queryParameters)
                                throws APIException

Returns a response object containing all episodes of a specific series mapped as Java DTO. Results will be paginated with 100 results per page. Use queryParameters to select a specific result page.

Corresponds to remote API route: [GET] /series/{id}/episodes

Parameters:

seriesId - The TheTVDB.com series ID

queryParameters - Object containing key/value pairs of query parameters. For a complete list of possible parameters see the API documentation.

Returns:

Extended API response containing the actually requested data as well as optional, additional error and paging information. Please note that not all API routes provide additional information so this type of data might be empty.

Throws:

APIException - If an exception with the remote API occurs, e.g. authentication failure, IO error, the given series ID does not exist, etc.

See Also:

TheTVDBApi.JSON.getEpisodes(seriesId, queryParameters), TheTVDBApi.getEpisodes(seriesId, queryParameters)

queryEpisodes

APIResponse<List<Episode>> queryEpisodes(long seriesId,
                                         QueryParameters queryParameters)
                                  throws APIException

Returns a response object containing all matching episodes of a specific series mapped as Java DTO. Results will be paginated. Note that this method is deterministic and will always return the first result page of the available episodes.

Corresponds to remote API route: [GET] /series/{id}/episodes/query

Parameters:

seriesId - The TheTVDB.com series ID

queryParameters - Object containing key/value pairs of query parameters. For a complete list of possible query parameters see the API documentation or use getAvailableEpisodeQueryParameters(seriesId).

Returns:

Extended API response containing the actually requested data as well as optional, additional error and paging information. Please note that not all API routes provide additional information so this type of data might be empty.

Throws:

APIException - If an exception with the remote API occurs, e.g. authentication failure, IO error, the given series ID does not exist, etc. or if no records are found that match your query.

See Also:

TheTVDBApi.JSON.queryEpisodes(seriesId, queryParameters), TheTVDBApi.queryEpisodes(seriesId, queryParameters)

getAvailableEpisodeQueryParameters

APIResponse<List<String>> getAvailableEpisodeQueryParameters(long seriesId)
                                                      throws APIException

Returns a response object containing a list of keys which are valid parameters for querying episodes, as plain Strings. These keys are permitted to be used in QueryParameters objects when querying for specific episodes of a series.

Corresponds to remote API route: [GET] /series/{id}/episodes/query/params

Parameters:

seriesId - The TheTVDB.com series ID

Returns:

Extended API response containing the actually requested data as well as optional, additional error and paging information. Please note that not all API routes provide additional information so this type of data might be empty.

Throws:

APIException - If an exception with the remote API occurs, e.g. authentication failure, IO error, the given series ID does not exist, etc.

See Also:

queryEpisodes(seriesId, queryParameters), TheTVDBApi.JSON.getAvailableEpisodeQueryParameters(seriesId), TheTVDBApi.getAvailableEpisodeQueryParameters(seriesId)

getSeriesEpisodesSummary

APIResponse<SeriesSummary> getSeriesEpisodesSummary(long seriesId)
                                             throws APIException

Returns a response object containing a summary of the episodes and seasons available for a series, mapped as Java DTO.
Note: Season "0" is for all episodes that are considered to be specials.

Corresponds to remote API route: [GET] /series/{id}/episodes/summary

Parameters:

seriesId - The TheTVDB.com series ID

Returns:

Extended API response containing the actually requested data as well as optional, additional error and paging information. Please note that not all API routes provide additional information so this type of data might be empty.

Throws:

APIException - If an exception with the remote API occurs, e.g. authentication failure, IO error, the given series ID does not exist, etc.

See Also:

TheTVDBApi.JSON.getSeriesEpisodesSummary(seriesId), TheTVDBApi.getSeriesEpisodesSummary(seriesId)

filterSeries

APIResponse<Series> filterSeries(long seriesId,
                                 QueryParameters queryParameters)
                          throws APIException

Returns a response object containing a filtered series record based on the given parameters, mapped as Java DTO.

Corresponds to remote API route: [GET] /series/{id}/filter

Parameters:

seriesId - The TheTVDB.com series ID

queryParameters - Object containing key/value pairs of query parameters. For a complete list of possible query parameters see the API documentation or use getAvailableSeriesFilterParameters(seriesId).

Returns:

Extended API response containing the actually requested data as well as optional, additional error and paging information. Please note that not all API routes provide additional information so this type of data might be empty.

Throws:

APIException - If an exception with the remote API occurs, e.g. authentication failure, IO error, the given series ID does not exist, etc.

See Also:

TheTVDBApi.JSON.filterSeries(seriesId, queryParameters), TheTVDBApi.filterSeries(seriesId, queryParameters)

getAvailableSeriesFilterParameters

APIResponse<List<String>> getAvailableSeriesFilterParameters(long seriesId)
                                                      throws APIException

Returns a response object containing a list of keys which are valid parameters for filtering series, as plain Strings. These keys are permitted to be used in QueryParameters objects when filtering for a specific series.

Corresponds to remote API route: [GET] /series/{id}/filter/params

Parameters:

seriesId - The TheTVDB.com series ID

Returns:

Extended API response containing the actually requested data as well as optional, additional error and paging information. Please note that not all API routes provide additional information so this type of data might be empty.

Throws:

APIException - If an exception with the remote API occurs, e.g. authentication failure, IO error, the given series ID does not exist, etc.

See Also:

filterSeries(seriesId, queryParameters), TheTVDBApi.JSON.getAvailableSeriesFilterParameters(seriesId), TheTVDBApi.getAvailableSeriesFilterParameters(seriesId)

getSeriesImagesSummary

APIResponse<ImageSummary> getSeriesImagesSummary(long seriesId)
                                          throws APIException

Returns a response object containing a summary of the images types and counts available for a particular series, mapped as Java DTO.

Corresponds to remote API route: [GET] /series/{id}/images

Parameters:

seriesId - The TheTVDB.com series ID

Returns:

Extended API response containing the actually requested data as well as optional, additional error and paging information. Please note that not all API routes provide additional information so this type of data might be empty.

Throws:

APIException - If an exception with the remote API occurs, e.g. authentication failure, IO error, the given series ID does not exist, etc.

See Also:

TheTVDBApi.JSON.getSeriesImagesSummary(seriesId), TheTVDBApi.getSeriesImagesSummary(seriesId)

queryImages

APIResponse<List<Image>> queryImages(long seriesId,
                                     QueryParameters queryParameters)
                              throws APIException

Returns a response object containing the matching result of querying images for a specific series, mapped as Java DTO.

Corresponds to remote API route: [GET] /series/{id}/images/query

Parameters:

seriesId - The TheTVDB.com series ID

queryParameters - Object containing key/value pairs of query parameters. For a complete list of possible query parameters see the API documentation or use getAvailableImageQueryParameters(seriesId).

Returns:

Extended API response containing the actually requested data as well as optional, additional error and paging information. Please note that not all API routes provide additional information so this type of data might be empty.

Throws:

APIException - If an exception with the remote API occurs, e.g. authentication failure, IO error, the given series ID does not exist, etc. or if no records are found that match your query.

See Also:

TheTVDBApi.JSON.queryImages(seriesId, queryParameters), TheTVDBApi.queryImages(seriesId, queryParameters)

getAvailableImageQueryParameters

APIResponse<List<ImageQueryParameter>> getAvailableImageQueryParameters(long seriesId)
                                                                 throws APIException

Returns a response object containing a list of valid parameters for querying a series images, mapped as Java DTO. Unlike other routes, querying for a series images may be restricted to certain combinations of query keys. The allowed combinations are clustered in the single ImageQueryParameter objects of the returned API responses data object.

Corresponds to remote API route: [GET] /series/{id}/images/query/params

Parameters:

seriesId - The TheTVDB.com series ID

Returns:

Extended API response containing the actually requested data as well as optional, additional error and paging information. Please note that not all API routes provide additional information so this type of data might be empty.

Throws:

APIException - If an exception with the remote API occurs, e.g. authentication failure, IO error, the given series ID does not exist, etc.

See Also:

queryImages(seriesId, queryParameters), TheTVDBApi.JSON.getAvailableImageQueryParameters(seriesId), TheTVDBApi.getAvailableImageQueryParameters(seriesId)

queryLastUpdated

APIResponse<Map<Long,Long>> queryLastUpdated(QueryParameters queryParameters)
                                      throws APIException

Returns a response object containing a map of series that have changed in a maximum of one week blocks since the provided fromTime query parameter, as plain Strings. The key/value pairs of the returned data object's map represent a TheTVDB.com series ID (key) and when it was updated the last time (value) as Epoch time. Note that the given query parameters must always contain a valid fromTime Epoch timestamp key.

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

Corresponds to remote API route: [GET] /updated/query

Parameters:

queryParameters - Object containing key/value pairs of query parameters. For a complete list of possible query parameters see the API documentation or use getAvailableLastUpdatedQueryParameters().

Returns:

Extended API response containing the actually requested data as well as optional, additional error and paging information. Please note that not all API routes provide additional information so this type of data might be empty.

Throws:

APIException - If an exception with the remote API occurs, e.g. authentication failure, IO error, resource not found, etc. or no records exist for the given timespan.

See Also:

TheTVDBApi.JSON.queryLastUpdated(queryParameters), TheTVDBApi.queryLastUpdated(queryParameters)

getAvailableLastUpdatedQueryParameters

APIResponse<List<String>> getAvailableLastUpdatedQueryParameters()
                                                          throws APIException

Returns a response object containing a list of valid parameters for querying series which have been updated lately, as plain Strings. These keys are permitted to be used in QueryParameters objects when querying for recently updated series.

Corresponds to remote API route: [GET] /updated/query/params

Returns:

Extended API response containing the actually requested data as well as optional, additional error and paging information. Please note that not all API routes provide additional information so this type of data might be empty.

Throws:

APIException - If an exception with the remote API occurs, e.g. authentication failure, IO error, resource not found, etc.

See Also:

queryLastUpdated(queryParameters), TheTVDBApi.JSON.getAvailableLastUpdatedQueryParameters(), TheTVDBApi.getAvailableLastUpdatedQueryParameters()

getUser

APIResponse<User> getUser()
                   throws APIException

Returns a response object containing basic information about the currently authenticated user, mapped as Java DTO.

Corresponds to remote API route: [GET] /user

Returns:

Extended API response containing the actually requested data as well as optional, additional error and paging information. Please note that not all API routes provide additional information so this type of data might be empty.

Throws:

APIException - If an exception with the remote API occurs, e.g. authentication failure, IO error, resource not found, etc. or if no information exists for the current user

See Also:

TheTVDBApi.JSON.getUser(), TheTVDBApi.getUser()

getFavorites

APIResponse<List<String>> getFavorites()
                                throws APIException

Returns a response object containing a list of favorite series for a given user, as plain Strings. The data object of the returned response will contain an empty list if no favorites exist.

Corresponds to remote API route: [GET] /user/favorites

Returns:

Extended API response containing the actually requested data as well as optional, additional error and paging information. Please note that not all API routes provide additional information so this type of data might be empty.

Throws:

APIException - If an exception with the remote API occurs, e.g. authentication failure, IO error, resource not found, etc. or if no information exists for the current user

See Also:

TheTVDBApi.JSON.getFavorites(), TheTVDBApi.getFavorites()

deleteFromFavorites

APIResponse<List<String>> deleteFromFavorites(long seriesId)
                                       throws APIException

Deletes the given series ID from the user’s favorite’s list and returns a response object containing the updated list as plain Strings.

Corresponds to remote API route: [DELETE] /user/favorites/{id}

Parameters:

seriesId - The TheTVDB.com series ID

Returns:

Extended API response containing the actually requested data as well as optional, additional error and paging information. Please note that not all API routes provide additional information so this type of data might be empty.

Throws:

APIException - If an exception with the remote API occurs, e.g. authentication failure, IO error, resource not found, etc. or if no information exists for the current user or the requested record could not be deleted

See Also:

addToFavorites(seriesId), TheTVDBApi.JSON.deleteFromFavorites(seriesId), TheTVDBApi.deleteFromFavorites(seriesId)

addToFavorites

APIResponse<List<String>> addToFavorites(long seriesId)
                                  throws APIException

Adds the supplied series ID to the user’s favorite’s list and returns a response object containing the updated list as plain Strings.

Corresponds to remote API route: [PUT] /user/favorites/{id}

Parameters:

seriesId - The TheTVDB.com series ID

Returns:

Extended API response containing the actually requested data as well as optional, additional error and paging information. Please note that not all API routes provide additional information so this type of data might be empty.

Throws:

APIException - If an exception with the remote API occurs, e.g. authentication failure, IO error, resource not found, etc. or if no information exists for the current user or the requested record could not be updated

See Also:

deleteFromFavorites(seriesId), TheTVDBApi.JSON.addToFavorites(seriesId), TheTVDBApi.addToFavorites(seriesId)

getRatings

APIResponse<List<Rating>> getRatings()
                              throws APIException

Returns a response object containing a list of ratings for the given user, mapped as Java DTO.

Corresponds to remote API route: [GET] /user/ratings

Returns:

Extended API response containing the actually requested data as well as optional, additional error and paging information. Please note that not all API routes provide additional information so this type of data might be empty.

Throws:

APIException - If an exception with the remote API occurs, e.g. authentication failure, IO error, resource not found, etc. or if no information exists for the current user

See Also:

TheTVDBApi.JSON.getRatings(), TheTVDBApi.getRatings()

queryRatings

APIResponse<List<Rating>> queryRatings(QueryParameters queryParameters)
                                throws APIException

Returns a response object containing a list of ratings for a given user that match the query, mapped as Java DTO.

Corresponds to remote API route: [GET] /user/ratings/query

Parameters:

queryParameters - Object containing key/value pairs of query parameters. For a complete list of possible query parameters see the API documentation or use getAvailableRatingsQueryParameters().

Returns:

Extended API response containing the actually requested data as well as optional, additional error and paging information. Please note that not all API routes provide additional information so this type of data might be empty.

Throws:

APIException - If an exception with the remote API occurs, e.g. authentication failure, IO error, resource not found, etc. or if no information exists for the current user

See Also:

TheTVDBApi.JSON.queryRatings(queryParameters), TheTVDBApi.queryRatings(queryParameters)

getAvailableRatingsQueryParameters

APIResponse<List<String>> getAvailableRatingsQueryParameters()
                                                      throws APIException

Returns a response object containing a list of valid parameters for querying user ratings, as plain Strings. These keys are permitted to be used in QueryParameters objects when querying for ratings.

Corresponds to remote API route: [GET] /user/ratings/query/params

Returns:

Extended API response containing the actually requested data as well as optional, additional error and paging information. Please note that not all API routes provide additional information so this type of data might be empty.

Throws:

APIException - If an exception with the remote API occurs, e.g. authentication failure, IO error, resource not found, etc. or if no information exists for the current user

See Also:

queryRatings(queryParameters), TheTVDBApi.JSON.getAvailableRatingsQueryParameters(), TheTVDBApi.getAvailableRatingsQueryParameters()

deleteFromRatings

void deleteFromRatings(@Nonnull
                       String itemType,
                       long itemId)
                throws APIException

Deletes a given rating of a given type.

Corresponds to remote API route: [DELETE] /user/ratings/{itemType}/{itemId}

Parameters:

itemType - Item to update. Can be either 'series', 'episode', or 'image'.

itemId - ID of the ratings record that you wish to delete

Throws:

APIException - If an exception with the remote API occurs, e.g. authentication failure, IO error, resource not found, etc. or if no rating is found that matches your given parameters

See Also:

addToRatings(itemType, itemId, itemRating), TheTVDBApi.JSON.deleteFromRatings(itemType, itemId), TheTVDBApi.deleteFromRatings(itemType, itemId)

addToRatings

APIResponse<List<Rating>> addToRatings(@Nonnull
                                       String itemType,
                                       long itemId,
                                       long itemRating)
                                throws APIException

Updates a given rating of a given type and return a response object containing the modified rating, mapped as Java DTO. If no rating exists yet, a new rating will be created.

Corresponds to remote API route: [PUT] /user/ratings/{itemType}/{itemId}/{itemRating}

Parameters:

itemType - Item to update. Can be either 'series', 'episode', or 'image'.

itemId - ID of the ratings record that you wish to modify

itemRating - The updated rating number

Returns:

Extended API response containing the actually requested data as well as optional, additional error and paging information. Please note that not all API routes provide additional information so this type of data might be empty.
Note: It seems that the data returned by the remote service for this route is quite unreliable! It might not always return the modified rating but an empty data array instead.

Throws:

APIException - If an exception with the remote API occurs, e.g. authentication failure, IO error, resource not found, etc. or if no rating is found that matches your given parameters

See Also:

deleteFromRatings(itemType, itemId), TheTVDBApi.JSON.addToRatings(itemType, itemId, itemRating), TheTVDBApi.addToRatings(itemType, itemId, itemRating)