1Finance::Quote(3) User Contributed Perl Documentation Finance::Quote(3)
2
6 Finance::Quote - Get stock and mutual fund quotes from various
7 exchanges
8
10 use Finance::Quote;
11 $q = Finance::Quote->new;
13 %quotes = $q->fetch("nasdaq", @stocks);
14
16 This module gets stock quotes from various internet sources all over
17 the world. Quotes are obtained by constructing a quoter object and
18 using the fetch method to gather data, which is returned as a two-
19 dimensional hash (or a reference to such a hash, if called in a scalar
20 context). For example:
21 $q = Finance::Quote->new;
23 %info = $q->fetch("australia", "CML");
24 print "The price of CML is ".$info{"CML", "price"};
25 The first part of the hash (eg, "CML") is referred to as the stock.
27 The second part (in this case, "price") is referred to as the label.
28 LABELS
30 When information about a stock is returned, the following standard
31 labels may be used. Some custom-written modules may use labels not
32 mentioned here. If you wish to be certain that you obtain a certain
33 set of labels for a given stock, you can specify that using
34 require_labels().
35 ask Ask
37 avg_vol Average Daily Vol
38 bid Bid
39 cap Market Capitalization
40 close Previous Close
41 currency Currency code for the returned data
42 date Last Trade Date (MM/DD/YY format)
43 day_range Day's Range
44 div Dividend per Share
45 div_date Dividend Pay Date
46 div_yield Dividend Yield
47 eps Earnings per Share
48 errormsg If success is false, this field may contain the reason why.
49 ex_div Ex-Dividend Date.
50 exchange The exchange the information was obtained from.
51 high Highest trade today
52 isin International Securities Identification Number
53 isodate ISO 8601 formatted date
54 last Last Price
55 low Lowest trade today
56 method The module (as could be passed to fetch) which found this information.
57 name Company or Mutual Fund Name
58 nav Net Asset Value
59 net Net Change
60 open Today's Open
61 p_change Percent Change from previous day's close
62 pe P/E Ratio
63 success Did the stock successfully return information? (true/false)
64 time Last Trade Time
65 type The type of equity returned
66 volume Volume
67 year_range 52-Week Range
68 yield Yield (usually 30 day avg)
69 If all stock lookups fail (possibly because of a failed connection)
71 then the empty list may be returned, or undef in a scalar context.
72
74 Please note that the Github repository is not meant for general users
75 of Finance::Quote for installation.
76 If you downloaded the Finance-Quote-N.NN.tar.gz tarball from CPAN (N.NN
78 is the version number, ex: Finance-Quote-1.50.tar.gz), run the
79 following commands:
80 tar xzf Finance-Quote-1.50.tar.gz
82 cd Finance-Quote-1.50.tar.gz
83 perl Makefile.PL
84 make
85 make test
86 make install
87 If you have the CPAN module installed: Using cpanm (Requires
89 App::cpanminus)
90 cpanm Finance::Quote
92 or Using CPAN shell
94 perl -MCPAN -e shell
96 install Finance::Quote
97
99 After installing, you can find documentation for this module with the
100 perldoc command.
101 perldoc Finance::Quote
103 You can also look for information at:
105 Finance::Quote GitHub project
107 https://github.com/finance-quote/finance-quote
108 Search CPAN
110 http://search.cpan.org/dist/Finance-Quote
111 The Finance::Quote home page
113 http://finance-quote.sourceforge.net/
114 The Finance::YahooQuote home page
116 http://www.padz.net/~djpadz/YahooQuote/
117 The GnuCash home page
119 http://www.gnucash.org/
120
122 Finance::Quote implements public class methods for constructing a
123 quoter object, getting or setting default class values, and for listing
124 available methods.
125 new
127 my $q = Finance::Quote->new()
128 my $q = Finance::Quote->new('-defaults')
129 my $q = Finance::Quote->new('AEX', 'Fool')
130 my $q = Finance::Quote->new(timeout => 30)
131 my $q = Finance::Quote->new('YahooJSON', fetch_currency => 'EUR')
132 my $q = Finance::Quote->new('alphavantage' => {API_KEY => '...'})
133 my $q = Finance::Quote->new('IEXCloud', 'iexcloud' => {API_KEY => '...'});
134 my $q = Finance::Quote->new(currency_rates => {order => ['ECB', 'Fixer'], 'fixer' => {API_KEY => '...'}});
135 Finance::Quote modules access a wide range of sources to provide
137 quotes. A module provides one or more methods to fetch quotes. One
138 method is usually the name of the module in lower case. Other methods,
139 if provided, are descriptive names, such as 'canada', 'nasdaq', or
140 'nyse'.
141 A Finance::Quote object uses one or more methods to fetch quotes for
143 securities.
144 "new" constructs a Finance::Quote object and enables the caller to load
146 only specific modules, set parameters that control the behavior of the
147 fetch method, and pass method specific parameters.
148 "timeout =" T> sets the web request timeout to "T" seconds
150 "failover =" B> where "B" is a boolean value indicating if failover in
151 fetch is permitted
152 "fetch_currency =" C> sets the desired currency code to "C" for fetch
153 results
154 "currency_rates =" H> configures the order currency rate modules are
155 consulted for exchange rates and currency rate module options
156 "required_labels =" A> sets the required labels for fetch results to
157 array "A"
158 "<ModuleName"> as a string is the name of a specific
159 Finance::Quote::Module to load
160 "<methodname" => H> passes hash "H" to methodname during fetch to
161 configure the method
162 With no arguments, "new" creates a Finance::Quote object with the
164 default methods. If the environment variable FQ_LOAD_QUOTELET is set,
165 then the contents of FQ_LOAD_QUOTELET (split on whitespace) will be
166 used as the argument list. This allows users to load their own custom
167 modules without having to change existing code. If any method names are
168 passed to "new" or the flag '-defaults' is included in the argument
169 list, then FQ_LOAD_QUOTELET is ignored.
170 When new() is passed one or more class name arguments, an object is
172 created with only the specified modules loaded. If the first argument
173 is '-defaults', then the default modules will be loaded first, followed
174 by any other specified modules. Note that the FQ_LOAD_QUOTELET
175 environment variable must begin with '-defaults' if you wish the
176 default modules to be loaded.
177 Method names correspond to the Perl module in the Finance::Quote module
179 space. For example, "Finance::Quote-"new('ASX')> will load the module
180 Finance::Quote::ASX, which provides the method "asx".
181 Some methods require API keys or have unique options. Passing 'method
183 => HASH' to new() enables the caller to provide a configuration HASH to
184 the corresponding method.
185 The key 'currency_rates' configures the Finanace::Quote currency rate
187 conversion. By default, to maintain backward compatibility,
188 Finance::Quote::CurrencyRates::AlphaVantage is used for currency
189 conversion. This end point requires an API key, which can either be
190 set in the environment or included in the configuration hash. To
191 specify a different primary currency conversion method or configure
192 fallback methods, include the 'order' key, which points to an array of
193 Finance::Quote::CurrencyRates module names. Setting the environment
194 variable FQ_CURRENCY will change the default endpoint used for currency
195 conversion. See the documentation for the individual
196 Finance::Quote::CurrencyRates to learn more.
197 get_default_currency_fields
199 my @fields = Finance::Quote::get_default_currency_fields();
200 "get_default_currency_fields" returns the standard list of fields in a
202 quote that are automatically converted during currency conversion.
203 Individual modules may override this list.
204 get_default_timeout
206 my $value = Finance::Quote::get_default_timeout();
207 "get_default_timeout" returns the current Finance::Quote default
209 timeout in seconds for web requests. Finance::Quote does not specify a
210 default timeout, deferring to the underlying user agent for web
211 requests. So this function will return undef unless
212 "set_default_timeout" was previously called.
213 set_default_timeout
215 Finance::Quote::set_default_timeout(45);
216 "set_default_timeout" sets the Finance::Quote default timeout to a new
218 value.
219 get_methods
221 my @methods = Finance::Quote::get_methods();
222 "get_methods" returns the list of methods that can be passed to "new"
224 when creating a quoter object and as the first argument to "fetch".
225 get_features
227 my %features = Finance::Quote::get_features();
228 "get_features" returns a hash with three keys: quote_methods,
230 quote_modules, and currency_modules.
231 $features{quote_methods} is a hash with key/value pairs of method_name => [array of module names]
233 $features{quote_modules} is a hash with key/value pairs of module_name => [array of parameter names]
234 $features{currency_modules} is a hash with key/value pairs of currency_module_name => [array of paramater names]
235 Parameter names are values that the module needs to function, such as
237 API_KEY. Most modules will have an empty list. Modules with a
238 parameter are configured when creating the Finance::Quote by passing
239 the argument
240 'module_name_in_lower_case' => {paramter => value}
242 to Finance::Quote->new().
244 The keys of the $features{currency_modules} hash are the names of
246 currency modules that can be used for currency conversion and the order
247 in which the modules are used is controlled by the argument
248 currency_rates => {order => [subset of $features{currency_modules}]}
250 to Finance::Quote->new(). By default, only AlphaVantage in used for
252 currency conversion, so "order" must be set to use other currency
253 modules.
254
256 B_to_billions
257 my $value = $q->B_to_billions("20B");
258 "B_to_billions" is a utility function that expands a numeric string
260 with a "B" suffix to the corresponding multiple of 1000000000.
261 decimal_shiftup
263 my $value = $q->decimal_shiftup("123.45", 1); # returns 1234.5
264 my $value = $q->decimal_shiftup("0.25", 1); # returns 2.5
265 "decimal_shiftup" moves a the decimal point in a numeric string the
267 specified number of places to the right.
268 fetch
270 my %stocks = $q->fetch("alphavantage", "IBM", "MSFT", "LNUX");
271 my $hashref = $q->fetch("nasdaq", "IBM", "MSFT", "LNUX");
272 "fetch" takes a method as its first argument and the remaining
274 arguments are treated as securities. If the quoter $q was constructed
275 with a specific method or methods, then only those methods are
276 available.
277 When called in an array context, a hash is returned. In a scalar
279 context, a reference to a hash will be returned. The keys for the
280 returned hash are "{SECURITY,LABEL}". For the above example call,
281 $stocks{"IBM","high"} is the high value for IBM.
282 $q->get_methods() returns the list of valid methods for quoter object
284 $q. Some methods specify a specific Finance::Quote module, such as
285 'alphavantage'. Other methods are available from multiple
286 Finance::Quote modules, such as 'nasdaq'. The quoter failover over
287 option determines if multiple modules are consulted for methods such as
288 'nasdaq' that more than one implementation.
289 get_failover
291 my $failover = $q->get_failover();
292 Failover is when the "fetch" method attempts to retrieve quote
294 information for a security from alternate sources when the requested
295 method fails. "get_failover" returns a boolean value indicating if the
296 quoter object will use failover or not.
297 set_failover
299 $q->set_failover(False);
300 "set_failover" sets the failover flag on the quoter object.
302 get_fetch_currency
304 my $currency = $q->get_fetch_currency();
305 "get_fetch_currency" returns either the desired currency code for the
307 quoter object or undef if no target currency was set during
308 construction or with the "set_fetch_currency" function.
309 set_fetch_currency
311 $q->set_fetch_currency("FRF"); # Get results in French Francs.
312 "set_fetch_currency" method is used to request that all information be
314 returned in the specified currency. Note that this increases the
315 chance stock-lookup failure, as remote requests must be made to fetch
316 both the stock information and the currency rates. In order to improve
317 reliability and speed performance, currency conversion rates are cached
318 and are assumed not to change for the duration of the Finance::Quote
319 object.
320 See the introduction to this page for information on how to configure
322 the source of currency conversion rates.
323 get_required_labels
325 my @labels = $q->get_required_labels();
326 "get_required_labels" returns the list of labels that must be populated
328 for a security quote to be considered valid and returned by "fetch".
329 set_required_labels
331 my $labels = ['close', 'isodate', 'last'];
332 $q->set_required_labels($labels);
333 "set_required_labels" updates the list of required labels for the
335 quoter object.
336 get_timeout
338 my $timeout = $q->get_timeout();
339 "get_timeout" returns the timeout in seconds the quoter object is using
341 for web requests.
342 set_timeout
344 $q->set_timeout(45);
345 "set_timeout" updated the timeout in seconds for the quoter object.
347 store_date
349 $quoter->store_date(\%info, $stocks, {eurodate => '06/11/2020'});
350 "store_date" is used by modules to consistent store date information
352 about securities. Given the various pieces of a date, this function
353 figures out how to construct a ISO date (yyyy-mm-dd) and US date
354 (mm/dd/yyyy) and stores those values in %info for security $stock.
355 get_user_agent
357 my $ua = $q->get_user_agent();
358 "get_user_agent" returns the LWP::UserAgent the quoter object is using
360 for web requests.
361 isoTime
363 $q->isoTime("11:39PM"); # returns "23:39"
364 $q->isoTime("9:10 AM"); # returns "09:10"
365 "isoTime" returns an ISO formatted time.
367
369 The following methods are available as class methods, but can also be
370 called from Finance::Quote objects.
371 scale_field
373 my $value = Finance::Quote->scale_field('1023', '0.01')
374 "scale_field" is a utility function that scales the first argument by
376 the second argument. In the above example, "value" is '10.23'.
377 currency
379 my $value = $q->currency('15.95 USD', 'AUD');
380 my $value = Finance::Quote->currency('23.45 EUR', 'RUB');
381 "currency" converts a value with a currency code suffix to another
383 currency using the current exchange rate as determined by the
384 Finance::Quote::CurrencyRates method or methods configured for the
385 quoter $q. When called as a class method, only
386 Finance::Quote::AlphaVantage is used, which requires an API key. See
387 the introduction for information on configuring currency rate
388 conversions and see Finance::Quote::CurrencyRates::AlphaVantage for
389 information about the API key.
390 currency_lookup
392 my $currency = $quoter->currency_lookup();
393 my $currency = $quoter->currency_lookup( name => "Caribbean");
394 my $currency = $quoter->currency_loopup( country => qw/denmark/i );
395 my $currency = $q->currency_lookup(country => qr/united states/i, number => 840);
396 "currency_lookup" takes zero or more constraints and filters the list
398 of currencies known to Finance::Quote. It returns a hash reference
399 where the keys are ISO currency codes and the values are hash
400 references containing metadata about the currency.
401 A constraint is a key name and either a scalar or regular expression.
403 A currency satisfies the constraint if its metadata hash contains the
404 constraint key and the value of that metadata field matches the regular
405 expression or contains the constraint value as a substring. If the
406 metadata field is an array, then it satisfies the constraint if any
407 value in the array satisfies the constraint.
408 parse_csv
410 my @list = Finance::Quote::parse_csv($string);
411 "parse_csv" is a utility function for splitting a comma separated value
413 string into a list of terms, treating double-quoted strings that
414 contain commas as a single value.
415 parse_csv_semicolon
417 my @list = Finance::Quote::parse_csv_semicolon($string);
418 "parse_csv" is a utility function for splitting a semicolon separated
420 value string into a list of terms, treating double-quoted strings that
421 contain semicolons as a single value.
422
424 default_currency_fields
425 Replaced with get_default_currency_fields().
426 sources
428 Replaced with get_methods().
429 failover
431 Replaced with get_failover() and set_failover().
432 require_labels
434 Replaced with get_required_labels() and set_required_labels().
435 user_agent
437 Replaced with get_user_agent().
438 set_currency
440 Replaced with get_fetch_currency() and set_fetch_currency().
441
443 Finance::Quote respects all environment that your installed version of
444 LWP::UserAgent respects. Most importantly, it respects the http_proxy
445 environment variable.
446
448 The caller cannot control the fetch failover order.
449 The two-dimensional hash is a somewhat unwieldly method of passing
451 around information when compared to references
452
454 Copyright 1998, Dj Padzensky
455 Copyright 1998, 1999 Linas Vepstas
456 Copyright 2000, Yannick LE NY (update for Yahoo Europe and YahooQuote)
457 Copyright 2000-2001, Paul Fenwick (updates for ASX, maintenance and release)
458 Copyright 2000-2001, Brent Neal (update for TIAA-CREF)
459 Copyright 2000 Volker Stuerzl (DWS)
460 Copyright 2001 Rob Sessink (AEX support)
461 Copyright 2001 Leigh Wedding (ASX updates)
462 Copyright 2001 Tobias Vancura (Fool support)
463 Copyright 2001 James Treacy (TD Waterhouse support)
464 Copyright 2008 Erik Colson (isoTime)
465 This program is free software; you can redistribute it and/or modify it
467 under the terms of the GNU General Public License as published by the
468 Free Software Foundation; either version 2 of the License, or (at your
469 option) any later version.
470 Currency information fetched through this module is bound by the terms
472 and conditons of the data source.
473 Other copyrights and conditions may apply to data fetched through this
475 module. Please refer to the sub-modules for further information.
476
478 Dj Padzensky <djpadz@padz.net>, PadzNet, Inc.
479 Linas Vepstas <linas@linas.org>
480 Yannick LE NY <y-le-ny@ifrance.com>
481 Paul Fenwick <pjf@cpan.org>
482 Brent Neal <brentn@users.sourceforge.net>
483 Volker Stuerzl <volker.stuerzl@gmx.de>
484 Keith Refson <Keith.Refson#earth.ox.ac.uk>
485 Rob Sessink <rob_ses@users.sourceforge.net>
486 Leigh Wedding <leigh.wedding@telstra.com>
487 Tobias Vancura <tvancura@altavista.net>
488 James Treacy <treacy@debian.org>
489 Bradley Dean <bjdean@bjdean.id.au>
490 Erik Colson <eco@ecocode.net>
491 The Finance::Quote home page can be found at
493 http://finance-quote.sourceforge.net/
494 The Finance::YahooQuote home page can be found at
496 http://www.padz.net/~djpadz/YahooQuote/
497 The GnuCash home page can be found at http://www.gnucash.org/
499
501 Finance::Quote::CurrencyRates::AlphaVantage,
502 Finance::Quote::CurrencyRates::ECB,
503 Finance::Quote::CurrencyRates::Fixer,
504 Finance::Quote::CurrencyRates::OpenExchange,
505 Finance::Quote::CurrencyRates::YahooJSON,
506 Finance::Quote::AEX,
507 Finance::Quote::ASEGR,
508 Finance::Quote::ASX,
509 Finance::Quote::Bloomberg,
510 Finance::Quote::BSEIndia,
511 Finance::Quote::Bourso,
512 Finance::Quote::BVB,
513 Finance::Quote::CSE,
514 Finance::Quote::Cdnfundlibrary,
515 Finance::Quote::Comdirect,
516 Finance::Quote::Consorsbank,
517 Finance::Quote::Currencies,
518 Finance::Quote::DWS,
519 Finance::Quote::Deka,
520 Finance::Quote::FTfunds,
521 Finance::Quote::Fidelity,
522 Finance::Quote::Finanzpartner,
523 Finance::Quote::Fondsweb,
524 Finance::Quote::Fool,
525 Finance::Quote::Fundata
526 Finance::Quote::GoldMoney,
527 Finance::Quote::GoogleWeb,
528 Finance::Quote::HU,
529 Finance::Quote::IEXCloud,
530 Finance::Quote::IndiaMutual,
531 Finance::Quote::MorningstarAU,
532 Finance::Quote::MorningstarCH,
533 Finance::Quote::MorningstarJP,
534 Finance::Quote::MorningstarUK,
535 Finance::Quote::NSEIndia,
536 Finance::Quote::NZX,
537 Finance::Quote::OnVista,
538 Finance::Quote::Oslobors,
539 Finance::Quote::SEB,
540 Finance::Quote::SIX,
541 Finance::Quote::TSP,
542 Finance::Quote::TMX,
543 Finance::Quote::Tiaacref,
544 Finance::Quote::TesouroDireto,
545 Finance::Quote::TreasuryDirect,
546 Finance::Quote::Troweprice,
547 Finance::Quote::TwelveData,
548 Finance::Quote::Union,
549 Finance::Quote::YahooJSON,
550 Finance::Quote::YahooWeb,
551 Finance::Quote::ZA
552 You should have received the Finance::Quote hacker's guide with this
554 package. Please read it if you are interested in adding extra methods
555 to this package. The latest hacker's guide can also be found on GitHub
556 at
557 https://github.com/finance-quote/finance-quote/blob/master/Documentation/Hackers-Guide
558perl v5.36.1 2023-08-13 Finance::Quote(3)