Network.API.TheMovieDB

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.

Types

data Movie

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

Methods

(==) :: Movie -> Movie -> Bool

(/=) :: Movie -> Movie -> Bool

Show Movie

Methods

showsPrec :: Int -> Movie -> ShowS

show :: Movie -> String

showList :: [Movie] -> ShowS

FromJSON Movie

Methods

parseJSON :: Value -> Parser Movie

parseJSONList :: Value -> Parser [Movie]

data TV

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

Methods

(==) :: TV -> TV -> Bool

(/=) :: TV -> TV -> Bool

Ord TV

Methods

compare :: TV -> TV -> Ordering

(<) :: TV -> TV -> Bool

(<=) :: TV -> TV -> Bool

(>) :: TV -> TV -> Bool

(>=) :: TV -> TV -> Bool

max :: TV -> TV -> TV

min :: TV -> TV -> TV

Show TV

Methods

showsPrec :: Int -> TV -> ShowS

show :: TV -> String

showList :: [TV] -> ShowS

FromJSON TV

Methods

parseJSON :: Value -> Parser TV

parseJSONList :: Value -> Parser [TV]

data Season

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

Methods

(==) :: Season -> Season -> Bool

(/=) :: Season -> Season -> Bool

Ord Season

Methods

compare :: Season -> Season -> Ordering

(<) :: Season -> Season -> Bool

(<=) :: Season -> Season -> Bool

(>) :: Season -> Season -> Bool

(>=) :: Season -> Season -> Bool

max :: Season -> Season -> Season

min :: Season -> Season -> Season

Show Season

Methods

showsPrec :: Int -> Season -> ShowS

show :: Season -> String

showList :: [Season] -> ShowS

FromJSON Season

Methods

parseJSON :: Value -> Parser Season

parseJSONList :: Value -> Parser [Season]

data Episode

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

Methods

(==) :: Episode -> Episode -> Bool

(/=) :: Episode -> Episode -> Bool

Ord Episode

Methods

compare :: Episode -> Episode -> Ordering

(<) :: Episode -> Episode -> Bool

(<=) :: Episode -> Episode -> Bool

(>) :: Episode -> Episode -> Bool

(>=) :: Episode -> Episode -> Bool

max :: Episode -> Episode -> Episode

min :: Episode -> Episode -> Episode

Show Episode

Methods

showsPrec :: Int -> Episode -> ShowS

show :: Episode -> String

showList :: [Episode] -> ShowS

FromJSON Episode

Methods

parseJSON :: Value -> Parser Episode

parseJSONList :: Value -> Parser [Episode]

data Genre

Metadata for a genre.

Constructors

Genre

Fields

• genreID :: ItemID

  TheMovieDB unique ID.

• genreName :: Text

  The name of the genre.

Instances

Eq Genre

Methods

(==) :: Genre -> Genre -> Bool

(/=) :: Genre -> Genre -> Bool

Show Genre

Methods

showsPrec :: Int -> Genre -> ShowS

show :: Genre -> String

showList :: [Genre] -> ShowS

FromJSON Genre

Methods

parseJSON :: Value -> Parser Genre

parseJSONList :: Value -> Parser [Genre]

data Error

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

Methods

showsPrec :: Int -> Error -> ShowS

show :: Error -> String

showList :: [Error] -> ShowS

type ItemID = Int

Type to represent IDs used by the API.

type Key = Text

Type for the API key issued by TheMovieDB.

API Functions

data TheMovieDB a

Result type for operations involving TheMovieDB API.

Instances

Monad TheMovieDB

Methods

(>>=) :: TheMovieDB a -> (a -> TheMovieDB b) -> TheMovieDB b

(>>) :: TheMovieDB a -> TheMovieDB b -> TheMovieDB b

return :: a -> TheMovieDB a

fail :: String -> TheMovieDB a

Functor TheMovieDB

Methods

fmap :: (a -> b) -> TheMovieDB a -> TheMovieDB b

(<$) :: a -> TheMovieDB b -> TheMovieDB a

Applicative TheMovieDB

Methods

pure :: a -> TheMovieDB a

(<*>) :: TheMovieDB (a -> b) -> TheMovieDB a -> TheMovieDB b

liftA2 :: (a -> b -> c) -> TheMovieDB a -> TheMovieDB b -> TheMovieDB c

(*>) :: TheMovieDB a -> TheMovieDB b -> TheMovieDB b

(<*) :: TheMovieDB a -> TheMovieDB b -> TheMovieDB a

MonadIO TheMovieDB

Methods

liftIO :: IO a -> TheMovieDB a

runTheMovieDB

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

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]

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

Arguments

:: ItemID

TheMovieDB ID for the movie.

-> TheMovieDB Movie

Fetch the metadata for the Movie with the given ID.

searchTV :: Text -> TheMovieDB [TV]

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

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

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

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

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

Associated Types

type Rep Configuration :: * -> *

Methods

from :: Configuration -> Rep Configuration x

to :: Rep Configuration x -> Configuration

ToJSON Configuration

Methods

toJSON :: Configuration -> Value

toEncoding :: Configuration -> Encoding

toJSONList :: [Configuration] -> Value

toEncodingList :: [Configuration] -> Encoding

FromJSON Configuration

Methods

parseJSON :: Value -> Parser Configuration

parseJSONList :: Value -> Parser [Configuration]

Binary Configuration

Methods

put :: Configuration -> Put

get :: Get Configuration

putList :: [Configuration] -> Put

type Rep Configuration

type Rep Configuration = D1 * (MetaData "Configuration" "Network.API.TheMovieDB.Internal.Configuration" "themoviedb-1.1.4.0-FWYrHG7HF9U5GVdYlX5Pjb" False) (C1 * (MetaCons "Configuration" PrefixI True) ((:*:) * (S1 * (MetaSel (Just Symbol "cfgImageBaseURL") NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 * Text)) ((:*:) * (S1 * (MetaSel (Just Symbol "cfgImageSecBaseURL") NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 * Text)) (S1 * (MetaSel (Just Symbol "cfgPosterSizes") NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 * [Text])))))

config :: TheMovieDB Configuration

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]

Return a list of URLs for all possible movie posters.

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

Return a list of URLs for all possible TV posters.

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

Return a list of URLs for all possible season posters.

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

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