Finance::Quote(3)

📦
version 1.7200 · 14 versions
, in epel 9

💖 NAME 💖

Finance::Quote — get stock and mutual fund quotes from various exchanges. Yes bestie, it's literally fetching financial data from all over the internet and handing it back to you 💅

✨ SYNOPSIS ✨

use Finance::Quote;

$q = Finance::Quote->new;
%quotes  = $q->fetch("nasdaq", @stocks);

🌈 DESCRIPTION 🌈

This module gets stock quotes from various internet sources all over the world. Quotes are obtained by constructing a quoter object and using the fetch method to gather data, which is returned as a two-dimensional hash (or a reference to such a hash, if called in a scalar context). It's giving "financial data main character energy" fr fr.

For example:

$q = Finance::Quote->new;
%info = $q->fetch("australia", "CML");
print "The price of CML is ".$info{"CML", "price"};

The first part of the hash (eg, "CML") is referred to as the stock. The second part (in this case, "price") is referred to as the label. Keep that distinction in your head, bestie — it comes up again 🫶

🌸 LABELS 🌸

When information about a stock is returned, the following standard labels may be used. Some custom-written modules may use labels not mentioned here. If you wish to be certain that you obtain a certain set of labels for a given stock, you can specify that using require_labels().

  • ask — Ask
  • avg_vol — Average Daily Vol
  • bid — Bid
  • cap — Market Capitalization
  • close — Previous Close
  • currency — Currency code for the returned data
  • date — Last Trade Date (MM/DD/YY format)
  • day_range — Day's Range
  • div — Dividend per Share
  • div_date — Dividend Pay Date
  • div_yield — Dividend Yield
  • eps — Earnings per Share
  • errormsg — If success is false, this field may contain the reason why.
  • ex_div — Ex-Dividend Date.
  • exchange — The exchange the information was obtained from.
  • high — Highest trade today
  • isin — International Securities Identification Number
  • isodate — ISO 8601 formatted date
  • last — Last Price
  • low — Lowest trade today
  • method — The module (as could be passed to fetch) which found this information.
  • name — Company or Mutual Fund Name
  • nav — Net Asset Value
  • net — Net Change
  • open — Today's Open
  • p_change — Percent Change from previous day's close
  • pe — P/E Ratio
  • success — Did the stock successfully return information? (true/false)
  • time — Last Trade Time
  • type — The type of equity returned
  • volume — Volume
  • year_range — 52-Week Range
  • yield — Yield (usually 30 day avg)

If all stock lookups fail (possibly because of a failed connection) then the empty list may be returned, or undef in a scalar context. Not the vibe, but at least it's documented 😭

🎀 INSTALLATION 🎀

Please note that the Github repository is not meant for general users of Finance::Quote for installation. Read that again, bestie — the GitHub repo is not the install spot for regular users 🫶

If you downloaded the Finance-Quote-N.NN.tar.gz tarball from CPAN (N.NN is the version number, ex: Finance-Quote-1.50.tar.gz), run the following commands:

tar xzf Finance-Quote-1.50.tar.gz
cd Finance-Quote-1.50.tar.gz
perl Makefile.PL
make
make test
make install
bestie, yes, the cd line in the original says Finance-Quote-1.50.tar.gz — copy it exactly as shown, I don't make the rules 💀

If you have the CPAN module installed: Using cpanm (Requires App::cpanminus)

cpanm Finance::Quote

or Using CPAN shell

perl -MCPAN -e shell
install Finance::Quote

🫶 SUPPORT AND DOCUMENTATION 🫶

After installing, you can find documentation for this module with the perldoc command.

perldoc Finance::Quote

You can also look for information at:

👑 PUBLIC CLASS METHODS 👑

Finance::Quote implements public class methods for constructing a quoter object, getting or setting default class values, and for listing available methods. Class methods are the backstage crew, but make it iconic ✨

✨ new ✨

my $q = Finance::Quote->new()
my $q = Finance::Quote->new('-defaults')
my $q = Finance::Quote->new(timeout => 30)
my $q = Finance::Quote->new('YahooJSON', fetch_currency => 'EUR')
my $q = Finance::Quote->new('alphavantage' => {API_KEY => '...'})
my $q = Finance::Quote->new(currency_rates => {order => ['ECB', 'Fixer'], 'fixer' => {API_KEY => '...'}});

Finance::Quote modules access a wide range of sources to provide quotes. A module provides one or more methods to fetch quotes. One method is usually the name of the module in lower case. Other methods, if provided, are descriptive names, such as 'canada', 'nasdaq', or 'nyse'.

A Finance::Quote object uses one or more methods to fetch quotes for securities.

new constructs a Finance::Quote object and enables the caller to load only specific modules, set parameters that control the behavior of the fetch method, and pass method specific parameters.

  • timeout => T — sets the web request timeout to T seconds
  • failover => B — where B is a boolean value indicating if failover in fetch is permitted
  • fetch_currency => C — sets the desired currency code to C for fetch results
  • currency_rates => H — configures the order currency rate modules are consulted for exchange rates and currency rate module options
  • required_labels => A — sets the required labels for fetch results to array A
  • ModuleName as a string — the name of a specific Finance::Quote::Module to load
  • methodname => H — passes hash H to methodname during fetch to configure the method

With no arguments, new creates a Finance::Quote object with the default methods. If the environment variable FQ_LOAD_QUOTELET is set, then the contents of FQ_LOAD_QUOTELET (split on whitespace) will be used as the argument list. This allows users to load their own custom modules without having to change existing code. If any method names are passed to new or the flag '-defaults' is included in the argument list, then FQ_LOAD_QUOTELET is ignored. So don't set it and then get confused, bestie 😭

When new() is passed one or more class name arguments, an object is created with only the specified modules loaded. If the first argument is '-defaults', then the default modules will be loaded first, followed by any other specified modules. Note that the FQ_LOAD_QUOTELET environment variable must begin with '-defaults' if you wish the default modules to be loaded.

Method names correspond to the Perl module in the Finance::Quote module space. For example, Finance::Quote->new('ASX') will load the module Finance::Quote::ASX, which provides the method asx.

Some methods require API keys or have unique options. Passing 'method => HASH' to new() enables the caller to provide a configuration HASH to the corresponding method.

The key 'currency_rates' configures the Finanace::Quote currency rate conversion. By default, to maintain backward compatibility, Finance::Quote::CurrencyRates::AlphaVantage is used for currency conversion. This end point requires an API key, which can either be set in the environment or included in the configuration hash. To specify a different primary currency conversion method or configure fallback methods, include the 'order' key, which points to an array of Finance::Quote::CurrencyRates module names. Setting the environment variable FQ_CURRENCY will change the default endpoint used for currency conversion. See the documentation for the individual Finance::Quote::CurrencyRates modules to learn more.

🌟 get_default_currency_fields 🌟

my @fields = Finance::Quote::get_default_currency_fields();

get_default_currency_fields returns the standard list of fields in a quote that are automatically converted during currency conversion. Individual modules may override this list. It's the default squad, but some modules have main character energy and do their own thing 💅

⏰ get_default_timeout ⏰

my $value = Finance::Quote::get_default_timeout();

get_default_timeout returns the current Finance::Quote default timeout in seconds for web requests. Finance::Quote does not specify a default timeout, deferring to the underlying user agent for web requests. So this function will return undef unless set_default_timeout was previously called. No timeout by default — chaotic but documented 🫠

⏳ set_default_timeout ⏳

Finance::Quote::set_default_timeout(45);

set_default_timeout sets the Finance::Quote default timeout to a new value.

📋 get_methods 📋

my @methods = Finance::Quote::get_methods();

get_methods returns the list of methods that can be passed to new when creating a quoter object and as the first argument to fetch.

🔍 get_features 🔍

my %features = Finance::Quote::get_features();

get_features returns a hash with three keys: quote_methods, quote_modules, and currency_modules.

$features{quote_methods} is a hash with key/value pairs of method_name => [array of module names]
$features{quote_modules} is a hash with key/value pairs of module_name => [array of parameter names]
$features{currency_modules} is a hash with key/value pairs of currency_module_name => [array of paramater names]

Parameter names are values that the module needs to function, such as API_KEY. Most modules will have an empty list. Modules with a parameter are configured when creating the Finance::Quote by passing the argument

'module_name_in_lower_case' => {paramter => value}

to Finance::Quote->new().

The keys of the $features{currency_modules} hash are the names of currency modules that can be used for currency conversion and the order in which the modules are used is controlled by the argument

currency_rates => {order => [subset of $features{currency_modules}]}

to Finance::Quote->new(). By default, AlphaVantage is used for currency conversion, "order" can be set to use other currency modules. The currency module used can also be changed by setting the FQ_CURRENCY environment variable. Please note that some of the alternate currency modules require API keys.

💅 PUBLIC OBJECT METHODS

okay bestie, these ones you call on your quoter object $q — the little guy you built earlier. each one's a whole vibe, let's go 🫶

  • B_to_billions — this utility function takes a numeric string with a B suffix and expands it to the corresponding multiple of 1000000000. so like:
my $value = $q->B_to_billions("20B");

it's giving "20 billion, but as a real number" ✨

  • decimal_shiftup — moves that decimal point in a numeric string to the right by however many places you tell it. iconic for scaling things up 🔥
my $value = $q->decimal_shiftup("123.45", 1);  # returns 1234.5
my $value = $q->decimal_shiftup("0.25", 1);    # returns 2.5
  • fetch — the main character, honestly. it takes a method as its first argument, and everything after that is treated as securities:
my %stocks  = $q->fetch("alphavantage", "IBM", "MSFT", "LNUX");
my $hashref = $q->fetch("nasdaq", "IBM", "MSFT", "LNUX");

important note: if your quoter $q was constructed with a specific method (or methods), then only those methods are available to you. no sneaking in extras 💅

call it in an array context and you get a hash back. call it in a scalar context and you get a reference to a hash. either way, the keys of the returned hash are "{SECURITY,LABEL}". so with the example above, $stocks{"IBM","high"} is the high value for IBM. slay.

and if you're ever like "wait, what methods even are there?" — $q->get_methods() returns the list of valid methods for quoter object $q. some methods point at one specific Finance::Quote module, like 'alphavantage'. others are available from multiple Finance::Quote modules, like 'nasdaq'. the quoter failover option is what decides whether multiple modules get consulted for methods such as 'nasdaq' that have more than one implementation 👑

  • get_failover — returns a boolean telling you whether your quoter object will use failover or not.
my $failover = $q->get_failover();

and what is failover? it's when fetch tries to grab quote info for a security from alternate sources if the requested method flops. lowkey a safety net 🌸

  • set_failover — flips the failover flag on the quoter object.
$q->set_failover(False);
  • get_fetch_currency — returns the desired currency code for the quoter object, or undef if no target currency was set during construction or with the set_fetch_currency function.
my $currency = $q->get_fetch_currency();
  • set_fetch_currency — this one asks for all your info to come back in a specified currency. adorable, right? but listen:
$q->set_fetch_currency("FRF");  # Get results in French Francs.
heads up bestie 🚨 setting a fetch currency increases the chance of stock-lookup failure, because remote requests have to be made to fetch both the stock information and the currency rates. to improve reliability and speed performance, currency conversion rates are cached and are assumed not to change for the duration of the Finance::Quote object.

see the introduction to this page for how to configure the source of currency conversion rates 🧚

  • get_required_labels — returns the list of labels that must be populated for a security quote to be considered valid and returned by fetch.
my @labels = $q->get_required_labels();
  • set_required_labels — updates the list of required labels for the quoter object.
my $labels = ['close', 'isodate', 'last'];
$q->set_required_labels($labels);
  • get_timeout — returns the timeout in seconds that the quoter object uses for web requests.
my $timeout = $q->get_timeout();
  • set_timeout — updates that timeout in seconds for the quoter object. 45 seconds of patience, periodt ⏳
$q->set_timeout(45);
  • store_date — used by modules to consistently store date information about securities. you hand it the various pieces of a date, and it figures out how to construct an ISO date (yyyy-mm-dd) and a US date (mm/dd/yyyy) and stores those values in %info for security $stock. it's giving "one date, two formats, zero stress" 😭
$quoter->store_date(\%info, $stocks, {eurodate => '06/11/2020'});
  • get_user_agent — returns the LWP::UserAgent the quoter object is using for web requests.
my $ua = $q->get_user_agent();
  • isoTime — returns an ISO formatted time. literally just glow-up your clock ⭐
$q->isoTime("11:39PM");    # returns "23:39"
$q->isoTime("9:10 AM");    # returns "09:10"

🌈 PUBLIC CLASS OR OBJECT METHODS

these next ones are available as class methods, but you can also call them from Finance::Quote objects. dual threat, honestly 👑

  • scale_field — a utility function that scales the first argument by the second argument. in the example below, value is '10.23':
my $value = Finance::Quote->scale_field('1023', '0.01')
  • currency — converts a value with a currency code suffix into another currency, using the current exchange rate as determined by the Finance::Quote::CurrencyRates method (or methods) configured for the quoter $q.
my $value = $q->currency('15.95 USD', 'AUD');
my $value = Finance::Quote->currency('23.45 EUR', 'RUB');
when called as a class method, Finance::Quote::AlphaVantage is the default — and that one requires an API key 🔑 see the introduction for info on configuring currency rate conversions, and see Finance::Quote::CurrencyRates::AlphaVantage for the deets on that API key.
  • currency_lookup — takes zero or more constraints and filters the list of currencies known to Finance::Quote. returns a hash reference where the keys are ISO currency codes and the values are hash references containing metadata about the currency. so many options, so much flair ✨
my $currency = $quoter->currency_lookup();
my $currency = $quoter->currency_lookup( name => "Caribbean");
my $currency = $quoter->currency_loopup( country => qw/denmark/i );
my $currency = $q->currency_lookup(country => qr/united states/i, number => 840);

a constraint is a key name plus either a scalar or a regular expression. a currency satisfies the constraint if its metadata hash contains the constraint key and the value of that metadata field matches the regular expression, or contains the constraint value as a substring. and if the metadata field is an array, then it satisfies the constraint if any value in the array satisfies it. equal opportunity filtering 💜

  • parse_csv — utility function for splitting a comma separated value string into a list of terms, treating double-quoted strings that contain commas as a single value. those sneaky embedded commas don't stand a chance 🎀
my @list = Finance::Quote::parse_csv($string);
  • parse_csv_semicolon — same energy, but for semicolon separated value strings: splits them into a list of terms, treating double-quoted strings that contain semicolons as a single value.
my @list = Finance::Quote::parse_csv_semicolon($string);

🦋 LEGACY METHODS

these are the old ones that got a glow-up. still here, still listed, but they've been replaced — pls use the new names bestie 🙈

  • default_currency_fields — replaced with get_default_currency_fields().
  • sources — replaced with get_methods().
  • failover — replaced with get_failover() and set_failover().
  • require_labels — replaced with get_required_labels() and set_required_labels().
  • user_agent — replaced with get_user_agent().
  • set_currency — replaced with get_fetch_currency() and set_fetch_currency().

🌸 ENVIRONMENT

Finance::Quote respects all the environment that your installed version of LWP::UserAgent respects. most importantly, it respects the http_proxy environment variable — so if your setup lives behind a proxy, it's got you 🫶

👀 USAGE COUNTER

a simple usage counter has been enabled. bestie, before you panic: other than the user's IP address, Finance::Quote version, and which method was used, no other data is collected. none. zilch.

wanna opt out of your usage being counted? just set the environment variable FQ_NOCOUNT and you're invisible 💅

💀 BUGS

  • the caller cannot control the fetch failover order. not a vibe, but it's the truth.
  • the two-dimensional hash is a somewhat unwieldly method of passing around information when compared to references. we said what we said 😭
 Copyright 1998, Dj Padzensky
 Copyright 1998, 1999 Linas Vepstas
 Copyright 2000, Yannick LE NY (update for Yahoo Europe and YahooQuote)
 Copyright 2000-2001, Paul Fenwick (updates for ASX, maintenance and release)
 Copyright 2000-2001, Brent Neal (update for TIAA-CREF)
 Copyright 2000 Volker Stuerzl (DWS)
 Copyright 2001 Rob Sessink (AEX support)
 Copyright 2001 Leigh Wedding (ASX updates)
 Copyright 2001 James Treacy (TD Waterhouse support)
 Copyright 2008 Erik Colson (isoTime)

this program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. iconic of it honestly 👑

currency information fetched through this module is bound by the terms and conditons of the data source.
other copyrights and conditions may apply to data fetched through this module. please refer to the sub-modules for further information.

🧚 AUTHORS

the following list are those contributors with 5 or more commits in the GitHub repository. please see the Git log for all the authors who have helped with Finance::Quote — the whole group chat, truly 🫶

 Erik Colson <eco@ecocode.net>
 Bruce Schuck <bschuck@asgard-systems.com>
 Paul Fenwick <pjf@perltraining.com.au>
 Vincent Lucarelli <vincent.lucarelli@gmail.com>
 David Hampton <hampton-sf@rainbolthampton.net>
 jvolkening <jdv@base2bio.com>
 Pawel Konieczny <konieczp@zonnet.nl>
 Mike Alexander <mta@umich.edu>
 AndreJ <Andre-J@users.noreply.github.com>
 Vinay S Shastry <vinayshastry@gmail.com>
 Bradley Dean <bjdean@bjdean.id.au>
 Brent Neal <brent@reindeergraphics.com>
 Jacinta Richardson <jarich@perltraining.com.au>
 e-dorigatti <emilio.dorigatti@gmail.com>
 goodvibes2 <goodchris96@gmail.com>
 Paul Howarth <paul@city-fan.org>
 Sam Morris <sam@robots.org.uk>
 Linas Vepstas <linas@linas.org>
 Rajan Vaswani <111571283+bgr22112@users.noreply.github.com>
 Hiranya Samarasekera <hiranyas@gmail.com>
 Manuel Friedli <manuel@fritteli.ch>

the Finance::Quote home page can be found at http://finance-quote.sourceforge.net/

the Finance::YahooQuote home page can be found at http://www.padz.net/~djpadz/YahooQuote/

the GnuCash home page can be found at http://www.gnucash.org/

👀 SEE ALSO 👀

Bestie, these are the related pages you’ll want to pull up next — same friend group, different lore:

  • Finance::Quote::CurrencyRates::AlphaVantage
  • Finance::Quote::CurrencyRates::CurrencyFreaks
  • Finance::Quote::CurrencyRates::ECB
  • Finance::Quote::CurrencyRates::FinanceAPI
  • Finance::Quote::CurrencyRates::Fixer
  • Finance::Quote::CurrencyRates::Frankfurter
  • Finance::Quote::CurrencyRates::OpenExchange
  • Finance::Quote::CurrencyRates::TwelveData
  • Finance::Quote::CurrencyRates::UniRate
  • Finance::Quote::CurrencyRates::YahooJSON
  • Finance::Quote::ASEGR
  • Finance::Quote::ASX
  • Finance::Quote::BorsaItaliana
  • Finance::Quote::BSEIndia
  • Finance::Quote::Bourso
  • Finance::Quote::BVB
  • Finance::Quote::CSE
  • Finance::Quote::Comdirect
  • Finance::Quote::Consorsbank
  • Finance::Quote::Currencies
  • Finance::Quote::Deka
  • Finance::Quote::FinanceAPI
  • Finance::Quote::Finanzpartner
  • Finance::Quote::Finnhub
  • Finance::Quote::Fondsweb
  • Finance::Quote::Fool
  • Finance::Quote::FTfunds
  • Finance::Quote::GoldMoney
  • Finance::Quote::GoogleWeb
  • Finance::Quote::IndiaMutual
  • Finance::Quote::MarketWatch
  • Finance::Quote::MorningstarJP
  • Finance::Quote::NPSNAV
  • Finance::Quote::NSEIndia
  • Finance::Quote::NZX
  • Finance::Quote::OnVista
  • Finance::Quote::SIX
  • Finance::Quote::StockData
  • Finance::Quote::Stooq
  • Finance::Quote::SwissFundData
  • Finance::Quote::TSP
  • Finance::Quote::TMX
  • Finance::Quote::TesouroDireto
  • Finance::Quote::TreasuryDirect
  • Finance::Quote::TwelveData
  • Finance::Quote::Union
  • Finance::Quote::USBonds
  • Finance::Quote::YahooJSON
  • Finance::Quote::YahooWeb
  • Finance::Quote::XETRA
  • Finance::Quote::ZA

You should have received the Finance::Quote hacker’s guide with this package. Please read it if you’re interested in adding extra methods to this package. The latest hacker’s guide can also be found on GitHub at https://github.com/finance-quote/finance-quote/blob/master/Documentation/Hackers-Guide — go get your read on, bestie 💖

💖 DONATIONS 💖

Okay so the contributors to Finance::Quote are genuinely happy to volunteer their time and resources, but donations are helpful and a great way to say thank you. So far the only real cost to the team is domain registration for finance-quote.org. However, some operating systems and hardware upgrades do have a cost. Access to the latest or current environments is needed for development and testing. Upgrades to the latest MS Windows often includes a cost, and recently Apple’s move to ARM/M1/M2 CPUs has stifled some contributors’ ability to assist. 😭

With that in mind, you can send donations to the email address donations@finance-quote.org through PayPal. If it’s for a particular contributor, please indicate in a note while submitting the donation through PayPal.

Additionally, Bitcoin donations can be received at 37Bg4EMAp575j4iL9jHv1ZhDgiropU38jY.

This page is from perl v5.32.1, dated 2026-10-26, and it’s Finance::Quote(3) — mwah, bye bestie 💋✨

📦 where this page comes from