1Finance::Quote(3)     User Contributed Perl Documentation    Finance::Quote(3)
2
3
4

NAME

6       Finance::Quote - Get stock and mutual fund quotes from various
7       exchanges
8

SYNOPSIS

10          use Finance::Quote;
11
12          $q = Finance::Quote->new;
13          %quotes  = $q->fetch("nasdaq", @stocks);
14

DESCRIPTION

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
22           $q = Finance::Quote->new;
23           %info = $q->fetch("australia", "CML");
24           print "The price of CML is ".$info{"CML", "price"};
25
26       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
29   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
36           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
70       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

INSTALLATION

74       Please note that the Github repository is not meant for general users
75       of Finance::Quote for installation.
76
77       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
81           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
88       If you have the CPAN module installed: Using cpanm (Requires
89       App::cpanminus)
90
91           cpanm Finance::Quote
92
93       or Using CPAN shell
94
95           perl -MCPAN -e shell
96           install Finance::Quote
97

SUPPORT AND DOCUMENTATION

99       After installing, you can find documentation for this module with the
100       perldoc command.
101
102           perldoc Finance::Quote
103
104       You can also look for information at:
105
106       Finance::Quote GitHub project
107           https://github.com/finance-quote/finance-quote
108
109       Search CPAN
110           http://search.cpan.org/dist/Finance-Quote
111
112       The Finance::Quote home page
113           http://finance-quote.sourceforge.net/
114
115       The Finance::YahooQuote home page
116           http://www.padz.net/~djpadz/YahooQuote/
117
118       The GnuCash home page
119           http://www.gnucash.org/
120

PUBLIC CLASS METHODS

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
126   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
136       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
142       A Finance::Quote object uses one or more methods to fetch quotes for
143       securities.
144
145       "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
149       "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
163       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
171       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
178       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
182       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
186       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
196   get_default_currency_fields
197           my @fields = Finance::Quote::get_default_currency_fields();
198
199       "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
203   get_default_timeout
204           my $value = Finance::Quote::get_default_timeout();
205
206       "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
212   set_default_timeout
213           Finance::Quote::set_default_timeout(45);
214
215       "set_default_timeout" sets the Finance::Quote default timeout to a new
216       value.
217
218   get_methods
219           my @methods = Finance::Quote::get_methods();
220
221       "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

PUBLIC OBJECT METHODS

225   B_to_billions
226           my $value = $q->B_to_billions("20B");
227
228       "B_to_billions" is a utility function that expands a numeric string
229       with a "B" suffix to the corresponding multiple of 1000000000.
230
231   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
235       "decimal_shiftup" moves a the decimal point in a numeric string the
236       specified number of places to the right.
237
238   fetch
239           my %stocks  = $q->fetch("alphavantage", "IBM", "MSFT", "LNUX");
240           my $hashref = $q->fetch("nasdaq", "IBM", "MSFT", "LNUX");
241
242       "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
247       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
252       $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
259   get_failover
260           my $failover = $q->get_failover();
261
262       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
267   set_failover
268           $q->set_failover(False);
269
270       "set_failover" sets the failover flag on the quoter object.
271
272   get_fetch_currency
273           my $currency = $q->get_fetch_currency();
274
275       "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
279   set_fetch_currency
280           $q->set_fetch_currency("FRF");  # Get results in French Francs.
281
282       "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
290       See the introduction to this page for information on how to configure
291       the source of currency conversion rates.
292
293   get_required_labels
294           my @labels = $q->get_required_labels();
295
296       "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
299   set_required_labels
300           my $labels = ['close', 'isodate', 'last'];
301           $q->set_required_labels($labels);
302
303       "set_required_labels" updates the list of required labels for the
304       quoter object.
305
306   get_timeout
307           my $timeout = $q->get_timeout();
308
309       "get_timeout" returns the timeout in seconds the quoter object is using
310       for web requests.
311
312   set_timeout
313           $q->set_timeout(45);
314
315       "set_timeout" updated the timeout in seconds for the quoter object.
316
317   store_date
318           $quoter->store_date(\%info, $stocks, {eurodate => '06/11/2020'});
319
320       "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
325   get_user_agent
326           my $ua = $q->get_user_agent();
327
328       "get_user_agent" returns the LWP::UserAgent the quoter object is using
329       for web requests.
330
331   isoTime
332           $q->isoTime("11:39PM");    # returns "23:39"
333           $q->isoTime("9:10 AM");    # returns "09:10"
334
335       "isoTime" returns an ISO formatted time.
336

PUBLIC CLASS OR OBJECT METHODS

338       The following methods are available as class methods, but can also be
339       called from Finance::Quote objects.
340
341   scale_field
342           my $value = Finance::Quote->scale_field('1023', '0.01')
343
344       "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
347   currency
348           my $value = $q->currency('15.95 USD', 'AUD');
349           my $value = Finance::Quote->currency('23.45 EUR', 'RUB');
350
351       "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
360   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
366       "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
371       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
378   parse_csv
379           my @list = Finance::Quote::parse_csv($string);
380
381       "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
385   parse_csv_semicolon
386           my @list = Finance::Quote::parse_csv_semicolon($string);
387
388       "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

LEGACY METHODS

393   default_currency_fields
394       Replaced with get_default_currency_fields().
395
396   sources
397       Replaced with get_methods().
398
399   failover
400       Replaced with get_failover() and set_failover().
401
402   require_labels
403       Replaced with get_required_labels() and set_required_labels().
404
405   user_agent
406       Replaced with get_user_agent().
407
408   set_currency
409       Replaced with get_fetch_currency() and set_fetch_currency().
410

ENVIRONMENT

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

BUGS

417       The caller cannot control the fetch failover order.
418
419       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
435       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
440       Currency information fetched through this module is bound by the terms
441       and conditons of the data source.
442
443       Other copyrights and conditions may apply to data fetched through this
444       module.  Please refer to the sub-modules for further information.
445

AUTHORS

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
461       The Finance::Quote home page can be found at
462       http://finance-quote.sourceforge.net/
463
464       The Finance::YahooQuote home page can be found at
465       http://www.padz.net/~djpadz/YahooQuote/
466
467       The GnuCash home page can be found at http://www.gnucash.org/
468

SEE ALSO

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       Finance::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::TreasuryDirect, Finance::Quote::Troweprice,
490       Finance::Quote::Union, Finance::Quote::YahooJSON, Finance::Quote::ZA
491
492       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
497
498
499
500perl v5.36.0                      2022-12-27                 Finance::Quote(3)
Impressum