GitHub - RenegadeFox/movie-metadata: A simple utility to easily fetch movie metadata, given an Array of movie titles, using the API from the Open Movie Database.

A simple utility to easily fetch movie metadata from a list of movie titles using the API from the Open Movie Database.

What Movie Metadata Does

movie-metadata will take an Array, List or JSON file filled with movie titles, and search the Open Movie Database (omdb) API for their respective metadata (Title, Rating, Writers, Actors, Plot, Runtime, etc.) and output the metadata into a JSON file (CLI) or return an Object with the same information.

Installing

movie-metadata is available via npm.

It can be installed either locally (for programmatic implementation) or globally (for general usage)

Local Installation:

npm install movie-metadata --save

Global Installation:

npm install -g movie-metadata --save

Usage

This is how you can use movie-metadata.

CLI Usage

How to use movie-metadata with the Command-Line Interface (CLI).

Note: Assuming that movie-metadata is globally installed

Example

$ getmetadata --key YOUR_API_KEY  /Users/me/moviesList.json

This will create a moviesList-metadata.json and moviesList-notFound.json file in the /Users/me/ directory.

Note: The moviesList-notFound.json file is only created if some movies in the list were not found on the omdb API server.

The moviesList-metadata.json file will contain an Array of Objects containing each movies respective metadata fetched from omdb's API server omdbapi.com.

Programmatic usage

How to use movie-metadata from within a .js file

Note: Assuming that movie-metadata is locally installed

Example: Async/Await

const { getMetadata } = require('movie-metadata')

async function getIt() {
    const metadata = await getMetadata({
        key: 'YOUR_API_KEY',
        source: ['dead man\'s chest', 'at world\'s end', 'ralph breaks the internet', 'Ocean\'s Eight']
    })

    console.log(metadata)
}

getIt()

// Outputs

{ fetchedMetadata: [
    {
        Title: 'Pirates of the Caribbean: Dead Man\'s Chest',
        Year: '2006',
        Rated: 'PG-13',
        Released: '07 Jul 2006',
        Runtime: '151 min',
        Genre: 'Action, Adventure, Fantasy',
        Director: 'Gore Verbinski',
        Writer: 'Ted Elliott, Terry Rossio, Ted Elliott (characters), Terry Rossio (characters), Stuart Beattie (characters), Jay Wolpert...'
        Actors: 'Johnny Depp, Orlando Bloom, Keira Knightley, Jack Davenport',
        Plot: 'Jack Sparrow races to recover the heart of Davy Jones to avoid enslaving his soul to Jones\' service, as other friends a...'
        Language: 'English, Turkish, Greek, Mandarin, French',
        Country: 'USA',
        Awards: 'Won 1 Oscar. Another 42 wins & 53 nominations.',
        Poster: 'https://m.media-amazon.com/images/M/MV5BMTcwODc1MTMxM15BMl5BanBnXkFtZTYwMDg1NzY3._V1_SX300.jpg',
        Ratings: [Array],
        Metascore: '53',
        imdbRating: '7.3',
        imdbVotes: '597,591',
        imdbID: 'tt0383574',
        Type: 'movie',
        DVD: '05 Dec 2006',
        BoxOffice: '$423,032,628',
        Production: 'Buena Vista',
        Website: 'http://pirates.movies.com',
        Response: 'True'
    },
    ...
],
notFoundMovies: [] }

Example: Promises

const { getMetadata } = require('movie-metadata')

getMetadata({
    key: 'YOUR_API_KEY',
    source: ['dead man\'s chest', 'at world\'s end', 'ralph breaks the internet', 'Ocean\'s Eight']
}).then(metadata => {
  console.log(metadata)  
})

// Same output

API Reference

Below is a reference to all of movie-metadata's API properties.

CLI API

This is the API when movie-metadata is installed globally, and is used within the CLI.

`--key|-k`

omdb API key

Default: none
Type: String

Example

$ getmetadata -k YOUR_API_KEY
// or
$ getmetadata --key YOUR_API_KEY

`--source|-s`

Source JSON file of movie titles to search with

Default: none
Type: String / JSON File Path

Example

$ getmetadata -k YOUR_API_KEY -s /path/to/movies/list.json
// or
$ getmetadata -k YOUR_API_KEY --source /path/to/movies/list.json

`--progress|-p`

Whether or not to show a CLI progress bar while downloading the metadata

Default: true
Type: Boolean

Example

$ getmetadata -k YOUR_API_KEY -s /movies/list.json -p false
// or
$ getmetadata -k YOUR_API_KEY -s /movies/list.json --progress false

`--verbose|-v`

Whether or not to run verbosely

Note: This disables --progress parameter, if enabled

Default: false
Type: Boolean

Example

$ getmetadata -k YOUR_API_KEY -s /movies/list.json -v
// or
$ getmetadata -k YOUR_API_KEY -s /movies/list.json --verbose

`--dest|-d`

Where to save the JSON file with metadata

Default: Same path as source with '-metadata' appended
Type: String

Example

$ getmetadata -k YOUR_API_KEY -s /movies/list.json -d /movies/metadata.json
// or
$ getmetadata -k YOUR_API_KEY -s /movies/list.json --dest /movies/metadata.json

`--notFound|-n`

Where to save the JSON file that holds the movies that were not found on the omdb API server

Note: the notFound file will only be create if there was any movies that were not found on the omdb API server.

Default: Same path as source with '-notFound' appended
Type: String

Example

$ getmetadata -k YOUR_API_KEY -s /movies/list.json -n /movies/metadata.json
// or
$ getmetadata -k YOUR_API_KEY -s /movies/list.json --notFound /movies/notFound.json

`--overwrite|-o`

Whether or not to overwrite the source file with the metadata JSON data

Note: If enabled, this disables dest parameter.

Default: false
Type: Boolean

Example

$ getmetadata -k YOUR_API_KEY -s /movies/list.json -o
// or
$ getmetadata -k YOUR_API_KEY -s /movies/list.json --overwrite

Programmatic API

This is the API when movie-metadata is installed locally, and is used within a .js file.

`key`

omdb API key

Default: none
Type: String

Example

const { getMetadata } = require('movie-metadata')

getMetadata({
    key: 'YOUR_API_KEY',
    source: 'path/to/list/of/movies.json'
}).then(metadata => {
  // Do stuff with the Array of movies (with metadata)
})

`source`

Path to JSON file, Array, or list of movie titles to fetch metadata for

Default: none
Type: String|Array|JSON file path

Note: If a string is provided and it is not a path to a JSON file, then the "splitter" parameter is used to split the String into an Array of Strings

Example: JSON file

const { getMetadata } = require('movie-metadata')

getMetadata({
    key: 'YOUR_API_KEY',
    source: 'path/to/list/of/movies.json'
}).then(metadata => {
  // Do stuff with the Array of movies (with metadata)
})

// movies.json file format
[
    "Ocean's Eight",
    "Ralph Breaks the Internet"
    // ...
]

Example: Array (inline)

const { getMetadata } = require('movie-metadata')

getMetadata({
    key: 'YOUR_API_KEY',
    source: ["Ocean's Eight", "Ralph Breaks the Internet", "Pulp Fiction"]
}).then(metadata => {
  // Do stuff with the Array of movies (with metadata)
})

`progress`

Whether or not to show a CLI progress bar while downloading the metadata

Default: true
Type: Boolean

Example

const { getMetadata } = require('movie-metadata')

getMetadata({
    key: 'YOUR_API_KEY',
    source: 'path/to/list/of/movies.json',
    progress: true
}).then(metadata => {
  // Do stuff with the Array of movies (with metadata)
})

This will display a CLI progress bar using the cli-progress module.

`verbose`

Whether or not to run verbosely

Note: This disables progress parameter, if enabled

Default: false
Type: Boolean

Example

const { getMetadata } = require('movie-metadata')

getMetadata({
    key: 'YOUR_API_KEY',
    source: 'path/to/list/of/movies.json',
    verbose: true
}).then(metadata => {
  // Do stuff with the Array of movies (with metadata)
})

This will output each movie title to the console, along with whether or not it was found.

`dest`

Where to save the fetched Array of movie metadata

Note: If set to false, the fetched movie metadata will be returned as a Promise of an Object with two properties fetchedMetadata:[Object] and notFoundMovies:[String].

Default: Same path as source with '-metadata' appended
Type: String|Boolean

Example

const { getMetadata } = require('movie-metadata')

getMetadata({
    key: 'YOUR_API_KEY',
    source: 'path/to/list/of/movies.json',
    dest: false
}).then(metadata => {
  // Do stuff with the Array of movies (with metadata)
})

`notFound`

Where to save the JSON file that holds the movies that were not found on the omdb API server

Note: If set to false, the fetched movie metadata will be returned as a Promise of an Object with two properties fetchedMetadata:[Object] and notFoundMovies:[String].

Default: Same path as source with '-notFound' appended
Type: String|Boolean

Example

const { getMetadata } = require('movie-metadata')

getMetadata({
    key: 'YOUR_API_KEY',
    source: 'path/to/list/of/movies.json',
    notFound: false
}).then(metadata => {
  // Do stuff with the Array of movies (with metadata)
})

`overwrite`

Whether or not to overwrite the source file with the metadata JSON data

Note: If enabled, this disables dest parameter. This is automatically disabled if dest parameter is disabled (false)

Default: false
Type: Boolean

Example

const { getMetadata } = require('movie-metadata')

getMetadata({
    key: 'YOUR_API_KEY',
    source: 'path/to/list/of/movies.json',
    overwrite: true
}).then(metadata => {
  // Do stuff with the Array of movies (with metadata)
})

`splitter`(Not Yet Working)

What character to use to split the source String into an Array

Note: This is only applied if the source parameter is not a JSON file, or is a plain String.

Note: As of version 1.0.3 this feature is not completely working yet. If the source parameter is a file, it must be a JSON file

Default: \n
Type: String

Example

const { getMetadata } = require('movie-metadata')

getMetadata({
    key: 'YOUR_API_KEY',
    source: "Lucy::Se7en::Dead Man's Chest::Ocean's Eleven",
    splitter: '::'
}).then(metadata => {
  // Do stuff with the Array of movies (with metadata)
})

Built With

abort-controller - Smooth API fetch operations
cli-progress - CLI progress bar
command-line-args - Processing command-line arguments
fs-extra - Reading/writing JSON files
lodash - General utilities
node-fetch - Running API calls to omdb
omdb - Open Movie Database (metadata API server)
node-tap - Unit testing (not yet implemented)

Versioning

We use SemVer for versioning.

Authors

Martin Cox - Initial work

License

This project is licensed under the CC BY-NC 4.0 License - see the LICENSE file for details. movie-metadata is not affiliated or endorsed by omdbapi.com in any way. An API Key (free) must be obtained prior to using this module.

Future Additions

Future additions/features for movie-metadata

Name		Name	Last commit message	Last commit date
Latest commit History 32 Commits
.github/ISSUE_TEMPLATE		.github/ISSUE_TEMPLATE
bin		bin
dev		dev
img		img
src		src
tests		tests
.eslintrc		.eslintrc
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
index.js		index.js
metadata.js		metadata.js
package-lock.json		package-lock.json
package.json		package.json

Folders and files

Latest commit

History

Repository files navigation

What Movie Metadata Does

Installing

Usage

CLI Usage

Programmatic usage

API Reference

CLI API

--key|-k

--source|-s

--progress|-p

--verbose|-v

--dest|-d

--notFound|-n

--overwrite|-o

Programmatic API

key

source

progress

verbose

dest

notFound

overwrite

splitter(Not Yet Working)

Built With

Versioning

Authors

License

Future Additions

About

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages

`--key|-k`

`--source|-s`

`--progress|-p`

`--verbose|-v`

`--dest|-d`

`--notFound|-n`

`--overwrite|-o`

`key`

`source`

`progress`

`verbose`

`dest`

`notFound`

`overwrite`

`splitter`(Not Yet Working)

Packages