yahoo-finance docs

Table of Contents

1. Common Options
2. CLI
3. MCP
4. Modules
5. Util Methods
6. Error Handling
7. Validation
8. Concurrency
9. Upgrading from v1

Common Options

Each API module accepts an optional third argument moduleOpts containing common configuration overrides:

• devel: Test cache/mock control. Can be set to a boolean or a specific string to guide test fixture generation/replay (see the main README.md developer guide).
• fetchOptions: Custom options passed directly to fetch(), e.g., to pass a timeout AbortSignal ({ signal: AbortSignal.timeout(10000) }).
• validateResult: Set to false to skip runtime schema validation for this request. Read the Validation docs first.
• queue: Custom request queue options (concurrency, timeout) for this request. See Concurrency.

const queryOpts = {}; // query options specific to the module

const moduleOpts = {
  devel: boolean | string,
  fetchOptions: {},
  validateResult: boolean,
};

const result = await yahooFinance.module(query, queryOpts, moduleOpts);

Modules

See the list of main modules and their options in the API docs.

There is also the list of "other" modules which are utility modules we provide for convenience but are not a part of the actual Yahoo Finance API.

Error Handling

The modules rely on external services and things can go wrong. Therefore, it's important to wrap your use of this library in try...catch statements, e.g.:

let result;
try {
  result = await yahooFinance.quote(symbol);
} catch (error) {
  // Inspect error and decide what to do; often, you may want to just abort:
  console.warn(
    `Skipping yf.quote("${symbol}"): [${error.name}] ${error.message}`,
  );
  return;
}

doSomethingWith(result); // safe to use in the way you expect

So what can go wrong?

• Network errors: request timeouts, no response, etc.
• HTTP errors: internal errors, etc.
• Missing resources, e.g. asking for fund data for a stock.
• Validation errors.
• Delisted stocks. If a stock gets delisted, a query that worked previously (for a particular symbol) will begin to throw an error. This includes historical (and chart) data from before the delisting occured. This is how Yahoo treats delisted stocks and there is nothing we can do about it.

The library goes to great lengths to ensure that if there are no errors, the result you receive will be in an expected format and structure, that is safe to use, put in your database, perform calculations with, etc (but please do let us know if you come across any edge cases).

There is a list of specific errors at lib/errors.ts, accessible via yahooFinance.errors, but many of these will require further inspection at runtime. For example:

• FailedYahooValidationError - see the Validation section on how to handle these correctly.

• HTTPError - the message property will be the HTTP Response statusText.

• Error - thrown after a "successful" HTTP request that returns JSON with an { error: { name: "ErrorName", description: "string" } } shape, and where we don't have an "ErrorName" class. The message property will be the description.

Example:

import YahooFinance from "yahoo-finance2";
const yahooFinance = new YahooFinance();

let result;
try {
  result = await yahooFinance.quote(symbol);
} catch (error) {
  if (error instanceof yahooFinance.errors.FailedYahooValidationError) {
    // See the validation docs for examples of how to handle this
    // error.result will be a partially validated / coerced result.
  } else if (error instanceof yahooFinance.errors.HTTPError) {
    // Probably you just want to log and skip these
    console.warn(
      `Skipping yf.quote("${symbol}"): [${error.name}] ${error.message}`,
    );
    return;
  } else {
    // Same here
    console.warn(
      `Skipping yf.quote("${symbol}"): [${error.name}] ${error.message}`,
    );
    return;
  }
}

doSomethingWith(result); // safe to use in the way you expect

If you run into any problems with error handling, feel free to open an issue so we can make these docs clearer.

Validation

As per the previous section, if you do receive a result (i.e. if no error is thrown), it should reliably be in the format you expect. As such, every received result is validated against the schema we've developed for each module.

See the Validation docs for more info, including how to continue past validation errors or skip validation entirely, as long as you understand the risks.

Concurrency

See Concurrency Docs.

For request timeouts today, pass an AbortSignal through fetchOptions, either on the client or per request:

const yahooFinance = new YahooFinance({
  fetchOptions: { signal: AbortSignal.timeout(10_000) },
});

await yahooFinance.quote("AAPL", {}, {
  fetchOptions: { signal: AbortSignal.timeout(10_000) },
});

Upgrading from v1

See Upgrading from v1.