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 deprecated, 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
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 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 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 To install this module, run the following commands:
86 perl Makefile.PL
88 make
89 make test
90 make install
91 For more detailed instructions, please see the INSTALL file.
93
95 After installing, you can find documentation for this module with the
96 perldoc command.
97 perldoc Finance::Quote
99 You can also look for information at:
101 RT, CPAN's request tracker
103 http://rt.cpan.org/NoAuth/Bugs.html?Dist=Finance-Quote
104 AnnoCPAN, Annotated CPAN documentation
106 http://annocpan.org/dist/Finance-Quote
107 CPAN Ratings
109 http://cpanratings.perl.org/d/Finance-Quote
110 Search CPAN
112 http://search.cpan.org/dist/Finance-Quote
113 The Finance::Quote home page
115 http://finance-quote.sourceforge.net/
116 The Finance::YahooQuote home page
118 http://www.padz.net/~djpadz/YahooQuote/
119 The GnuCash home page
121 http://www.gnucash.org/
122
124 NEW
125 my $q = Finance::Quote->new;
126 my $q = Finance::Quote->new("ASX");
127 my $q = Finance::Quote->new("-defaults", "CustomModule");
128 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 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 Note that the FQ_LOAD_QUOTELET environment variable must begin with
143 "-defaults" if you wish the default modules to be loaded.
144 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 Please read the Finance::Quote hacker's guide for information on how to
150 create new modules for Finance::Quote.
151 FETCH
153 my %stocks = $q->fetch("usa","IBM","MSFT","LNUX");
154 my $hashref = $q->fetch("usa","IBM","MSFT","LNUX");
155 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 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 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 The fetch method automatically arranges for failover support and
179 currency conversion if requested.
180 If you wish to fetch information from only one particular source, then
182 consult the documentation of that sub-module for further information.
183 SOURCES
185 my @sources = $q->sources;
186 my $listref = $q->sources;
187 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 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 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 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 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 CURRENCY
215 $conversion_rate = $q->currency("USD","AUD");
216 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 The currency method will return a false value if a given currency
223 conversion cannot be fetched.
224 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 SET_CURRENCY
230 $q->set_currency("FRF"); # Get results in French Francs.
231 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 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 FAILOVER
245 $q->failover(1); # Set automatic failover support.
246 $q->failover(0); # Disable failover support.
247 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 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 USER_AGENT
260 my $ua = $q->user_agent;
261 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 $q->user_agent->timeout(10); # Set the timeout directly.
268 SCALE_FIELD
270 my $pounds = $q->scale_field($item_in_pence,0.01);
271 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 ISOTIME
280 $q->isoTime("11:39PM"); # returns "23:39"
281 $q->isoTime("9:10 AM"); # returns "09:10"
282 This function will return a isoformatted time
284
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
291 There are no ways for a user to define a failover list.
292 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 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 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 Currency information fetched through this module is bound by Yahoo!'s
321 terms and conditons.
322 Other copyrights and conditions may apply to data fetched through this
324 module. Please refer to the sub-modules for further information.
325
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 The Finance::Quote home page can be found at
342 http://finance-quote.sourceforge.net/
343 The Finance::YahooQuote home page can be found at
345 http://www.padz.net/~djpadz/YahooQuote/
346 The GnuCash home page can be found at http://www.gnucash.org/
348
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 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/
364perl v5.32.1 2021-01-27 Finance::Quote(3)