boxoffice-scraper

A TypeScript library for scraping box office data from Box Office Mojo with caching and export capabilities.

Description

This library allows you to fetch worldwide box office data for specific years from Box Office Mojo. It includes built-in caching to reduce redundant requests and supports exporting data to JSON or CSV formats.

Features

• Fetch box office data by year
• Automatic caching for 1 hour
• Export to JSON or CSV
• TypeScript support with full type definitions

Installation

npm install boxoffice-scraper

Usage

Basic Usage

import { getBoxOfficeData } from 'boxoffice-scraper';

async function getData() {
  const data = await getBoxOfficeData(2023);
  console.log(data.slice(0, 5)); // Get top 5 movies
}

With Export Options

// Export to JSON
await getBoxOfficeData(2023, { saveAs: 'json' });

// Export to CSV with custom path
await getBoxOfficeData(2023, { saveAs: 'csv', filePath: 'my-data.csv' });

API

getBoxOfficeData(year: number, options?: GetDataOptions): Promise<BoxOfficeData[]>

Fetches box office data for the specified year.

Parameters:

• year: The year for which to fetch data
• options (optional): Configuration object with:
  • saveAs: 'json' | 'csv' - Format to save the data
  • filePath: Custom file path (defaults to boxoffice_${year}.${saveAs})

Returns: Promise resolving to an array of BoxOfficeData objects.

BoxOfficeData Interface

interface BoxOfficeData {
  rank: number;
  title: string;
  worldwideGross: string;
  domesticGross: string;
  domesticPercent: string;
  foreignGross: string;
  foreignPercent: string;
  year: number;
}

Development

Building

npm run build

Testing

npm test

Publishing

npm publish

License

ISC

Repository

GitHub Repository

Contributing

Contributions are welcome! Please open an issue or submit a pull request.