Safe Haskell	None
Language	Haskell2010

Network.API.TheMovieDB

Contents

Types
API Functions
Utility Types and Functions

Description

This library provides some data types and functions for fetching movie metadata from http://TheMovieDB.org. To use this library start by requesting an API key from http://docs.themoviedb.apiary.io.

Example:

import Network.API.TheMovieDB

main :: IO ()
main = do
  -- The API key assigned to you (as a Text value).
  let key = "your API key"

  -- The fetch function will get a Movie record based on its ID.
  result <- runTheMovieDB key (fetchMovie 9340)

  -- Do something with the result (or error).
  putStrLn (show result)

This library also includes an example executable in the example directory.

Synopsis

Types

data Movie Source

Metadata for a movie.

The moviePosterPath field is an incomplete URL. To construct a complete URL you'll need to use the Configuration type and the moviePosterURLs helper function.

Constructors

Movie

Fields

movieID :: ItemID: TheMovieDB unique ID.
movieTitle :: Text: The name/title of the movie.
movieOverview :: Text: Short plot summary.
movieGenres :: [Genre]: List of Genres.
moviePopularity :: Double: Popularity ranking.
moviePosterPath :: Text: Incomplete URL for poster image. See moviePosterURLs.
movieReleaseDate :: Maybe Day: Movie release date. (Movie may not have been released yet.)
movieAdult :: Bool: TheMovieDB adult movie flag.
movieIMDB :: Text: IMDB.com ID.
movieRunTime :: Int: Movie length in minutes.

Instances

Eq Movie
Show Movie
FromJSON Movie

data TV Source

Metadata for a TV series.

The tvPosterPath field is an incomplete URL. To construct a complete URL you'll need to use the Configuration type and the tvPosterURLs helper function.

Constructors

TV

Fields

tvID :: ItemID

TheMovieDB unique ID.

tvName :: Text

The name of the TV series.

tvOverview :: Text

Short description of the TV series.

tvGenres :: [Genre]

List of Genres.

tvPopularity :: Double

Popularity ranking.

tvPosterPath :: Text

Incomplete URL for poster image. See tvPosterURLs.

tvFirstAirDate :: Maybe Day

Air date for first episode.

tvLastAirDate :: Maybe Day

Air date for last episode.

tvNumberOfSeasons :: Int

Number of seasons for the TV series.

tvNumberOfEpisodes :: Int

Total number of episodes for all seasons.

tvSeasons :: [Season]

Information about each season.

The number of elements in this list may not match tvNumberOfSeasons. Information about special episodes and unreleased episodes are usually kept in a Season listed as season 0. Therefore, the first element in this list might not be season 1.

Instances

Eq TV
Ord TV
Show TV
FromJSON TV

data Season Source

Metadata for a TV Season.

The seasonPosterPath field is an incomplete URL. To construct a complete URL you'll need to use the Configuration type and the seasonPosterURLs helper function.

Constructors

Season

Fields

seasonID :: ItemID: TheMovieDB unique ID.
seasonNumber :: Int: Season sequence number. Remember that season 0 is sometimes used to hold unreleased/unaired episodes.
seasonAirDate :: Maybe Day: The date this season began to air, if ever.
seasonEpisodeCount :: Int: Number of episodes in this season.
seasonPosterPath :: Text: Incomplete URL for poster image. See seasonPosterURLs.
seasonEpisodes :: [Episode]: List of Episodes.

Instances

Eq Season
Ord Season
Show Season
FromJSON Season

data Episode Source

Metadata for a TV Episode.

The episodeStillPath field is an incomplete URL. To construct a complete URL you'll need to use the Configuration type and the episodeStillURLs helper function.

Constructors

Episode

Fields

episodeID :: ItemID: TheMovieDB unique ID.
episodeNumber :: Int: Episode sequence number.
episodeName :: Text: Episode name.
episodeOverview :: Text: Short description of the episode.
episodeSeasonNumber :: Int: The season this episode belongs to.
episodeAirDate :: Maybe Day: Episode air date, if it ever aired.
episodeStillPath :: Text: Incomplete URL to a still image from the episode. See the episodeStillURLs function for more information.

Instances

Eq Episode
Ord Episode
Show Episode
FromJSON Episode

data Genre Source

Metadata for a genre.

Constructors

Genre
Fields genreID :: ItemID TheMovieDB unique ID. genreName :: Text The name of the genre.

Instances

Eq Genre
Show Genre
FromJSON Genre

data Error Source

Possible errors returned by the API.

Constructors

InvalidKeyError	Missing or invalid API key. Make sure you are using a valid API key issued by https://www.themoviedb.org/faq/api.
HttpExceptionError HttpException	An exception relating to HTTP was thrown while interacting with the API.
ServiceError String	The HTTP interaction with the API service did not result in a successful response. Information about the failure is encoded in the String.
ResponseParseError String (Maybe ByteString)	Invalid or error response from the API.

Instances

Show Error

type ItemID = Int Source

Type to represent IDs used by the API.

type Key = Text Source

Type for the API key issued by TheMovieDB.

API Functions

data TheMovieDB a Source

Result type for operations involving TheMovieDB API.

Instances

Monad TheMovieDB
Functor TheMovieDB
Applicative TheMovieDB
MonadIO TheMovieDB

runTheMovieDB Source

Arguments

:: Key	The API key to include in all requests.
-> TheMovieDB a	The API calls to make.
-> IO (Either Error a)	Response or error.

Execute requests for TheMovieDB with the given API key and produce either an error or a result.

This version creates a temporary Manager using tlsManagerSettings. If you want to use an existing Manager you should use runTheMovieDBWithManager instead.

runTheMovieDBWithManager Source

Arguments

:: Manager	The `Manager` to use.
-> Key	The API key to include in all requests.
-> TheMovieDB a	The API calls to make.
-> IO (Either Error a)	Response or error.

Execute requests for TheMovieDB with the given API key and produce either an error or a result.

This version allows you to provide a Manager value which should have been created to allow TLS requests (e.g., with tlsManagerSettings).

searchMovies :: Text -> TheMovieDB [Movie] Source

Search TheMovieDB using the given query string.

The movies returned will not have all their fields completely filled out, to get a complete record you'll need to follow this call up with a call to fetchMovie.

fetchMovie Source

Arguments

:: ItemID	TheMovieDB ID for the movie.
-> TheMovieDB Movie

Fetch the metadata for the Movie with the given ID.

searchTV :: Text -> TheMovieDB [TV] Source

Search TheMovieDB for matching TV series.

The TV values returned from this function will be partial records. The only fields that will be available are tvID, tvName, tvPosterPath, tvPopularity, and possibly tvFirstAirDate.

To get full TV records you need to follow this function with a call to fetchTV using the desired tvID value.

fetchTV Source

Arguments

:: ItemID	TheMovieDB ID for the TV series.
-> TheMovieDB TV

Fetch metadata for a TV series given its TheMovieDB ID. The metadata for Seasons listed in the TV series will not have complete Episode information.

After calling this function you should call fetchTVSeason to fill in the Episode metadata, or just begin with fetchFullTVSeries.

fetchTVSeason Source

Arguments

:: ItemID	TheMovieDB ID for the TV series.
-> Int	Season number (not season ID).
-> TheMovieDB Season

Fetch metadata for a Season, including all Episodes.

fetchFullTVSeries Source

Arguments

:: ItemID	TheMovieDB ID for the TV series.
-> TheMovieDB TV

Fetch full metadata for a TV series, including all seasons and episodes.

This function will make multiple HTTP requests to TheMovieDB API.

Utility Types and Functions

data Configuration Source

TheMovieDB API tries to preserve bandwidth by omitting information (such as full URLs for poster images) from most of the API calls. Therefore in order to construct a complete URL for a movie poster you'll need to use the config function to retrieve API configuration information.

A helper function is provided (moviePosterURLs) that constructs a list of all poster URLs given a Movie and Configuration.

According to the API documentation for TheMovieDB, you should cache the Configuration value and only request it every few days. Therefore, it is an instance of the Binary class so it can be serialized to and from a cache file on disk.

Alternatively, the FromJSON and ToJSON instances can be used to cache the Configuration value.

Instances

Generic Configuration
ToJSON Configuration
FromJSON Configuration
Binary Configuration
type Rep Configuration

config :: TheMovieDB Configuration Source

Fetch the API configuration information such as base URLs for movie posters. The resulting configuration value should be cached and only requested every few days.

moviePosterURLs :: Configuration -> Movie -> [Text] Source

Return a list of URLs for all possible movie posters.

tvPosterURLs :: Configuration -> TV -> [Text] Source

Return a list of URLs for all possible TV posters.

seasonPosterURLs :: Configuration -> Season -> [Text] Source

Return a list of URLs for all possible season posters.

episodeStillURLs :: Configuration -> Episode -> [Text] Source

Return a list of URLs for all possible episode still images.