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;
12 $q->timeout(60);
14 $conversion_rate = $q->currency("AUD","USD");
16 $q->set_currency("EUR"); # Return all info in Euros.
17 $q->require_labels(qw/price date high low volume/);
19 $q->failover(1); # Set failover support (on by default).
21 %quotes = $q->fetch("nasdaq",@stocks);
23 $hashref = $q->fetch("nyse",@stocks);
24
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 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 %info = $q->fetch("australia","CML");
37 print "The price of CML is ".$info{"CML","price"};
38 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 LABELS
43 When information about a stock is returned, the following standard
45 labels may be used. Some custom-written modules may use labels not
46 mentioned here. If you wish to be certain that you obtain a certain
47 set of labels for a given stock, you can specify that using
48 require_labels().
49 name Company or Mutual Fund Name
51 last Last Price
52 high Highest trade today
53 low Lowest trade today
54 date Last Trade Date (MM/DD/YY format)
55 time Last Trade Time
56 net Net Change
57 p_change Percent Change from previous day's close
58 volume Volume
59 avg_vol Average Daily Vol
60 bid Bid
61 ask Ask
62 close Previous Close
63 open Today's Open
64 day_range Day's Range
65 year_range 52-Week Range
66 eps Earnings per Share
67 pe P/E Ratio
68 div_date Dividend Pay Date
69 div Dividend per Share
70 div_yield Dividend Yield
71 cap Market Capitalization
72 ex_div Ex-Dividend Date.
73 nav Net Asset Value
74 yield Yield (usually 30 day avg)
75 exchange The exchange the information was obtained from.
76 success Did the stock successfully return information? (true/false)
77 errormsg If success is false, this field may contain the reason why.
78 method The module (as could be passed to fetch) which found
79 this information.
80 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
85 NEW
86 my $q = Finance::Quote->new;
88 my $q = Finance::Quote->new("ASX");
89 my $q = Finance::Quote->new("-defaults", "CustomModule");
90 With no arguents, this creates a new Finance::Quote object with the
92 default methods. If the environment variable FQ_LOAD_QUOTELET is set,
93 then the contents of FQ_LOAD_QUOTELET (split on whitespace) will be
94 used as the argument list. This allows users to load their own custom
95 modules without having to change existing code. If you do not want
96 users to be able to load their own modules at run-time, pass an
97 explicit argumetn to ->new() (usually "-defaults").
98 When new() is passed one or more arguments, an object is created with
100 only the specified modules loaded. If the first argument is
101 "-defaults", then the default modules will be loaded first, followed by
102 any other specified modules.
103 Note that the FQ_LOAD_QUOTELET environment variable must begin with
105 "-defaults" if you wish the default modules to be loaded.
106 Any modules specified will automatically be looked for in the
108 Finance::Quote:: module-space. Hence, Finance::Quote->new("ASX") will
109 load the module Finance::Quote::ASX.
110 Please read the Finance::Quote hacker's guide for information on how to
112 create new modules for Finance::Quote.
113 FETCH
115 my %stocks = $q->fetch("usa","IBM","MSFT","LNUX");
117 my $hashref = $q->fetch("usa","IBM","MSFT","LNUX");
118 Fetch takes an exchange as its first argument. The second and remain‐
120 ing arguments are treated as stock-names. In the standard
121 Finance::Quote distribution, the following exchanges are recognised:
122 australia Australan Stock Exchange
124 dwsfunds Deutsche Bank Gruppe funds
125 fidelity Fidelity Investments
126 tiaacref TIAA-CREF
127 troweprice T. Rowe Price
128 europe European Markets
129 canada Canadian Markets
130 usa USA Markets
131 nyse New York Stock Exchange
132 nasdaq NASDAQ
133 uk_unit_trusts UK Unit Trusts
134 vanguard Vanguard Investments
135 vwd Vereinigte Wirtschaftsdienste GmbH
136 When called in an array context, a hash is returned. In a scalar con‐
138 text, a reference to a hash will be returned. The structure of this
139 hash is described earlier in this document.
140 The fetch method automatically arranges for failover support and cur‐
142 rency conversion if requested.
143 If you wish to fetch information from only one particular source, then
145 consult the documentation of that sub-module for further information.
146 SOURCES
148 my @sources = $q->sources;
150 my $listref = $q->sources;
151 The sources method returns a list of sources that have currently been
153 loaded and can be passed to the fetch method. If you're providing a
154 user with a list of sources to choose from, then it is recommended that
155 you use this method.
156 CURRENCY
158 $conversion_rate = $q->currency("USD","AUD");
160 The currency method takes two arguments, and returns a conversion rate
162 that can be used to convert from the first currency into the second.
163 In the example above, we've requested the factor that would convert US
164 dollars into Australian dollars.
165 The currency method will return a false value if a given currency con‐
167 version cannot be fetched.
168 At the moment, currency rates are fetched from Yahoo!, and the informa‐
170 tion returned is governed by Yahoo!'s terms and conditions. See
171 Finance::Quote::Yahoo for more information.
172 SET_CURRENCY
174 $q->set_currency("FRF"); # Get results in French Francs.
176 The set_currency method can be used to request that all information be
178 returned in the specified currency. Note that this increases the
179 chance stock-lookup failure, as remote requests must be made to fetch
180 both the stock information and the currency rates. In order to improve
181 reliability and speed performance, currency conversion rates are cached
182 and are assumed not to change for the duration of the Finance::Quote
183 object.
184 At this time, currency conversions are only looked up using Yahoo!'s
186 services, and hence information obtained with automatic currency con‐
187 version is bound by Yahoo!'s terms and conditions.
188 FAILOVER
190 $q->failover(1); # Set automatic failover support.
192 $q->failover(0); # Disable failover support.
193 The failover method takes a single argument which either sets (if true)
195 or unsets (if false) automatic failover support. If automatic failover
196 support is enabled (default) then multiple information sources will be
197 tried if one or more sources fail to return the requested information.
198 Failover support will significantly increase the time spent looking for
199 a non-existant stock.
200 If the failover method is called with no arguments, or with an unde‐
202 fined argument, it will return the current failover state (true/false).
203 USER_AGENT
205 my $ua = $q->user_agent;
207 The user_agent method returns the LWP::UserAgent object that
209 Finance::Quote and its helpers use. Normally this would not be useful
210 to an application, however it is possible to modify the user-agent
211 directly using this method:
212 $q->user_agent->timeout(10); # Set the timeout directly.
214 SCALE_FIELD
216 my $pounds = $q->scale_field($item_in_pence,0.01);
218 The scale_field() function is a helper that can scale complex fields
220 such as ranges (eg, "102.5 - 103.8") and other fields where the numbers
221 should be scaled but any surrounding text preserved. It's most useful
222 in writing new Finance::Quote modules where you may retrieve informa‐
223 tion in a non-ISO4217 unit (such as cents) and would like to scale it
224 to a more useful unit (like dollars).
225
227 Finance::Quote respects all environment that your installed version of
228 LWP::UserAgent respects. Most importantly, it respects the http_proxy
229 environment variable.
230
232 There are no ways for a user to define a failover list.
233 The two-dimensional hash is a somewhat unwieldly method of passing
235 around information when compared to references. A future release is
236 planned that will allow for information to be returned in a more flexi‐
237 ble $hash{$stock}{$label} style format.
238 There is no way to override the default behaviour to cache currency
240 conversion rates.
241
243 Copyright 1998, Dj Padzensky
244 Copyright 1998, 1999 Linas Vepstas
245 Copyright 2000, Yannick LE NY (update for Yahoo Europe and YahooQuote)
246 Copyright 2000-2001, Paul Fenwick (updates for ASX, maintainence and release)
247 Copyright 2000-2001, Brent Neal (update for TIAA-CREF)
248 Copyright 2000 Volker Stuerzl (DWS and VWD support)
249 Copyright 2000 Keith Refson (Trustnet support)
250 Copyright 2001 Rob Sessink (AEX support)
251 Copyright 2001 Leigh Wedding (ASX updates)
252 Copyright 2001 Tobias Vancura (Fool support)
253 Copyright 2001 James Treacy (TD Waterhouse support)
254 This program is free software; you can redistribute it and/or modify it
256 under the terms of the GNU General Public License as published by the
257 Free Software Foundation; either version 2 of the License, or (at your
258 option) any later version.
259 Currency information fetched through this module is bound by Yahoo!'s
261 terms and conditons.
262 Other copyrights and conditions may apply to data fetched through this
264 module. Please refer to the sub-modules for further information.
265
267 Dj Padzensky (C<djpadz@padz.net>), PadzNet, Inc.
268 Linas Vepstas (C<linas@linas.org>)
269 Yannick LE NY (C<y-le-ny@ifrance.com>)
270 Paul Fenwick (C<pjf@schools.net.au>)
271 Brent Neal (C<brentn@users.sourceforge.net>)
272 Volker Stuerzl (C<volker.stuerzl@gmx.de>)
273 Keith Refson (C<Keith.Refson#earth.ox.ac.uk>)
274 Rob Sessink (C<rob_ses@users.sourceforge.net>)
275 Leigh Wedding (C<leigh.wedding@telstra.com>)
276 Tobias Vancura (C<tvancura@altavista.net>)
277 James Treacy (C<treacy@debian.org>)
278 The Finance::Quote home page can be found at
280 http://finance-quote.sourceforge.net/
281 The Finance::YahooQuote home page can be found at
283 http://www.padz.net/~djpadz/YahooQuote/
284 The GnuCash home page can be found at http://www.gnucash.org/
286
288 Finance::Quote::AEX, Finance::Quote::ASX, Finance::Quote::Cdnfundli‐
289 brary, Finance::Quote::DWS, Finance::Quote::Fidelity,
290 Finance::Quote::FinanceCanada, Finance::Quote::Fool,
291 Finance::Quote::FTPortfolios, Finance::Quote::Tdefunds,
292 Finance::Quote::Tdwaterhouse, Finance::Quote::Tiaacref,
293 Finance::Quote::Troweprice, Finance::Quote::Trustnet,
294 Finance::Quote::VWD, Finance::Quote::Yahoo::Australia,
295 Finance::Quote::Yahoo::Europe, Finance::Quote::Yahoo::USA, LWP::UserA‐
296 gent
297 You should have also received the Finance::Quote hacker's guide with
299 this package. Please read it if you are interested in adding extra
300 methods to this package. The hacker's guide can also be found on the
301 Finance::Quote website, http://finance-quote.sourceforge.net/
302perl v5.8.8 2007-01-08 Finance::Quote(3)