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          $q = Finance::Quote->new;
12
13          $q->timeout(60);
14
15          $conversion_rate = $q->currency("AUD","USD");
16          $q->set_currency("EUR");  # Return all info in Euros.
17
18          $q->require_labels(qw/price date high low volume/);
19
20          $q->failover(1); # Set failover support (on by default).
21
22          %quotes  = $q->fetch("nasdaq",@stocks);
23          $hashref = $q->fetch("nyse",@stocks);
24

DESCRIPTION

26       This module gets stock quotes from various internet sources, including
27       Yahoo! Finance, Fidelity Investments, and the Australian Stock
28       Exchange.  There are two methods of using this module -- a functional
29       interface that is deprecated, and an object-orientated method that
30       provides greater flexibility and stability.
31
32       With the exception of straight currency exchange rates, all information
33       is returned as a two-dimensional hash (or a reference to such a hash,
34       if called in a scalar context).  For example:
35
36           %info = $q->fetch("australia","CML");
37           print "The price of CML is ".$info{"CML","price"};
38
39       The first part of the hash (eg, "CML") is referred to as the stock.
40       The second part (in this case, "price") is referred to as the label.
41
42   LABELS
43       When information about a stock is returned, the following standard
44       labels may be used.  Some custom-written modules may use labels not
45       mentioned here.  If you wish to be certain that you obtain a certain
46       set of labels for a given stock, you can specify that using
47       require_labels().
48
49           name         Company or Mutual Fund Name
50           last         Last Price
51           high         Highest trade today
52           low          Lowest trade today
53           date         Last Trade Date  (MM/DD/YY format)
54           time         Last Trade Time
55           net          Net Change
56           p_change     Percent Change from previous day's close
57           volume       Volume
58           avg_vol      Average Daily Vol
59           bid          Bid
60           ask          Ask
61           close        Previous Close
62           open         Today's Open
63           day_range    Day's Range
64           year_range   52-Week Range
65           eps          Earnings per Share
66           pe           P/E Ratio
67           div_date     Dividend Pay Date
68           div          Dividend per Share
69           div_yield    Dividend Yield
70           cap          Market Capitalization
71           ex_div       Ex-Dividend Date.
72           nav          Net Asset Value
73           yield        Yield (usually 30 day avg)
74           exchange     The exchange the information was obtained from.
75           success      Did the stock successfully return information? (true/false)
76           errormsg     If success is false, this field may contain the reason why.
77           method       The module (as could be passed to fetch) which found this
78                        information.
79           type         The type of equity returned
80
81       If all stock lookups fail (possibly because of a failed connection)
82       then the empty list may be returned, or undef in a scalar context.
83

INSTALLATION

85       To install this module, run the following commands:
86
87           perl Makefile.PL
88           make
89           make test
90           make install
91
92       For more detailed instructions, please see the INSTALL file.
93

SUPPORT AND DOCUMENTATION

95       After installing, you can find documentation for this module with the
96       perldoc command.
97
98           perldoc Finance::Quote
99
100       You can also look for information at:
101
102       RT, CPAN's request tracker
103           http://rt.cpan.org/NoAuth/Bugs.html?Dist=Finance-Quote
104
105       AnnoCPAN, Annotated CPAN documentation
106           http://annocpan.org/dist/Finance-Quote
107
108       CPAN Ratings
109           http://cpanratings.perl.org/d/Finance-Quote
110
111       Search CPAN
112           http://search.cpan.org/dist/Finance-Quote
113
114       The Finance::Quote home page
115           http://finance-quote.sourceforge.net/
116
117       The Finance::YahooQuote home page
118           http://www.padz.net/~djpadz/YahooQuote/
119
120       The GnuCash home page
121           http://www.gnucash.org/
122

AVAILABLE METHODS

124   NEW
125           my $q = Finance::Quote->new;
126           my $q = Finance::Quote->new("ASX");
127           my $q = Finance::Quote->new("-defaults", "CustomModule");
128
129       With no arguents, this creates a new Finance::Quote object with the
130       default methods.  If the environment variable FQ_LOAD_QUOTELET is set,
131       then the contents of FQ_LOAD_QUOTELET (split on whitespace) will be
132       used as the argument list.  This allows users to load their own custom
133       modules without having to change existing code.  If you do not want
134       users to be able to load their own modules at run-time, pass an
135       explicit argumetn to ->new() (usually "-defaults").
136
137       When new() is passed one or more arguments, an object is created with
138       only the specified modules loaded.  If the first argument is
139       "-defaults", then the default modules will be loaded first, followed by
140       any other specified modules.
141
142       Note that the FQ_LOAD_QUOTELET environment variable must begin with
143       "-defaults" if you wish the default modules to be loaded.
144
145       Any modules specified will automatically be looked for in the
146       Finance::Quote:: module-space.  Hence, Finance::Quote->new("ASX") will
147       load the module Finance::Quote::ASX.
148
149       Please read the Finance::Quote hacker's guide for information on how to
150       create new modules for Finance::Quote.
151
152   FETCH
153           my %stocks  = $q->fetch("usa","IBM","MSFT","LNUX");
154           my $hashref = $q->fetch("usa","IBM","MSFT","LNUX");
155
156       Fetch takes an exchange as its first argument.  The second and
157       remaining arguments are treated as stock-names.  In the standard
158       Finance::Quote distribution, the following exchanges are recognised:
159
160           australia   Australan Stock Exchange
161           dwsfunds    Deutsche Bank Gruppe funds
162           fidelity    Fidelity Investments
163           tiaacref    TIAA-CREF
164           troweprice    T. Rowe Price
165           europe    European Markets
166           canada    Canadian Markets
167           usa     USA Markets
168           nyse    New York Stock Exchange
169           nasdaq    NASDAQ
170           uk_unit_trusts  UK Unit Trusts
171           vanguard    Vanguard Investments
172           vwd     Vereinigte Wirtschaftsdienste GmbH
173
174       When called in an array context, a hash is returned.  In a scalar
175       context, a reference to a hash will be returned.  The structure of this
176       hash is described earlier in this document.
177
178       The fetch method automatically arranges for failover support and
179       currency conversion if requested.
180
181       If you wish to fetch information from only one particular source, then
182       consult the documentation of that sub-module for further information.
183
184   SOURCES
185           my @sources = $q->sources;
186           my $listref = $q->sources;
187
188       The sources method returns a list of sources that have currently been
189       loaded and can be passed to the fetch method.  If you're providing a
190       user with a list of sources to choose from, then it is recommended that
191       you use this method.
192
193   CURRENCY_LOOKUP
194           $currencies_by_name = $q->currency_lookup( name => 'Australian' );
195           $currencies_by_code = $q->currency_lookup( code => qr/^b/i      );
196           $currencies_by_both = $q->currency_lookup( name => qr/pound/i
197                                                    , code => 'GB'         );
198
199       The currency_lookup method provides a search against the known
200       currencies. The list of currencies is based on the available currencies
201       in the Yahoo Currency Converter (the list is stored within the module
202       as the list should be fairly static).
203
204       The lookup can be done by currency name (ie "Australian Dollar"), by
205       code (ie "AUD") or both. You can pass either a scalar or regular
206       expression as a search value - scalar values are matched by substring
207       while regular expressions are matched as-is (no changes are made to the
208       expression).
209
210       See Finance::Quote::Currencies::fetch_live_currencies (and the
211       "t/currencies.t" test file) for a way to make sure that the stored
212       currency list is up to date.
213
214   CURRENCY
215           $conversion_rate = $q->currency("USD","AUD");
216
217       The currency method takes two arguments, and returns a conversion rate
218       that can be used to convert from the first currency into the second.
219       In the example above, we've requested the factor that would convert US
220       dollars into Australian dollars.
221
222       The currency method will return a false value if a given currency
223       conversion cannot be fetched.
224
225       At the moment, currency rates are fetched from Yahoo!, and the
226       information returned is governed by Yahoo!'s terms and conditions.  See
227       Finance::Quote::Yahoo for more information.
228
229   SET_CURRENCY
230           $q->set_currency("FRF");  # Get results in French Francs.
231
232       The set_currency method can be used to request that all information be
233       returned in the specified currency.  Note that this increases the
234       chance stock-lookup failure, as remote requests must be made to fetch
235       both the stock information and the currency rates.  In order to improve
236       reliability and speed performance, currency conversion rates are cached
237       and are assumed not to change for the duration of the Finance::Quote
238       object.
239
240       At this time, currency conversions are only looked up using Yahoo!'s
241       services, and hence information obtained with automatic currency
242       conversion is bound by Yahoo!'s terms and conditions.
243
244   FAILOVER
245           $q->failover(1);  # Set automatic failover support.
246           $q->failover(0);  # Disable failover support.
247
248       The failover method takes a single argument which either sets (if true)
249       or unsets (if false) automatic failover support.  If automatic failover
250       support is enabled (default) then multiple information sources will be
251       tried if one or more sources fail to return the requested information.
252       Failover support will significantly increase the time spent looking for
253       a non-existant stock.
254
255       If the failover method is called with no arguments, or with an
256       undefined argument, it will return the current failover state
257       (true/false).
258
259   USER_AGENT
260           my $ua = $q->user_agent;
261
262       The user_agent method returns the LWP::UserAgent object that
263       Finance::Quote and its helpers use.  Normally this would not be useful
264       to an application, however it is possible to modify the user-agent
265       directly using this method:
266
267           $q->user_agent->timeout(10);  # Set the timeout directly.
268
269   SCALE_FIELD
270           my $pounds = $q->scale_field($item_in_pence,0.01);
271
272       The scale_field() function is a helper that can scale complex fields
273       such as ranges (eg, "102.5 - 103.8") and other fields where the numbers
274       should be scaled but any surrounding text preserved.  It's most useful
275       in writing new Finance::Quote modules where you may retrieve
276       information in a non-ISO4217 unit (such as cents) and would like to
277       scale it to a more useful unit (like dollars).
278
279   ISOTIME
280           $q->isoTime("11:39PM");    # returns "23:39"
281           $q->isoTime("9:10 AM");    # returns "09:10"
282
283       This function will return a isoformatted time
284

ENVIRONMENT

286       Finance::Quote respects all environment that your installed version of
287       LWP::UserAgent respects.  Most importantly, it respects the http_proxy
288       environment variable.
289

BUGS

291       There are no ways for a user to define a failover list.
292
293       The two-dimensional hash is a somewhat unwieldly method of passing
294       around information when compared to references.  A future release is
295       planned that will allow for information to be returned in a more
296       flexible $hash{$stock}{$label} style format.
297
298       There is no way to override the default behaviour to cache currency
299       conversion rates.
300
302        Copyright 1998, Dj Padzensky
303        Copyright 1998, 1999 Linas Vepstas
304        Copyright 2000, Yannick LE NY (update for Yahoo Europe and YahooQuote)
305        Copyright 2000-2001, Paul Fenwick (updates for ASX, maintainence and release)
306        Copyright 2000-2001, Brent Neal (update for TIAA-CREF)
307        Copyright 2000 Volker Stuerzl (DWS and VWD support)
308        Copyright 2000 Keith Refson (Trustnet support)
309        Copyright 2001 Rob Sessink (AEX support)
310        Copyright 2001 Leigh Wedding (ASX updates)
311        Copyright 2001 Tobias Vancura (Fool support)
312        Copyright 2001 James Treacy (TD Waterhouse support)
313        Copyright 2008 Erik Colson (isoTime)
314
315       This program is free software; you can redistribute it and/or modify it
316       under the terms of the GNU General Public License as published by the
317       Free Software Foundation; either version 2 of the License, or (at your
318       option) any later version.
319
320       Currency information fetched through this module is bound by Yahoo!'s
321       terms and conditons.
322
323       Other copyrights and conditions may apply to data fetched through this
324       module.  Please refer to the sub-modules for further information.
325

AUTHORS

327         Dj Padzensky <djpadz@padz.net>, PadzNet, Inc.
328         Linas Vepstas <linas@linas.org>
329         Yannick LE NY <y-le-ny@ifrance.com>
330         Paul Fenwick <pjf@cpan.org>
331         Brent Neal <brentn@users.sourceforge.net>
332         Volker Stuerzl <volker.stuerzl@gmx.de>
333         Keith Refson <Keith.Refson#earth.ox.ac.uk>
334         Rob Sessink <rob_ses@users.sourceforge.net>
335         Leigh Wedding <leigh.wedding@telstra.com>
336         Tobias Vancura <tvancura@altavista.net>
337         James Treacy <treacy@debian.org>
338         Bradley Dean <bjdean@bjdean.id.au>
339         Erik Colson <eco@ecocode.net>
340
341       The Finance::Quote home page can be found at
342       http://finance-quote.sourceforge.net/
343
344       The Finance::YahooQuote home page can be found at
345       http://www.padz.net/~djpadz/YahooQuote/
346
347       The GnuCash home page can be found at http://www.gnucash.org/
348

SEE ALSO

350       Finance::Quote::AEX, Finance::Quote::ASX,
351       Finance::Quote::Cdnfundlibrary, Finance::Quote::DWS,
352       Finance::Quote::Fidelity, Finance::Quote::FinanceCanada,
353       Finance::Quote::Fool, Finance::Quote::FTPortfolios,
354       Finance::Quote::Tdefunds, Finance::Quote::Tdwaterhouse,
355       Finance::Quote::Tiaacref, Finance::Quote::Troweprice,
356       Finance::Quote::Trustnet, Finance::Quote::VWD,
357       Finance::Quote::Yahoo::Australia, Finance::Quote::Yahoo::Europe,
358       Finance::Quote::Yahoo::USA, LWP::UserAgent
359
360       You should have also received the Finance::Quote hacker's guide with
361       this package.  Please read it if you are interested in adding extra
362       methods to this package.  The hacker's guide can also be found on the
363       Finance::Quote website, http://finance-quote.sourceforge.net/
364
365
366
367perl v5.32.0                      2020-07-28                 Finance::Quote(3)
Impressum