Finance::Quote(3pm)

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 depreciated, 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
78            this information.
79
80       If all stock lookups fail (possibly because of a failed connection)
81       then the empty list may be returned, or undef in a scalar context.
82

AVAILABLE METHODS

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

ENVIRONMENT

246       Finance::Quote respects all environment that your installed version of
247       LWP::UserAgent respects.  Most importantly, it respects the http_proxy
248       environment variable.
249

BUGS

251       There are no ways for a user to define a failover list.
252
253       The two-dimensional hash is a somewhat unwieldly method of passing
254       around information when compared to references.  A future release is
255       planned that will allow for information to be returned in a more
256       flexible $hash{$stock}{$label} style format.
257
258       There is no way to override the default behaviour to cache currency
259       conversion rates.
260

COPYRIGHT & LICENSE

262        Copyright 1998, Dj Padzensky
263        Copyright 1998, 1999 Linas Vepstas
264        Copyright 2000, Yannick LE NY (update for Yahoo Europe and YahooQuote)
265        Copyright 2000-2001, Paul Fenwick (updates for ASX, maintainence and release)
266        Copyright 2000-2001, Brent Neal (update for TIAA-CREF)
267        Copyright 2000 Volker Stuerzl (DWS and VWD support)
268        Copyright 2000 Keith Refson (Trustnet support)
269        Copyright 2001 Rob Sessink (AEX support)
270        Copyright 2001 Leigh Wedding (ASX updates)
271        Copyright 2001 Tobias Vancura (Fool support)
272        Copyright 2001 James Treacy (TD Waterhouse support)
273        Copyright 2008 Erik Colson (isoTime)
274
275       This program is free software; you can redistribute it and/or modify it
276       under the terms of the GNU General Public License as published by the
277       Free Software Foundation; either version 2 of the License, or (at your
278       option) any later version.
279
280       Currency information fetched through this module is bound by Yahoo!'s
281       terms and conditons.
282
283       Other copyrights and conditions may apply to data fetched through this
284       module.  Please refer to the sub-modules for further information.
285

AUTHORS

287         Dj Padzensky <djpadz@padz.net>, PadzNet, Inc.
288         Linas Vepstas <linas@linas.org>
289         Yannick LE NY <y-le-ny@ifrance.com>
290         Paul Fenwick <pjf@cpan.org>
291         Brent Neal <brentn@users.sourceforge.net>
292         Volker Stuerzl <volker.stuerzl@gmx.de>
293         Keith Refson <Keith.Refson#earth.ox.ac.uk>
294         Rob Sessink <rob_ses@users.sourceforge.net>
295         Leigh Wedding <leigh.wedding@telstra.com>
296         Tobias Vancura <tvancura@altavista.net>
297         James Treacy <treacy@debian.org>
298         Bradley Dean <bjdean@bjdean.id.au>
299         Erik Colson <eco@ecocode.net>
300
301       The Finance::Quote home page can be found at
302       http://finance-quote.sourceforge.net/
303
304       The Finance::YahooQuote home page can be found at
305       http://www.padz.net/~djpadz/YahooQuote/
306
307       The GnuCash home page can be found at http://www.gnucash.org/
308