🎥 Movier: Lightweight IMDb scraping helpers for movies, series, and celeb data inside your Node.js app 🚀

🌟 Welcome to movier, an IMDb Data Scraping Library!

Note: We recommend not using this package directly in production, as it scrapes IMDB page content. Requests can take a couple of seconds to complete. Instead, use this package to fetch and cache the information in your local database for faster retrieval.

🛠️ Installation

Requires Node.js >= 20.18.1 (we recommend Bun; if you’re using another runtime, make sure it’s at least 20.18.1).

Install movier using your preferred package manager:

Bun:

bun add @valhalladev/movier

Yarn:

yarn add @valhalladev/movier

npm:

npm install @valhalladev/movier --save

🚀 Usage

Import the functions you need:

import {
  getTitleDetailsByName,
  getTitleDetailsByUrl,
  getTitleDetailsByIMDBId,
  getTitleDetailsByFoundedTitleDetails,
  searchTitleByName,
  getPersonDetailsByName,
  getPersonDetailsByUrl,
  getPersonDetailsByIMDBId,
  getPersonDetailsByFoundedPersonDetails,
  searchPersonByName,
  TitleMainType,
} from "@valhalladev/movier";

Or use the default export:

import movier from "@valhalladev/movier";

CommonJS (legacy):

const movier = require("@valhalladev/movier");

Title details (movie/series)

Pull every detail from an IMDB title page—plot, ratings, cast, crew, release info, keywords, images, awards, and more.

// Search and get details by name
const title = await getTitleDetailsByName("interstellar 2014");

// Or get details directly by URL or IMDB ID
await getTitleDetailsByUrl("https://www.imdb.com/title/tt0816692/");
await getTitleDetailsByIMDBId("tt0816692");

// Or use search results
const searchResults = await searchTitleByName("interstellar 2014");
const titleFromSearch = await getTitleDetailsByFoundedTitleDetails(searchResults[0]);

Each call resolves to a structured title object. See the example in examples/results/interstellarTitleResults.json for the full schema.

Search for titles

Search by name and receive match metadata (IMDB url, score, thumbnail) so you can select the correct entry before fetching the full payload.

const results = await searchTitleByName("interstellar 2014");
// Optionally filter by exact match or specific type
const movieResults = await searchTitleByName("interstellar", {
  exactMatch: false,
  specificType: TitleMainType.Movie
});

Results match the shape shown in examples/results/interstellarTitleSearchResults.json.

Person (celebrity) details

Grab bios, birth info, filmography, personal details, and imagery for any celebrity page.

// Search and get details by name
const person = await getPersonDetailsByName("jennifer lawrence");

// Or get details directly by URL or IMDB ID
await getPersonDetailsByUrl("https://www.imdb.com/name/nm2225369/");
await getPersonDetailsByIMDBId("nm2225369");

// Or use search results
const searchResults = await searchPersonByName("jennifer lawrence");
const personFromSearch = await getPersonDetailsByFoundedPersonDetails(searchResults[0]);

Each method resolves to a consistent person object. Reference examples/results/jenniferLawrencePersonResults.json for the payload structure.

Search for people

const results = await searchPersonByName("jennifer lawrence");
// Optionally filter by exact match
const exactResults = await searchPersonByName("jennifer lawrence", {
  exactMatch: true
});

Returns a shortlist of profiles with match scores and URLs (see examples/results/jenniferLawrencePersonSerachResults.json).

🧪 Test

Execute the test suite after installing dependencies:

bun test

🤝 Contributing

We welcome contributions that help movier stay useful and reliable. Before you start work, please review our CONTRIBUTING guide so you understand the workflow, Code of Conduct, and release expectations. Follow the listed steps (fork, branch, commit, push, open a PR) and keep your PR description detailed so reviewers can follow the changes you made.

📜 License

This project is licensed under the MIT License – feel free to fork, adapt, and redistribute with attribution.

🙏 Acknowledgements

• IMDb for the data that powers movier’s lookups
• Zoha for the original movier project and parser work
• Everyone who tests, files issues, or contributes to movier’s continued usefulness

📬 Support & Community

Got questions or need help? Join our Discord server for support and to connect with other bot developers!

💻 Crafted with ❤️ by Valhalla-Development & Zoha

🐛 Spotted an issue? | 💡 Got an idea? | 🤔 Need help?

🔝 Back to Top