Yahoo Finance 2 API Client

3.14.0 · active · verified Tue Apr 21

yahoo-finance2 is an actively maintained JavaScript and TypeScript client library for accessing the unofficial Yahoo Finance API. Currently at stable version 3.14.0, it provides programmatic access to various financial data points including historical prices, real-time quotes, company fundamentals, and search capabilities. The project maintains a regular release cadence, with multiple minor and patch updates occurring monthly, ensuring responsiveness to changes in Yahoo Finance's underlying API. Key differentiators include its comprehensive TypeScript support, broad runtime compatibility (Node.js v20+, Bun, Deno, Cloudflare Workers), and a command-line interface for quick data retrieval. As an unofficial API client, it does not come with guarantees from Yahoo Inc., emphasizing its community-driven nature and the importance of using it at one's own risk for financial applications.

Common errors

```
TypeError: YahooFinance is not a constructor
```
cause Attempting to call `require("yahoo-finance2")()` directly without accessing the `.default` export in CommonJS, or incorrect ESM default import syntax.

fix For CommonJS, use `const YahooFinance = require("yahoo-finance2").default;`. For ESM, ensure `import YahooFinance from "yahoo-finance2";` is used for the class, or `import { someFunction } from "yahoo-finance2";` for named exports.
```
Failed to fetch data from Yahoo Finance API (status 401/403) or receiving empty/malformed responses for valid requests.
```
cause The unofficial Yahoo Finance API can change endpoints or block requests that appear automated, sometimes due to an outdated or problematic `User-Agent` header. This was specifically addressed in v3.11.1.

fix Ensure you are on the latest stable version of `yahoo-finance2` (>=3.11.1). If issues persist, consider implementing retry mechanisms, rate-limiting, or explicitly setting `fetchOptions.userAgent` if the default is causing problems.
```
Property 'typeDisp' does not exist on type 'SearchQuote'.
```
cause A change in the Yahoo API backend affected how `typeDisp` (display type for search results) was returned, leading to inconsistent casing (`typeDisp` vs `TypeDisp`). This was patched in v3.13.2.

fix Upgrade to `yahoo-finance2@^3.13.2` or later to ensure correct processing of search results and access to the `typeDisp` property.

Warnings

breaking Version 3 introduced significant breaking changes from v2, including a new class-based API design and updated import paths. Direct migration without consulting the UPGRADING.md guide is not recommended.
Fix: Consult the `UPGRADING.md` document in the repository for detailed migration steps from v2 to v3. Update import statements and API call patterns as necessary.
breaking The project repository was renamed from `node-yahoo-finance2` to `yahoo-finance2`, and default branch names changed (e.g., `master` to `main`). While this primarily affects Git workflows, it's crucial for correct contribution and tracking.
Fix: Update your local Git remote URLs and branch tracking. Refer to `UPGRADING.md#dev` for specific `git` commands to update your repository clone.
gotcha This library interacts with the unofficial Yahoo Finance API. Yahoo Inc. does not provide an official API, and therefore, service availability, API consistency, and data accuracy are not guaranteed. Use this package at your own risk for any financial decision-making.
Fix: Implement robust error handling, consider rate-limiting, and validate data against other sources if using for critical applications. Be prepared for potential API changes that may require library updates.
gotcha The library explicitly requires Node.js version 20 or higher. Older Node.js versions are not supported and may lead to unexpected errors or stability issues.
Fix: Ensure your Node.js environment is updated to version 20.0.0 or newer. Check the `engines.node` field in `package.json` for current requirements.

Install

npm install yahoo-finance2 npm
yarn add yahoo-finance2 yarn
pnpm add yahoo-finance2 pnpm

Imports

YahooFinance
wrong:
```
import { YahooFinance } from 'yahoo-finance2';
```
correct:
```
import YahooFinance from 'yahoo-finance2';
```
The primary class is exported as the default export. Use this for creating an instance with shared configuration.
quote
wrong:
```
import YahooFinance from 'yahoo-finance2'; const quote = new YahooFinance().quote;
```
correct:
```
import { quote } from 'yahoo-finance2';
```
Individual API functions like `quote`, `historical`, `search`, etc., are also exported as named exports for direct, stateless use.
YahooFinance (CommonJS)
wrong:
```
const YahooFinance = require('yahoo-finance2');
```
correct:
```
const YahooFinance = require('yahoo-finance2').default;
```
In CommonJS environments, the default export of an ESM module is accessed via the `.default` property.

Quickstart

Demonstrates instantiating the YahooFinance client and using both instance methods (search) and directly imported functions (quote, historical) to fetch financial data.

import YahooFinance, { quote, historical } from 'yahoo-finance2';

async function runFinanceExamples() {
  // Option 1: Using the default class export for a client instance
  const yahooFinance = new YahooFinance();
  console.log('--- Searching for Apple ---');
  const searchResults = await yahooFinance.search('Apple');
  console.log('Top search result:', searchResults.quotes[0]?.symbol, searchResults.quotes[0]?.longname);

  // Option 2: Using named exports directly for individual functions (stateless)
  console.log('\n--- Getting Apple (AAPL) current quote ---');
  const aaplQuote = await quote('AAPL');
  const { regularMarketPrice: price, currency } = aaplQuote;
  console.log(`Apple (AAPL) current price: ${price} ${currency}`);

  console.log('\n--- Getting historical data for Microsoft (MSFT) ---');
  const msftHistorical = await historical('MSFT', {
    period1: '2025-01-01',
    period2: '2025-01-07',
    interval: '1d'
  });
  console.log(`Historical data for MSFT (2025-01-01 to 2025-01-07):`, msftHistorical.map(d => ({ date: d.date.toISOString().split('T')[0], close: d.close })));
}

runFinanceExamples().catch(console.error);

view raw JSON →