Copyright	This file is part of the package themoviedb. It is subject to the license terms in the LICENSE file found in the top-level directory of this distribution and at: https://github.com/pjones/themoviedb No part of this package including this file may be copied modified propagated or distributed except according to the terms contained in the LICENSE file.
License	MIT
Safe Haskell	None
Language	Haskell2010

Network.API.TheMovieDB

Contents

Types
Library Settings
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 (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.

Synopsis

data Movie = Movie {
- movieID :: ItemID
- movieTitle :: Text
- movieOverview :: Text
- movieGenres :: [Genre]
- moviePopularity :: Double
- moviePosterPath :: Text
- movieReleaseDate :: Maybe Day
- movieAdult :: Bool
- movieIMDB :: Text
- movieRunTime :: Int
}
data TV = TV {
- tvID :: ItemID
- tvName :: Text
- tvOverview :: Text
- tvGenres :: [Genre]
- tvPopularity :: Double
- tvPosterPath :: Text
- tvFirstAirDate :: Maybe Day
- tvLastAirDate :: Maybe Day
- tvNumberOfSeasons :: Int
- tvNumberOfEpisodes :: Int
- tvSeasons :: [Season]
}
data Season = Season {
- seasonID :: ItemID
- seasonNumber :: Int
- seasonAirDate :: Maybe Day
- seasonEpisodeCount :: Int
- seasonPosterPath :: Text
- seasonEpisodes :: [Episode]
}
data Episode = Episode {
- episodeID :: ItemID
- episodeNumber :: Int
- episodeName :: Text
- episodeOverview :: Text
- episodeSeasonNumber :: Int
- episodeAirDate :: Maybe Day
- episodeStillPath :: Text
}
data Genre = Genre {
- genreID :: ItemID
- genreName :: Text
}
data Error
- = InvalidKeyError
- | HttpExceptionError HttpException
- | ServiceError String
- | ResponseParseError String (Maybe LByteString)
type ItemID = Int
data Settings = Settings {
- tmdbKey :: Key
- tmdbLanguage :: Maybe LanguageCode
}
defaultSettings :: Key -> Settings
type Key = Text
type LanguageCode = Text
data TheMovieDB a
runTheMovieDB :: Settings -> TheMovieDB a -> IO (Either Error a)
runTheMovieDBWithManager :: Manager -> Settings -> TheMovieDB a -> IO (Either Error a)
searchMovies :: Text -> TheMovieDB [Movie]
fetchMovie :: ItemID -> TheMovieDB Movie
searchTV :: Text -> TheMovieDB [TV]
fetchTV :: ItemID -> TheMovieDB TV
fetchTVSeason :: ItemID -> Int -> TheMovieDB Season
fetchFullTVSeries :: ItemID -> TheMovieDB TV
data Configuration
config :: TheMovieDB Configuration
moviePosterURLs :: Configuration -> Movie -> [Text]
tvPosterURLs :: Configuration -> TV -> [Text]
seasonPosterURLs :: Configuration -> Season -> [Text]
episodeStillURLs :: Configuration -> Episode -> [Text]

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 Source #
Instance details Defined in Network.API.TheMovieDB.Types.Movie Methods (==) :: Movie -> Movie -> Bool # (/=) :: Movie -> Movie -> Bool #
Show Movie Source #
Instance details Defined in Network.API.TheMovieDB.Types.Movie Methods showsPrec :: Int -> Movie -> ShowS # show :: Movie -> String # showList :: [Movie] -> ShowS #
FromJSON Movie Source #
Instance details Defined in Network.API.TheMovieDB.Types.Movie Methods parseJSON :: Value -> Parser Movie # parseJSONList :: Value -> Parser [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 Source #
Instance details Defined in Network.API.TheMovieDB.Types.TV Methods (==) :: TV -> TV -> Bool # (/=) :: TV -> TV -> Bool #
Ord TV Source #
Instance details 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 Source #
Instance details Defined in Network.API.TheMovieDB.Types.TV Methods showsPrec :: Int -> TV -> ShowS # show :: TV -> String # showList :: [TV] -> ShowS #
FromJSON TV Source #
Instance details Defined in Network.API.TheMovieDB.Types.TV Methods parseJSON :: Value -> Parser TV # parseJSONList :: Value -> Parser [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 Source #
Instance details Defined in Network.API.TheMovieDB.Types.Season Methods (==) :: Season -> Season -> Bool # (/=) :: Season -> Season -> Bool #
Ord Season Source #
Instance details 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 Source #
Instance details Defined in Network.API.TheMovieDB.Types.Season Methods showsPrec :: Int -> Season -> ShowS # show :: Season -> String # showList :: [Season] -> ShowS #
FromJSON Season Source #
Instance details Defined in Network.API.TheMovieDB.Types.Season Methods parseJSON :: Value -> Parser Season # parseJSONList :: Value -> Parser [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 Source #
Instance details Defined in Network.API.TheMovieDB.Types.Episode Methods (==) :: Episode -> Episode -> Bool # (/=) :: Episode -> Episode -> Bool #
Ord Episode Source #
Instance details 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 Source #
Instance details Defined in Network.API.TheMovieDB.Types.Episode Methods showsPrec :: Int -> Episode -> ShowS # show :: Episode -> String # showList :: [Episode] -> ShowS #
FromJSON Episode Source #
Instance details Defined in Network.API.TheMovieDB.Types.Episode Methods parseJSON :: Value -> Parser Episode # parseJSONList :: Value -> Parser [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 Source #
Instance details Defined in Network.API.TheMovieDB.Types.Genre Methods (==) :: Genre -> Genre -> Bool # (/=) :: Genre -> Genre -> Bool #
Show Genre Source #
Instance details Defined in Network.API.TheMovieDB.Types.Genre Methods showsPrec :: Int -> Genre -> ShowS # show :: Genre -> String # showList :: [Genre] -> ShowS #
FromJSON Genre Source #
Instance details Defined in Network.API.TheMovieDB.Types.Genre Methods parseJSON :: Value -> Parser Genre # parseJSONList :: Value -> Parser [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 LByteString)	Invalid or error response from the API.

Instances

Show Error Source #
Instance details Defined in Network.API.TheMovieDB.Internal.Types Methods showsPrec :: Int -> Error -> ShowS # show :: Error -> String # showList :: [Error] -> ShowS #

type ItemID = Int Source #

Type to represent IDs used by the API.

Library Settings

data Settings Source #

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 Source #
Instance details Defined in Network.API.TheMovieDB.Internal.Settings Methods toJSON :: Settings -> Value # toEncoding :: Settings -> Encoding # toJSONList :: [Settings] -> Value # toEncodingList :: [Settings] -> Encoding #
FromJSON Settings Source #
Instance details Defined in Network.API.TheMovieDB.Internal.Settings Methods parseJSON :: Value -> Parser Settings # parseJSONList :: Value -> Parser [Settings] #

defaultSettings :: Key -> Settings Source #

Default settings.

type Key = Text Source #

Type for the API key issued by TheMovieDB.

type LanguageCode = Text Source #

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

API Functions

data TheMovieDB a Source #

Result type for operations involving TheMovieDB API.

Instances

Monad TheMovieDB Source #
Instance details 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 # fail :: String -> TheMovieDB a #
Functor TheMovieDB Source #
Instance details Defined in Network.API.TheMovieDB.Internal.TheMovieDB Methods fmap :: (a -> b) -> TheMovieDB a -> TheMovieDB b # (<$) :: a -> TheMovieDB b -> TheMovieDB a #
Applicative TheMovieDB Source #
Instance details 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 Source #
Instance details Defined in Network.API.TheMovieDB.Internal.TheMovieDB Methods liftIO :: IO a -> TheMovieDB a #

runTheMovieDB Source #

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 Source #

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

Instances

Generic Configuration Source #
Instance details 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 Source #
Instance details Defined in Network.API.TheMovieDB.Internal.Configuration Methods toJSON :: Configuration -> Value # toEncoding :: Configuration -> Encoding # toJSONList :: [Configuration] -> Value # toEncodingList :: [Configuration] -> Encoding #
FromJSON Configuration Source #
Instance details Defined in Network.API.TheMovieDB.Internal.Configuration Methods parseJSON :: Value -> Parser Configuration # parseJSONList :: Value -> Parser [Configuration] #
type Rep Configuration Source #
Instance details Defined in Network.API.TheMovieDB.Internal.Configuration type Rep Configuration = D1 (MetaData "Configuration" "Network.API.TheMovieDB.Internal.Configuration" "themoviedb-1.2.0.0-KnFlr4mbeSgEZg6sVCYTV5" 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 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.