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	Safe-Inferred
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

Instances details

FromJSON Movie Source #
Instance details Defined in Network.API.TheMovieDB.Types.Movie Methods parseJSON :: Value -> Parser Movie # parseJSONList :: Value -> Parser [Movie] #
Show Movie Source #
Instance details Defined in Network.API.TheMovieDB.Types.Movie Methods showsPrec :: Int -> Movie -> ShowS # show :: Movie -> String # showList :: [Movie] -> ShowS #
Eq Movie Source #
Instance details Defined in Network.API.TheMovieDB.Types.Movie Methods (==) :: Movie -> Movie -> Bool # (/=) :: Movie -> Movie -> Bool #

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

Instances details

FromJSON TV Source #
Instance details Defined in Network.API.TheMovieDB.Types.TV Methods parseJSON :: Value -> Parser TV # parseJSONList :: Value -> Parser [TV] #
Show TV Source #
Instance details Defined in Network.API.TheMovieDB.Types.TV Methods showsPrec :: Int -> TV -> ShowS # show :: TV -> String # showList :: [TV] -> ShowS #
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 #

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

Instances details

FromJSON Season Source #
Instance details Defined in Network.API.TheMovieDB.Types.Season Methods parseJSON :: Value -> Parser Season # parseJSONList :: Value -> Parser [Season] #
Show Season Source #
Instance details Defined in Network.API.TheMovieDB.Types.Season Methods showsPrec :: Int -> Season -> ShowS # show :: Season -> String # showList :: [Season] -> ShowS #
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 #

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

Instances details

FromJSON Episode Source #
Instance details Defined in Network.API.TheMovieDB.Types.Episode Methods parseJSON :: Value -> Parser Episode # parseJSONList :: Value -> Parser [Episode] #
Show Episode Source #
Instance details Defined in Network.API.TheMovieDB.Types.Episode Methods showsPrec :: Int -> Episode -> ShowS # show :: Episode -> String # showList :: [Episode] -> ShowS #
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 #

data Genre Source #

Metadata for a genre.

Constructors

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

Instances

Instances details

FromJSON Genre Source #
Instance details Defined in Network.API.TheMovieDB.Types.Genre Methods parseJSON :: Value -> Parser Genre # parseJSONList :: Value -> Parser [Genre] #
Show Genre Source #
Instance details Defined in Network.API.TheMovieDB.Types.Genre Methods showsPrec :: Int -> Genre -> ShowS # show :: Genre -> String # showList :: [Genre] -> ShowS #
Eq Genre Source #
Instance details Defined in Network.API.TheMovieDB.Types.Genre Methods (==) :: Genre -> Genre -> Bool # (/=) :: Genre -> Genre -> Bool #

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

Instances details

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

Instances details

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

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

Instances details

MonadIO TheMovieDB Source #
Instance details Defined in Network.API.TheMovieDB.Internal.TheMovieDB Methods liftIO :: IO a -> 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 #
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 #
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 #

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

Instances details

FromJSON Configuration Source #
Instance details Defined in Network.API.TheMovieDB.Internal.Configuration Methods parseJSON :: Value -> Parser Configuration # parseJSONList :: Value -> Parser [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 #
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 #
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.2-BJmi1ZfYUxmEKyi1Jn9JiM" '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.