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. See the documentation for
194 the individual Finance::Quote::CurrencyRates to learn more.
195 get_default_currency_fields
197 my @fields = Finance::Quote::get_default_currency_fields();
198 "get_default_currency_fields" returns the standard list of fields in a
200 quote that are automatically converted during currency conversion.
201 Individual modules may override this list.
202 get_default_timeout
204 my $value = Finance::Quote::get_default_timeout();
205 "get_default_timeout" returns the current Finance::Quote default
207 timeout in seconds for web requests. Finance::Quote does not specify a
208 default timeout, deferring to the underlying user agent for web
209 requests. So this function will return undef unless
210 "set_default_timeout" was previously called.
211 set_default_timeout
213 Finance::Quote::set_default_timeout(45);
214 "set_default_timeout" sets the Finance::Quote default timeout to a new
216 value.
217 get_methods
219 my @methods = Finance::Quote::get_methods();
220 "get_methods" returns the list of methods that can be passed to "new"
222 when creating a quoter object and as the first argument to "fetch".
223
225 B_to_billions
226 my $value = $q->B_to_billions("20B");
227 "B_to_billions" is a utility function that expands a numeric string
229 with a "B" suffix to the corresponding multiple of 1000000000.
230 decimal_shiftup
232 my $value = $q->decimal_shiftup("123.45", 1); # returns 1234.5
233 my $value = $q->decimal_shiftup("0.25", 1); # returns 2.5
234 "decimal_shiftup" moves a the decimal point in a numeric string the
236 specified number of places to the right.
237 fetch
239 my %stocks = $q->fetch("alphavantage", "IBM", "MSFT", "LNUX");
240 my $hashref = $q->fetch("nasdaq", "IBM", "MSFT", "LNUX");
241 "fetch" takes a method as its first argument and the remaining
243 arguments are treated as securities. If the quoter $q was constructed
244 with a specific method or methods, then only those methods are
245 available.
246 When called in an array context, a hash is returned. In a scalar
248 context, a reference to a hash will be returned. The keys for the
249 returned hash are "{SECURITY,LABEL}". For the above example call,
250 $stocks{"IBM","high"} is the high value for IBM.
251 $q->get_methods() returns the list of valid methods for quoter object
253 $q. Some methods specify a specific Finance::Quote module, such as
254 'alphavantage'. Other methods are available from multiple
255 Finance::Quote modules, such as 'nasdaq'. The quoter failover over
256 option determines if multiple modules are consulted for methods such as
257 'nasdaq' that more than one implementation.
258 get_failover
260 my $failover = $q->get_failover();
261 Failover is when the "fetch" method attempts to retrieve quote
263 information for a security from alternate sources when the requested
264 method fails. "get_failover" returns a boolean value indicating if the
265 quoter object will use failover or not.
266 set_failover
268 $q->set_failover(False);
269 "set_failover" sets the failover flag on the quoter object.
271 get_fetch_currency
273 my $currency = $q->get_fetch_currency();
274 "get_fetch_currency" returns either the desired currency code for the
276 quoter object or undef if no target currency was set during
277 construction or with the "set_fetch_currency" function.
278 set_fetch_currency
280 $q->set_fetch_currency("FRF"); # Get results in French Francs.
281 "set_fetch_currency" method is used to request that all information be
283 returned in the specified currency. Note that this increases the
284 chance stock-lookup failure, as remote requests must be made to fetch
285 both the stock information and the currency rates. In order to improve
286 reliability and speed performance, currency conversion rates are cached
287 and are assumed not to change for the duration of the Finance::Quote
288 object.
289 See the introduction to this page for information on how to configure
291 the source of currency conversion rates.
292 get_required_labels
294 my @labels = $q->get_required_labels();
295 "get_required_labels" returns the list of labels that must be populated
297 for a security quote to be considered valid and returned by "fetch".
298 set_required_labels
300 my $labels = ['close', 'isodate', 'last'];
301 $q->set_required_labels($labels);
302 "set_required_labels" updates the list of required labels for the
304 quoter object.
305 get_timeout
307 my $timeout = $q->get_timeout();
308 "get_timeout" returns the timeout in seconds the quoter object is using
310 for web requests.
311 set_timeout
313 $q->set_timeout(45);
314 "set_timeout" updated the timeout in seconds for the quoter object.
316 store_date
318 $quoter->store_date(\%info, $stocks, {eurodate => '06/11/2020'});
319 "store_date" is used by modules to consistent store date information
321 about securities. Given the various pieces of a date, this function
322 figures out how to construct a ISO date (yyyy-mm-dd) and US date
323 (mm/dd/yyyy) and stores those values in %info for security $stock.
324 get_user_agent
326 my $ua = $q->get_user_agent();
327 "get_user_agent" returns the LWP::UserAgent the quoter object is using
329 for web requests.
330 isoTime
332 $q->isoTime("11:39PM"); # returns "23:39"
333 $q->isoTime("9:10 AM"); # returns "09:10"
334 "isoTime" returns an ISO formatted time.
336
338 The following methods are available as class methods, but can also be
339 called from Finance::Quote objects.
340 scale_field
342 my $value = Finance::Quote->scale_field('1023', '0.01')
343 "scale_field" is a utility function that scales the first argument by
345 the second argument. In the above example, "value" is '10.23'.
346 currency
348 my $value = $q->currency('15.95 USD', 'AUD');
349 my $value = Finance::Quote->currency('23.45 EUR', 'RUB');
350 "currency" converts a value with a currency code suffix to another
352 currency using the current exchange rate as determined by the
353 Finance::Quote::CurrencyRates method or methods configured for the
354 quoter $q. When called as a class method, only
355 Finance::Quote::AlphaVantage is used, which requires an API key. See
356 the introduction for information on configuring currency rate
357 conversions and see Finance::Quote::CurrencyRates::AlphaVantage for
358 information about the API key.
359 currency_lookup
361 my $currency = $quoter->currency_lookup();
362 my $currency = $quoter->currency_lookup( name => "Caribbean");
363 my $currency = $quoter->currency_loopup( country => qw/denmark/i );
364 my $currency = $q->currency_lookup(country => qr/united states/i, number => 840);
365 "currency_lookup" takes zero or more constraints and filters the list
367 of currencies known to Finance::Quote. It returns a hash reference
368 where the keys are ISO currency codes and the values are hash
369 references containing metadata about the currency.
370 A constraint is a key name and either a scalar or regular expression.
372 A currency satisfies the constraint if its metadata hash contains the
373 constraint key and the value of that metadata field matches the regular
374 expression or contains the constraint value as a substring. If the
375 metadata field is an array, then it satisfies the constraint if any
376 value in the array satisfies the constraint.
377 parse_csv
379 my @list = Finance::Quote::parse_csv($string);
380 "parse_csv" is a utility function for splitting a comma separated value
382 string into a list of terms, treating double-quoted strings that
383 contain commas as a single value.
384 parse_csv_semicolon
386 my @list = Finance::Quote::parse_csv_semicolon($string);
387 "parse_csv" is a utility function for splitting a semicolon separated
389 value string into a list of terms, treating double-quoted strings that
390 contain semicolons as a single value.
391
393 default_currency_fields
394 Replaced with get_default_currency_fields().
395 sources
397 Replaced with get_methods().
398 failover
400 Replaced with get_failover() and set_failover().
401 require_labels
403 Replaced with get_required_labels() and set_required_labels().
404 user_agent
406 Replaced with get_user_agent().
407 set_currency
409 Replaced with get_fetch_currency() and set_fetch_currency().
410
412 Finance::Quote respects all environment that your installed version of
413 LWP::UserAgent respects. Most importantly, it respects the http_proxy
414 environment variable.
415
417 The caller cannot control the fetch failover order.
418 The two-dimensional hash is a somewhat unwieldly method of passing
420 around information when compared to references
421
423 Copyright 1998, Dj Padzensky
424 Copyright 1998, 1999 Linas Vepstas
425 Copyright 2000, Yannick LE NY (update for Yahoo Europe and YahooQuote)
426 Copyright 2000-2001, Paul Fenwick (updates for ASX, maintenance and release)
427 Copyright 2000-2001, Brent Neal (update for TIAA-CREF)
428 Copyright 2000 Volker Stuerzl (DWS)
429 Copyright 2001 Rob Sessink (AEX support)
430 Copyright 2001 Leigh Wedding (ASX updates)
431 Copyright 2001 Tobias Vancura (Fool support)
432 Copyright 2001 James Treacy (TD Waterhouse support)
433 Copyright 2008 Erik Colson (isoTime)
434 This program is free software; you can redistribute it and/or modify it
436 under the terms of the GNU General Public License as published by the
437 Free Software Foundation; either version 2 of the License, or (at your
438 option) any later version.
439 Currency information fetched through this module is bound by the terms
441 and conditons of the data source.
442 Other copyrights and conditions may apply to data fetched through this
444 module. Please refer to the sub-modules for further information.
445
447 Dj Padzensky <djpadz@padz.net>, PadzNet, Inc.
448 Linas Vepstas <linas@linas.org>
449 Yannick LE NY <y-le-ny@ifrance.com>
450 Paul Fenwick <pjf@cpan.org>
451 Brent Neal <brentn@users.sourceforge.net>
452 Volker Stuerzl <volker.stuerzl@gmx.de>
453 Keith Refson <Keith.Refson#earth.ox.ac.uk>
454 Rob Sessink <rob_ses@users.sourceforge.net>
455 Leigh Wedding <leigh.wedding@telstra.com>
456 Tobias Vancura <tvancura@altavista.net>
457 James Treacy <treacy@debian.org>
458 Bradley Dean <bjdean@bjdean.id.au>
459 Erik Colson <eco@ecocode.net>
460 The Finance::Quote home page can be found at
462 http://finance-quote.sourceforge.net/
463 The Finance::YahooQuote home page can be found at
465 http://www.padz.net/~djpadz/YahooQuote/
466 The GnuCash home page can be found at http://www.gnucash.org/
468
470 Finance::Quote::CurrencyRates::AlphaVantage,
471 Finance::Quote::CurrencyRates::ECB,
472 Finance::Quote::CurrencyRates::Fixer,
473 Finance::Quote::CurrencyRates::OpenExchange, Finance::Quote::AEX,
474 Finance::Quote::ASEGR, Finance::Quote::ASX, Finance::Quote::Bloomberg,
475 Finance::Quote::BSEIndia, Finance::Quote::Bourso, Finance::Quote::CSE,
476 Finance::Quote::Cdnfundlibrary, Finance::Quote::Comdirect,
477 Financ::Quote::Currencies, Finance::Quote::DWS, Finance::Quote::Deka,
478 Finance::Quote::FTfunds, Finance::Quote::Fidelity,
479 Finance::Quote::Finanzpartner, Finance::Quote::Fondsweb,
480 Finance::Quote::Fool, Finance::Quote::Fundata
481 Finance::Quote::GoldMoney, Finance::Quote::HU,
482 Finance::Quote::IEXCloud, Finance::Quote::IndiaMutual,
483 Finance::Quote::MStaruk, Finance::Quote::MorningstarAU,
484 Finance::Quote::MorningstarCH, Finance::Quote::MorningstarJP,
485 Finance::Quote::NSEIndia, Finance::Quote::NZX, Finance::Quote::OnVista,
486 Finance::Quote::Oslobors, Finance::Quote::SEB, Finance::Quote::SIX,
487 Finance::Quote::Tradeville, Finance::Quote::TSP, Finance::Quote::TMX,
488 Finance::Quote::Tiaacref, Finance::Quote::TesouroDireto,
489 Finance::Quote::Troweprice, Finance::Quote::USFedBonds,
490 Finance::Quote::Union, Finance::Quote::YahooJSON, Finance::Quote::ZA
491 You should have received the Finance::Quote hacker's guide with this
493 package. Please read it if you are interested in adding extra methods
494 to this package. The latest hacker's guide can also be found on GitHub
495 at
496 https://github.com/finance-quote/finance-quote/blob/master/Documentation/Hackers-Guide
497perl v5.34.1 2022-07-04 Finance::Quote(3)