Network.API.TheMovieDB

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

A typical workflow while using this library is:

1. Place an API Key inside a Context using mkContext or one of the utility functions in Network.API.TheMovieDB.Util.
2. Retrieve API Configuration information using either the config function or the configErr function.
3. Search TheMovieDB using either the search function or the searchErr function.
4. Since the search functions don't return a full Movie record follow them up with the fetch function or the fetchErr function.

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

Types

TheMovieDB Metadata

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

Instances

FromJSON Configuration

data Movie

Metadata for a movie.

• The moviePosterPath is an incomplete URL. To construct a complete URL you'll need to use the Configuration type. You can also use moviePosterURLs.

Constructors

Movie

Fields

movieID :: MovieID

TheMovieDB unique ID.

movieTitle :: String

The name/title of the movie.

movieOverview :: String

Short plot summary.

movieGenres :: [Genre]

List of Genres.

moviePopularity :: Double

Popularity ranking.

moviePosterPath :: String

Incomplete URL for poster image. See moviePosterURLs.

movieReleaseDate :: Day

Movie release date.

movieAdult :: Bool

TheMovieDB adult movie flag.

movieIMDB :: String

IMDB.com ID.

movieRunTime :: Int

Movie length in minutes.

Instances

Eq Movie

Show Movie

FromJSON Movie

data Genre

Metadata for a genre.

Constructors

Genre

Fields

genreID :: GenreID

TheMovieDB unique ID.

genreName :: String

The name of the genre.

Instances

Eq Genre

Show Genre

FromJSON Genre

Context and Errors

data Context

Data that needs to be given to the API functions. Use the mkContext function to turn an API Key into a Context.

data Error

Possible errors returned by the API.

Constructors

NetworkError String

Network or HTTP error.

ParseError String

Invalid or error response from the API.

Instances

Eq Error

Show Error

Type Synonyms

type Key = String

Type for the API key issued by TheMovieDB.

type MovieID = Int

Type for representing unique movie IDs.

type GenreID = Int

Type for representing unique genre IDs.

type SearchQuery = String

A search query for TheMovieDB API.

API Functions

Functions That Fail

config :: Context -> IO Configuration

Fetch the API configuration information or fail. For a function that returns an error instead of failing see configErr.

fetch :: Context -> MovieID -> IO Movie

Fetch the metadata for the movie with the given ID and fail if any errors are encountered along the way. For a function that returns an error instead of failing see fetchErr.

search :: Context -> SearchQuery -> IO [Movie]

Search TheMovieDB using the given query string and return a list of movies. This function fails if there are any errors. For a function that returns an error instead of failing see searchErr.

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 fetchErr or fetch.

Functions That Return Errors

configErr :: Context -> IO (Either Error Configuration)

Fetch the API configuration information such as base URLs for movie posters. Results in either an Error or a Configuration.

fetchErr :: Context -> MovieID -> IO (Either Error Movie)

Fetch the metadata for the movie with the given ID. Returns either an Error or a Movie.

searchErr :: Context -> SearchQuery -> IO (Either Error [Movie])

Search TheMovieDB using the given query string and return either an Error if something went wrong or a list of matching Movies.

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 fetchErr or fetch.

Utility functions

mkContext :: Key -> Context

Turns an API Key into a Context so that you can call the API functions such as fetch and search.

apiKey :: Context -> Key

Extract an API Key from a Context.

moviePosterURLs :: Configuration -> Movie -> [String]

Return a list of URLs for all possible movie posters.