LABELS¶

When information about a stock is returned, the following standard labels may be used. Some custom-written modules may use labels not mentioned here. If you wish to be certain that you obtain a certain set of labels for a given stock, you can specify that using require_labels().

    ask          Ask
    avg_vol      Average Daily Vol
    bid          Bid
    cap          Market Capitalization
    close        Previous Close
    currency     Currency code for the returned data
    date         Last Trade Date  (MM/DD/YY format)
    day_range    Day's Range
    div          Dividend per Share
    div_date     Dividend Pay Date
    div_yield    Dividend Yield
    eps          Earnings per Share
    errormsg     If success is false, this field may contain the reason why.
    ex_div       Ex-Dividend Date.
    exchange     The exchange the information was obtained from.
    high         Highest trade today
    isin         International Securities Identification Number
    isodate      ISO 8601 formatted date 
    last         Last Price
    low          Lowest trade today
    method       The module (as could be passed to fetch) which found this information.
    name         Company or Mutual Fund Name
    nav          Net Asset Value
    net          Net Change
    open         Today's Open
    p_change     Percent Change from previous day's close
    pe           P/E Ratio
    success      Did the stock successfully return information? (true/false)
    time         Last Trade Time
    type         The type of equity returned
    volume       Volume
    year_range   52-Week Range
    yield        Yield (usually 30 day avg)

If all stock lookups fail (possibly because of a failed connection) then the empty list may be returned, or undef in a scalar context.

new¶

    my $q = Finance::Quote->new()
    my $q = Finance::Quote->new('-defaults')
    my $q = Finance::Quote->new(timeout => 30)
    my $q = Finance::Quote->new('YahooJSON', fetch_currency => 'EUR')
    my $q = Finance::Quote->new('alphavantage' => {API_KEY => '...'})
    my $q = Finance::Quote->new('IEXCloud', 'iexcloud' => {API_KEY => '...'});
    my $q = Finance::Quote->new(currency_rates => {order => ['ECB', 'Fixer'], 'fixer' => {API_KEY => '...'}});

Finance::Quote modules access a wide range of sources to provide quotes. A module provides one or more methods to fetch quotes. One method is usually the name of the module in lower case. Other methods, if provided, are descriptive names, such as 'canada', 'nasdaq', or 'nyse'.

A Finance::Quote object uses one or more methods to fetch quotes for securities.

"new" constructs a Finance::Quote object and enables the caller to load only specific modules, set parameters that control the behavior of the fetch method, and pass method specific parameters.

"timeout =" T> sets the web request timeout to "T" seconds

"failover =" B> where "B" is a boolean value indicating if failover in fetch is permitted

"fetch_currency =" C> sets the desired currency code to "C" for fetch results

"currency_rates =" H> configures the order currency rate modules are consulted for exchange rates and currency rate module options

"required_labels =" A> sets the required labels for fetch results to array "A"

"<ModuleName"> as a string is the name of a specific Finance::Quote::Module to load

"<methodname" => H> passes hash "H" to methodname during fetch to configure the method

With no arguments, "new" creates a Finance::Quote object with the default methods. If the environment variable FQ_LOAD_QUOTELET is set, then the contents of FQ_LOAD_QUOTELET (split on whitespace) will be used as the argument list. This allows users to load their own custom modules without having to change existing code. If any method names are passed to "new" or the flag '-defaults' is included in the argument list, then FQ_LOAD_QUOTELET is ignored.

When new() is passed one or more class name arguments, an object is created with only the specified modules loaded. If the first argument is '-defaults', then the default modules will be loaded first, followed by any other specified modules. Note that the FQ_LOAD_QUOTELET environment variable must begin with '-defaults' if you wish the default modules to be loaded.

Method names correspond to the Perl module in the Finance::Quote module space. For example, "Finance::Quote-"new('ASX')> will load the module Finance::Quote::ASX, which provides the method "asx".

Some methods require API keys or have unique options. Passing 'method => HASH' to new() enables the caller to provide a configuration HASH to the corresponding method.

The key 'currency_rates' configures the Finanace::Quote currency rate conversion. By default, to maintain backward compatibility, Finance::Quote::CurrencyRates::AlphaVantage is used for currency conversion. This end point requires an API key, which can either be set in the environment or included in the configuration hash. To specify a different primary currency conversion method or configure fallback methods, include the 'order' key, which points to an array of Finance::Quote::CurrencyRates module names. Setting the environment variable FQ_CURRENCY will change the default endpoint used for currency conversion. See the documentation for the individual Finance::Quote::CurrencyRates modules to learn more.

get_default_currency_fields¶

    my @fields = Finance::Quote::get_default_currency_fields();

"get_default_currency_fields" returns the standard list of fields in a quote that are automatically converted during currency conversion. Individual modules may override this list.

get_default_timeout¶

    my $value = Finance::Quote::get_default_timeout();

"get_default_timeout" returns the current Finance::Quote default timeout in seconds for web requests. Finance::Quote does not specify a default timeout, deferring to the underlying user agent for web requests. So this function will return undef unless "set_default_timeout" was previously called.

set_default_timeout¶

    Finance::Quote::set_default_timeout(45);

"set_default_timeout" sets the Finance::Quote default timeout to a new value.

get_methods¶

    my @methods = Finance::Quote::get_methods();

"get_methods" returns the list of methods that can be passed to "new" when creating a quoter object and as the first argument to "fetch".

get_features¶

    my %features = Finance::Quote::get_features();

"get_features" returns a hash with three keys: quote_methods, quote_modules, and currency_modules.

    $features{quote_methods} is a hash with key/value pairs of method_name => [array of module names]
    $features{quote_modules} is a hash with key/value pairs of module_name => [array of parameter names]
    $features{currency_modules} is a hash with key/value pairs of currency_module_name => [array of paramater names]

Parameter names are values that the module needs to function, such as API_KEY. Most modules will have an empty list. Modules with a parameter are configured when creating the Finance::Quote by passing the argument

   'module_name_in_lower_case' => {paramter => value}

to Finance::Quote->new().

The keys of the $features{currency_modules} hash are the names of currency modules that can be used for currency conversion and the order in which the modules are used is controlled by the argument

    currency_rates => {order => [subset of $features{currency_modules}]}

to Finance::Quote->new(). By default, AlphaVantage in used for currency conversion, "order" can be set to use other currency modules. The currency module used can also be changed by setting the FQ_CURRENCY environment variable. Please note that some of the alternate currency modules require API keys.

B_to_billions¶

    my $value = $q->B_to_billions("20B");

"B_to_billions" is a utility function that expands a numeric string with a "B" suffix to the corresponding multiple of 1000000000.

decimal_shiftup¶

    my $value = $q->decimal_shiftup("123.45", 1);  # returns 1234.5
    my $value = $q->decimal_shiftup("0.25", 1);    # returns 2.5

"decimal_shiftup" moves a the decimal point in a numeric string the specified number of places to the right.

fetch¶

    my %stocks  = $q->fetch("alphavantage", "IBM", "MSFT", "LNUX");
    my $hashref = $q->fetch("nasdaq", "IBM", "MSFT", "LNUX");

"fetch" takes a method as its first argument and the remaining arguments are treated as securities. If the quoter $q was constructed with a specific method or methods, then only those methods are available.

When called in an array context, a hash is returned. In a scalar context, a reference to a hash will be returned. The keys for the returned hash are "{SECURITY,LABEL}". For the above example call, $stocks{"IBM","high"} is the high value for IBM.

$q->get_methods() returns the list of valid methods for quoter object $q. Some methods specify a specific Finance::Quote module, such as 'alphavantage'. Other methods are available from multiple Finance::Quote modules, such as 'nasdaq'. The quoter failover over option determines if multiple modules are consulted for methods such as 'nasdaq' that more than one implementation.

get_failover¶

    my $failover = $q->get_failover();

Failover is when the "fetch" method attempts to retrieve quote information for a security from alternate sources when the requested method fails. "get_failover" returns a boolean value indicating if the quoter object will use failover or not.

set_failover¶

    $q->set_failover(False);

"set_failover" sets the failover flag on the quoter object.

get_fetch_currency¶

    my $currency = $q->get_fetch_currency();

"get_fetch_currency" returns either the desired currency code for the quoter object or undef if no target currency was set during construction or with the "set_fetch_currency" function.

set_fetch_currency¶

    $q->set_fetch_currency("FRF");  # Get results in French Francs.

"set_fetch_currency" method is used to request that all information be returned in the specified currency. Note that this increases the chance stock-lookup failure, as remote requests must be made to fetch both the stock information and the currency rates. In order to improve reliability and speed performance, currency conversion rates are cached and are assumed not to change for the duration of the Finance::Quote object.

See the introduction to this page for information on how to configure the source of currency conversion rates.

get_required_labels¶

    my @labels = $q->get_required_labels();

"get_required_labels" returns the list of labels that must be populated for a security quote to be considered valid and returned by "fetch".

set_required_labels¶

    my $labels = ['close', 'isodate', 'last'];
    $q->set_required_labels($labels);

"set_required_labels" updates the list of required labels for the quoter object.

get_timeout¶

    my $timeout = $q->get_timeout();

"get_timeout" returns the timeout in seconds the quoter object is using for web requests.

set_timeout¶

    $q->set_timeout(45);

"set_timeout" updated the timeout in seconds for the quoter object.

store_date¶

    $quoter->store_date(\%info, $stocks, {eurodate => '06/11/2020'});

"store_date" is used by modules to consistent store date information about securities. Given the various pieces of a date, this function figures out how to construct a ISO date (yyyy-mm-dd) and US date (mm/dd/yyyy) and stores those values in %info for security $stock.

get_user_agent¶

    my $ua = $q->get_user_agent();

"get_user_agent" returns the LWP::UserAgent the quoter object is using for web requests.

isoTime¶

    $q->isoTime("11:39PM");    # returns "23:39"
    $q->isoTime("9:10 AM");    # returns "09:10"

"isoTime" returns an ISO formatted time.

scale_field¶

    my $value = Finance::Quote->scale_field('1023', '0.01')

"scale_field" is a utility function that scales the first argument by the second argument. In the above example, "value" is '10.23'.

currency¶

    my $value = $q->currency('15.95 USD', 'AUD');
    my $value = Finance::Quote->currency('23.45 EUR', 'RUB');

"currency" converts a value with a currency code suffix to another currency using the current exchange rate as determined by the Finance::Quote::CurrencyRates method or methods configured for the quoter $q. When called as a class method, Finance::Quote::AlphaVantage is the default, which requires an API key. See the introduction for information on configuring currency rate conversions and see Finance::Quote::CurrencyRates::AlphaVantage for information about the API key.

currency_lookup¶

    my $currency = $quoter->currency_lookup();
    my $currency = $quoter->currency_lookup( name => "Caribbean");
    my $currency = $quoter->currency_loopup( country => qw/denmark/i );
    my $currency = $q->currency_lookup(country => qr/united states/i, number => 840);

"currency_lookup" takes zero or more constraints and filters the list of currencies known to Finance::Quote. It returns a hash reference where the keys are ISO currency codes and the values are hash references containing metadata about the currency.

A constraint is a key name and either a scalar or regular expression. A currency satisfies the constraint if its metadata hash contains the constraint key and the value of that metadata field matches the regular expression or contains the constraint value as a substring. If the metadata field is an array, then it satisfies the constraint if any value in the array satisfies the constraint.

parse_csv¶

    my @list = Finance::Quote::parse_csv($string);

"parse_csv" is a utility function for splitting a comma separated value string into a list of terms, treating double-quoted strings that contain commas as a single value.

parse_csv_semicolon¶

    my @list = Finance::Quote::parse_csv_semicolon($string);

"parse_csv" is a utility function for splitting a semicolon separated value string into a list of terms, treating double-quoted strings that contain semicolons as a single value.

default_currency_fields¶

Replaced with get_default_currency_fields().

sources¶

Replaced with get_methods().

failover¶

Replaced with get_failover() and set_failover().

require_labels¶

Replaced with get_required_labels() and set_required_labels().

user_agent¶

Replaced with get_user_agent().

set_currency¶

Replaced with get_fetch_currency() and set_fetch_currency().