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 (defaultSettings 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

Defined in Network.API.TheMovieDB.Types.Movie

Methods

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

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

Show Movie

Defined in Network.API.TheMovieDB.Types.Movie

Methods

showsPrec :: Int -> Movie -> ShowS

show :: Movie -> String

showList :: [Movie] -> ShowS

FromJSON Movie

Defined in Network.API.TheMovieDB.Types.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

Defined in Network.API.TheMovieDB.Types.TV

Methods

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

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

Ord TV

Defined in Network.API.TheMovieDB.Types.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

Defined in Network.API.TheMovieDB.Types.TV

Methods

showsPrec :: Int -> TV -> ShowS

show :: TV -> String

showList :: [TV] -> ShowS

FromJSON TV

Defined in Network.API.TheMovieDB.Types.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

Defined in Network.API.TheMovieDB.Types.Season

Methods

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

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

Ord Season

Defined in Network.API.TheMovieDB.Types.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

Defined in Network.API.TheMovieDB.Types.Season

Methods

showsPrec :: Int -> Season -> ShowS

show :: Season -> String

showList :: [Season] -> ShowS

FromJSON Season

Defined in Network.API.TheMovieDB.Types.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

Defined in Network.API.TheMovieDB.Types.Episode

Methods

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

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

Ord Episode

Defined in Network.API.TheMovieDB.Types.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

Defined in Network.API.TheMovieDB.Types.Episode

Methods

showsPrec :: Int -> Episode -> ShowS

show :: Episode -> String

showList :: [Episode] -> ShowS

FromJSON Episode

Defined in Network.API.TheMovieDB.Types.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

Defined in Network.API.TheMovieDB.Types.Genre

Methods

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

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

Show Genre

Defined in Network.API.TheMovieDB.Types.Genre

Methods

showsPrec :: Int -> Genre -> ShowS

show :: Genre -> String

showList :: [Genre] -> ShowS

FromJSON Genre

Defined in Network.API.TheMovieDB.Types.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 LByteString)

Invalid or error response from the API.

Instances

Show Error

Defined in Network.API.TheMovieDB.Internal.Types

Methods

showsPrec :: Int -> Error -> ShowS

show :: Error -> String

showList :: [Error] -> ShowS

type ItemID = Int

Type to represent IDs used by the API.

Library Settings

data Settings

Settings used by this library.

Constructors

Settings

Fields

• tmdbKey :: Key

  The API key to use.

• tmdbLanguage :: Maybe LanguageCode

  Optional ISO 639-1 language code to send with every request.

Instances

ToJSON Settings

Defined in Network.API.TheMovieDB.Internal.Settings

Methods

toJSON :: Settings -> Value

toEncoding :: Settings -> Encoding

toJSONList :: [Settings] -> Value

toEncodingList :: [Settings] -> Encoding

FromJSON Settings

Defined in Network.API.TheMovieDB.Internal.Settings

Methods

parseJSON :: Value -> Parser Settings

parseJSONList :: Value -> Parser [Settings]

defaultSettings :: Key -> Settings

Default settings.

type Key = Text

Type for the API key issued by TheMovieDB.

type LanguageCode = Text

Type for selecting a TMDb language in ISO 639-1 format.

API Functions

data TheMovieDB a

Result type for operations involving TheMovieDB API.

Instances

Monad TheMovieDB

Defined in Network.API.TheMovieDB.Internal.TheMovieDB

Methods

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

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

return :: a -> TheMovieDB a

Functor TheMovieDB

Defined in Network.API.TheMovieDB.Internal.TheMovieDB

Methods

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

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

Applicative TheMovieDB

Defined in Network.API.TheMovieDB.Internal.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

Defined in Network.API.TheMovieDB.Internal.TheMovieDB

Methods

liftIO :: IO a -> TheMovieDB a

runTheMovieDB

Arguments

:: Settings

Library settings.

-> 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.

-> Settings

Library settings.

-> 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.

Instances

Generic Configuration

Defined in Network.API.TheMovieDB.Internal.Configuration

Associated Types

type Rep Configuration :: Type -> Type

Methods

from :: Configuration -> Rep Configuration x

to :: Rep Configuration x -> Configuration

ToJSON Configuration

Defined in Network.API.TheMovieDB.Internal.Configuration

Methods

toJSON :: Configuration -> Value

toEncoding :: Configuration -> Encoding

toJSONList :: [Configuration] -> Value

toEncodingList :: [Configuration] -> Encoding

FromJSON Configuration

Defined in Network.API.TheMovieDB.Internal.Configuration

Methods

parseJSON :: Value -> Parser Configuration

parseJSONList :: Value -> Parser [Configuration]

type Rep Configuration

Defined in Network.API.TheMovieDB.Internal.Configuration

type Rep Configuration = D1 ('MetaData "Configuration" "Network.API.TheMovieDB.Internal.Configuration" "themoviedb-1.2.1-6maNURGzi74BMNjlj5A7S2" 'False) (C1 ('MetaCons "Configuration" 'PrefixI 'True) (S1 ('MetaSel ('Just "cfgImageBaseURL") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 Text) :*: (S1 ('MetaSel ('Just "cfgImageSecBaseURL") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 Text) :*: S1 ('MetaSel ('Just "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.