Difference between revisions of "Online Quotes"

Revision as of 19:14, 4 July 2023

GnuCash can automatically retrieve the current currency exchange rates and share price of marketable commodities (such as stocks and mutual funds) - often simply called "quotes" - so that you do not need to manually enter and update them in the GnuCash Price Database one at a time. If you are tracking the prices of more than a handful of securities, this features saves an enormous amount of time.

Before you continue read the Official Documentation:

Manual

Setting Up the Quote Retrieval,

Steps to enable Online Quotes updating per account;

We try to reduce redundancy.

Overview

GnuCash stores the share prices of investments in the respective buy/sell/split transactions, currency exchange rates and additional quotes in an internal price database. Although it is possible to enter prices manually into the price database, it is more convenient to update them from online sources. GnuCash uses an external program written in the Perl programming language called Finance::Quote (often shortened to simply F::Q) to fetch these quotes online. Therefore, for this feature of GnuCash to work, your computer will need to have some additional software installed beyond simply the GnuCash application itself, as well as have an active Internet connection.

F::Q uses source AlphaVantage for all currency exchange rates.

About Finance::Quote

The Finance::Quote Perl module is

managed at GitHub and

has a SourceForge website.

Most linux distributions have packages for recent versions in their own repositories (e.g., dnf install perl-Finance-Quote). In addition for all platforms downloads are available

like for other Perl modules at CPAN (both recent),

and additionally at SourceForge project.

You can report issues

at their bugtracker

or if unsure discuss them on their devel-mailing list at SF.

https://rt.cpan.org/Public/Dist/Display.html?Status=Active&Name=Finance-Quote was the old tracker.

However, please be reasonably confident that the problem truly lies in the Finance::Quote software and not somewhere else (e.g., could your Internet connection simply be down right now?) before you submit a bug report to the Finance::Quote developers.

The Finance::Quote software gathers its price data from several Web sites around the world that provide this information in different ways. Some sources offer

• an API like JSON or YQL^[1],
• downloads, usually as CSV file, and finally,
• quite literally by extracting information from the web page itself.

As these sources change frequently, we advise you to keep Finance::Quote up-to-date.

Setting up online quotes in GnuCash

The GnuCash Guide includes instructions on setting up online quotes. This set up procedure provides the input to Finance::Quote, so it must be completed before the "Get Quotes" button in GnuCash's Price Database will have any effect.

Below are some extra caveats to keep in mind:

Note

The examples below use the command line syntax for GnuCash 5.0 and up. Users of older GnuCash versions can uuse the gnc-fq-dump helper script instead. More on this further down.

1. The symbol depends on the source:

   $ gnucash-cli --quotes dump currency USD EUR
   1 EUR = 1.1004732 USD
   $ gnucash-cli -V --quotes dump yahoo_json USD
   USD:
           high => 25.7606
           open => 25.2
          close => 24.88
           last => 25.7606
     year_range =>        11.65 - 29.65
            low => 24.99
        isodate => 2023-05-05
           date => 05/05/2023
           name => USD (ProShares Ultra Semiconductors)
        success => 1
      div_yield => 0
       exchange => Sourced from Yahoo Finance (as JSON)
         method => yahoo_json
         symbol => USD
       currency => USD
           type => ETF
         volume => 20348
             pe => null
            eps => null
   

   Ultra Semiconductors ≠ US Dollar
2. Some special characters like & get interpreted by your command shell. For example using "M&M.NS" unquoted would fetch the quote for "M" instead and treat "M.NS" as a separate shell command.

   $ gnucash-cli -V --quotes dump yahoo_json M&M.NS
   [1] 1732
   If 'M.NS' is not a typo you can use command-not-found to lookup the package that contains it, like this:
       cnf M.NS
   M:
         method => yahoo_json
        isodate => 2023-05-05
           last => 15.12
         volume => 3446273
         symbol => M
           type => EQUITY
           open => 15
           date => 05/05/2023
           high => 15.2873
     year_range =>        14.48 - 25.12
          close => 14.75
             pe => 3.7425742
       currency => USD
        success => 1
            eps => 4.04
      div_yield => 4.2711865
            low => 14.92
       exchange => Sourced from Yahoo Finance (as JSON)
           name => M (Macy's Inc)
   

   Escaping by backslash correctly returns the result for M&M.NS (this was not working with gnc-fq-dump in prior versions!)

   $ gnucash-cli -V --quotes dump yahoo_json M\&M.NS
   M&M.NS:
            eps => null
             pe => null
            low => 1208.05
       exchange => Sourced from Yahoo Finance (as JSON)
       currency => INR
         volume => 4753303
           last => 1211.2
           high => 1242.35
         symbol => M&M.NS
           type => EQUITY
           open => 1232.8
           name => M&M.NS (MAHINDRA &MAHINDRA)
     year_range =>        853.7 - 1397
      div_yield => 0
         method => yahoo_json
           date => 05/05/2023
        success => 1
        isodate => 2023-05-05
          close => 1231.7
   

   Percent-encoding also gets the right result, though it returns slightly less readable data (and this was the only option that worked with gnc-fq-dump in prior versions)

   $ gnucash-cli -V --quotes dump yahoo_json 'M%26M.NS'
   M%26M.NS:
            eps => null
      div_yield => 0
       currency => INR
           name => M%26M.NS (MAHINDRA &MAHINDRA)
            low => 1208.05
             pe => null
        isodate => 2023-05-05
           open => 1232.8
       exchange => Sourced from Yahoo Finance (as JSON)
           last => 1211.2
         method => yahoo_json
         volume => 4753303
     year_range =>        853.7 - 1397
           date => 05/05/2023
        success => 1
           type => EQUITY
          close => 1231.7
         symbol => M%26M.NS
           high => 1242.35
   

Command line interface

GnuCash also offers a command line tool called "gnucash-cli" that can interact directly with Finance::Quote.

Note

Prior to gnucash 5.0 this command line tool was pretty limited with regards to quotes. It could only update quotes in an existing book. For more interaction these releases shipped a few helper scripts. These are documented in #Obsolete scripts.

gnucash-cli has the following quotes related subcommands:

gnucash-cli --quotes get <book>

This command opens datafile <book> and attempts to retrieve the most recent price for each quote in it via Finance::Quote. This command was actually introduced already in gnucash 4.0. In older versions still the gnucash application itself had the option --add-price-quotes to the same effect. This option has now been removed from gnucash 5.0 in favour of the gnucash-cli command instead.

Note

GnuCash 5.0 had a bug in this command, which has been fixed in GnuCash 5.1. To make it work with GnuCash 5.0 you need to add an extra double-dash between get and <book> like so:

$ gnucash-cli --quotes get -- <book>

There is a space between '--' and <book> here!

gnucash-cli --quotes info

$ gnucash-cli --quotes info
Found Finance::Quote version 1.54.
Finance::Quote sources:
aex          alphavantage              amfiindia    asegr        asx          
aufunds      australia    bamosz       bet          bloomberg    bourso       
bse          bseindia     canada       canadamutual              comdirect    
cse          deka         dutch        dwsfunds     europe       
fetch_live_currencies     fidelity     fidelity_direct           
finanzpartner             fondsweb     fool         france       ftfunds      
fundata      fundlibrary  goldmoney    greece       hu           hufund       
hungary      hustock      iexcloud     india        indiamutual  
known_currencies          morningstarau             morningstarch             
morningstarjp             mstaruk      nasdaq       nseindia     nyse         
nzx          onvista      oslobors     romania      seb_funds    sinvestor    
six          tesouro_direto            tiaacref     tmx          tradegate    
tradeville   treasurydirect            troweprice   troweprice_direct         
tsp          tsx          ukfunds      unionfunds   usa          xetra        
yahoo_json   za

$ gnucash-cli --quotes info
Failed to initialize Finance::Quote: Can't locate JSON.pm in @INC (you may need to install the JSON module) (@INC contains: /usr/local/lib64/perl5/5.36 /usr/local/share/perl5/5.36 /usr/lib64/perl5/vendor_perl /usr/share/perl5/vendor_perl /usr/lib64/perl5 /usr/share/perl5) at /home/janssege/Development/gnucash/stable/build/bin/finance-quote-wrapper line 277.
BEGIN failed--compilation aborted at /home/janssege/Development/gnucash/stable/build/bin/finance-quote-wrapper line 277.

Note

The most recent Finance::Quote version is 1.63.

gnucash-cli --quotes dump

This command returns quote data for a source and a list of symbols in a format which is easy to read for humans. It is useful for checking that a given online quote source is online and functional.

gnucash-cli -V --quotes dump $SOURCE $SYMBOL
# e.g.
gnucash-cli -V --quotes dump alphavantage IBM

Note

The -V parameter is optional. If omitted only the tags relevant to use within gnucash will be printed:

$ gnucash-cli --quotes dump alphavantage IBM
Finance::Quote fields GnuCash uses:
    symbol: IBM             <=== required
      date: 05/04/2023      <=== recommended
  currency: USD             <=== required
      last: 122.5700        <=\ 
       nav:                 <=== one of these
     price:                 <=/

If the command is run with the -V parameter, all tags retrieved from Finance::Quote are printed:

$ gnucash-cli -V --quotes dump alphavantage IBM 2>/dev/null
IBM:
         net => -0.8800
        date => 05/04/2023
      volume => 4468237
     isodate => 2023-05-04
        high => 123.5200
    currency => USD
      symbol => IBM
    p_change => -0.7128
      method => alphavantage
     success => 1
       close => 123.4500
        open => 123.0300
currency_set_by_fq => 1
         low => 121.7563
        last => 122.5700

gnucash-cli  --quotes dump currency USD EUR

But it is still possible to get the rate between 2 currencies AAA and BBB using source Yahoo as JSON:

gnucash-cli --quotes dump yahoo_json ${AAA}${BBB}=X
# e.g.
gnucash-cli -V --quotes dump yahoo_json USDEUR=X

Helper Scripts

Note

All helper scripts mentioned in this section are Perl scripts. Before you can use them you must have a functioning Perl installation on your system.

gnc-fq-update

As stated earlier, Finance::Quote is external to GnuCash and hence managed independently of GnuCash. Linux distributions typically make it easy: you can usually download Finance::Quote from their package repositories. For MacOS and Windows a different approach is needed.

To help with installing and updating on these platforms, GnuCash comes with a helper script called gnc-fq-update which installs or updates the Finance::Quote software module along with its dependencies.

Notes

• This program needs superuser or administrative privileges to succeed in Linux or macOS but not in Windows 10.
• If you want to use this script on Linux to install a more recent Finance::Quote module than is shipped by your distribution, you may want to uninstall the system package first to avoid any conflicts.
• Technically it is a Perl script which calls CPAN.

Note for Microsoft Windows users to run Perl scripts like gnc-fq-update

Unixoid operating systems use a shebang (#!) to associate Perl scripts with the Perl interpreter. Windows, on the other hand, makes no such association. Attempting to execute Perl scripts by directly calling them will fail, as shown below.

C:\> gnc-fq-check
gnc-fq-check is not recognized as an internal or external command, operable program or batch file

In order to run Perl scripts on Windows, use the following:

1. Open a command line window:

   Windows 10 (not in Tablet Mode)

   Click in the Cortana Ask me anything field to the right of Start Button, begin typing cmd, a search menu should appear. The menu should display Command Prompt. Left-click or tap the Command Prompt icon.

   Windows 8 (or Windows 10 in Tablet Mode)

   From the Start screen, begin typing cmd, a search menu should appear. The menu should display Command Prompt. Left-click or tap the Command Prompt icon.

   Windows 7

   Click Start Button → type cmd in the Search programs and files field, press Enter

   Windows XP

   Click Start Button → All Programs → Accessories → Command Prompt

2. Change to the drive containing the GnuCash program files (usually C drive) if that is not already the current drive:

   C:
   

3. Change to the ...\gnucash\bin directory which contains the required gnc-fq-xxx Perl scripts:

   32 bit version of Windows

   cd \Program Files\gnucash\bin
   

   64 bit version of Windows

   cd \Program Files (x86)\gnucash\bin
   

4. Prefix any gnc-fq-xxx Perl script command with Perl and a space:

   perl gnc-fq-check
   

Obsolete scripts

GnuCash 5.0 introduces several extra command line options in gnucash-cli to interface with Finance::Quote. These are explained in #Command line interface. Prior to that release, GnuCash provided a few extra helper scripts to achieve the same. While no longer available for GnuCash 5.0 and later, they are still mentioned here for historical interest.

gnc-fq-check

This program returns the version number of Finance::Quote module currently installed as well as a list of sources available via the Finance::Quote module. It will also inform you if there is a problem with your Finance::Quote installation or if it is missing, and may suggest a fix.

Example with broken dependency

$ gnc-fq-check 
Can't locate Mozilla/CA.pm in @INC (you may need to install the Mozilla::CA module) (@INC contains: /usr/lib/perl5/site_perl/5.30.1/x86_64-linux-thread-multi /usr/lib/perl5/site_perl/5.30.1 /usr/lib/perl5/vendor_perl/5.30.1/x86_64-linux-thread-multi /usr/lib/perl5/vendor_perl/5.30.1 /usr/lib/perl5/5.30.1/x86_64-linux-thread-multi /usr/lib/perl5/5.30.1 /usr/lib/perl5/site_perl) at /usr/lib/perl5/vendor_perl/5.30.1/Finance/Quote/Tiaacref.pm line 33.
Compilation failed in require at (eval 303) line 1.
BEGIN failed--compilation aborted at (eval 303) line 1.
 at /usr/local/bin/gnc-fq-check line 91.
("1.47" "adig" "aex" "aiahk" "alphavantage" "amfiindia" "asegr" "asia" "asx" "australia" "bamosz" "bet" "bmonesbittburns" "bourso" "brasil" "bse" "bsero" "canada" "canadamutual" "citywire" "cominvest" "cse" "deka" "dutch" "dwsfunds" "europe" "fetch_live_currencies" "fidelity" "fidelity_direct" "fidelityfixed" "financecanada" "finanzpartner" "finland" "fool" "france" "ftfunds" "ftportfolios" "ftportfolios_direct" "fundlibrary" "goldmoney" "greece" "hex" "hu" "hufund" "hungary" "hustock" "indiamutual" "known_currencies" "lerevenu" "maninv" "morningstar" "morningstarjp" "mstaruk" "nasdaq" "nyse" "nz" "nzx" "platinum" "romania" "seb_funds" "sixfunds" "sixshares" "stockhousecanada_fund" "tdefunds" "tdwaterhouse" "tiaacref" "tnetuk" "troweprice" "troweprice_direct" "trustnet" "tsp" "tsx" "uk_unit_trusts" "ukfunds" "unionfunds" "usa" "usfedbonds" "vanguard" "vwd" "yahoo" "yahoo_asia" "yahoo_australia" "yahoo_brasil" "yahoo_europe" "yahoo_json" "yahoo_nz" "yahoo_yql" "za" "za_unittrusts")

The first part is the error message about a missing Mozilla/CA.pm.

At the end in parentheses is the normal output of the currently installed Finance::Quote version and a list of available sources.

Note: The most recent Finance::Quote version is 1.63.

If an error is displayed, see the next section gnc-fq-update. Otherwise, continue with gnc-fq-dump.

gnc-fq-dump

This program returns quote data for a source and a list of symbols in a format which is easy to read for humans. It is useful for checking that a given online quote source is online and functional.

To get a stock price, run a command from the command line of the form:

gnc-fq-dump -v $SOURCE $SYMBOL
# e.g.
gnc-fq-dump -v alphavantage IBM

Since Finance::Quote 1.41 the default source for currencies is hardcoded to be Alpha Vantage, e.g.

gnc-fq-dump currency USD EUR

But it is still possible to get the rate between 2 currencies AAA and BBB using source Yahoo as JSON:

gnc-fq-dump -v yahoo_json ${AAA}${BBB}=X
# e.g.
gnc-fq-dump -v yahoo_json USDEUR=X

To test that Finance::Quote is working for currencies within GnuCash,

1. find a two-currency transaction and
2. right-click on it, then
3. select Edit Exchange Rate in the context menu.

The transfer dialog will appear. Click the Fetch Rate button and if everything is behaving itself the current rate will fill in the exchange rate box.

gnc-fq-helper

This script is the interface between GnuCash and Finance::Quote and primarily intended to be used by GnuCash internally. It does more or less what gnc-fq-dump does, but in a form which the program understands. Input and output are Scheme expressions.

Requirements

This section describes the software installation required for GnuCash's online quote feature to work. Briefly, in addition to the GnuCash application itself, you will need to install Perl and its Finance::Quote module.

Perl

The Finance::Quote module relies on Perl, so Perl must be installed first. The procedure for installing Perl is handled differently on different operating systems.

Installing Perl on Unix

On most Unix-like operating systems (Linux, AIX, *BSD, HPUX, Solaris, etc.), Perl is probably already installed. If it is not, but your Unix-like operating system has a package manager, it will likely be installed automatically as a dependency of Finance::Quote.

To check if Perl is installed, invoke the perl -v command at a terminal prompt to get the Perl interpreter's version number. If that fails, the best bet is to use your package manager to install it. Refer to your operating system's documentation for additional details on using your package manager.

The GnuCash Flatpak has a working perl and Finance::Quote already installed. You will need to add your Alpha Vantage API key if you require currency conversion rates or to use Alpha Vantage as a price source. If you need to get currency conversion rates, you need Finance::Quote version 1.53 or later which was first included in the GnuCash 4.12-1 Flatpak. If you need a more recent version of F::Q than is included in the latest GnuCash Flatpak, you should wait until the GnuCash developers incorporate the version you need in the GnuCash Flatpak as it is not easy to update F::Q in the Flatpak because it doesn't contain the tools CPAN needs.

Installing Perl on macOS

perl -v

Installing Perl on Windows

The way to do this is slightly different depending on the version of GnuCash.

GnuCash 2.5 and more recent

Everything is done for you by running the "Install Online Price Retrieval" command. You can find this in the Windows start menu under the GnuCash group. This will install Strawberry perl and all the perl modules required to run Finance::Quote.

• With typical Windows 10 security, you need Administrator privileges to install perl.

After you initiate "Install Online Price Retrieval", a User Access Control window will appear

if you are an Administrator

to confirm you intend to install software , or

else

to enable you to enter the credentials of an administrative user.

• Installation can take from 15 minutes to several hours or more depending on the speed of your PC and internet connection.

No such file or directory or permission denied errors while installing Strawberry perl:

Turning of anti-virus software while installing perl may help.

This issue was reported to McAfee as Service Request number 1446848354 16 Mar 2014.

GnuCash 2.4 and before

These GnuCash releases only work with ActivePerl, which you first have to install manually.

• If you are upgrading from an earlier version of ActivePerl, uninstall the old version and delete its directory before installing the new one.
• Download and install it from ActiveState. ActivePerl versions before 5.16.3 may not deliver the latest version of F::Q (1.18 as of this writing). The 32-bit version is recommended, even on 64-bit Windows, but success has also been achieved running the 64 bit version under Windows XP Pro x64 SP2 with both GC 2.4.11 and 2.4.12(YMMV). If prompted, you don't have to provide contact details, just choose the MSI installer for your system. It is strongly recommended to use the default installation directory.
• Once perl is installed, use the start menu item "Install Online Price Retrieval" from the GnuCash group to install the necessary Perl modules for F::Q and verify the setup.

Because ActivePerl uses their own precompiled perl package manager (PPM) you should - in the case you need to update F::Q - not use the Comprehensive Perl Archive Network (CPAN). Instead you can use the PPM Index: Finance-Quote to see the state and download the latest ppmx they compiled successful.

GnuCash 2.2.6 and before

Installation is similar to the installation for GnuCash 2.4, except that these releases only work with ActivePerl 5.8 and the menu item is called "Install Finance-Quote".

You are advised to upgrade to a more recent version of GnuCash though, because it's unlikely you can get Finance::Quote to work still on these old releases. You will have a hard time finding a version of ActivePerl 5.8 (unless you pay ActiveState for it), and the version of Finance::Quote that comes with this perl version is outdated.

Source: perl.org

Finance::Quote

As mentioned previously, Finance::Quote is a Perl module that must be installed to enable online quote fetching. Finance::Quote, in turn, depends on a number of other Perl modules.

You can check to see if your system has Finance::Quote installed by running the gnc-fq-check helper program after you have installed Perl itself. Alternatively, you can open the "About GnuCash" window (from the menu, choose Help → About, or on macOS, from the menu choose GnuCash → About GnuCash) and look for a line reading Finance::Quote: 1.63 or similar; this screen reports the currently installed version of Finance::Quote (1.63 in the example given), if it can find one. If GnuCash cannot find a Finance::Quote version, this line will read Finance::Quote: -.

The easiest way to install the Finance::Quote software needed for retrieving online price quotes is to use the provided installation tools, or your system's package manager. Both the Windows and macOS GnuCash packages include provided update tools for Finance::Quote, while many Linux distributions provide a standard way to install packages (e.g., the apt program on Debian-based Linux distributions and the dnf tool on RedHat-based Linux distrubtions such as Fedora). These methods are described next.

Installing Finance::Quote on Windows

On a Windows computer, GnuCash provides the Install Online Price Retrieval program, which is located in the GnuCash group in the Start Menu.

• If your computer is in Tablet Mode you must switch to Desktop Mode to see the entry. Or just run

  C:\Program Files (x86)\gnucash\bin\install-fq-mods.cmd
  

Simply click on it to begin the Finance::Quote installation process. You can re-run the Install Online Price Retrieval program as often as you like to ensure the Finance::Quote module remains up to date.

Installing Finance::Quote on macOS

Until GnuCash 3.6, GnuCash provided the FinanceQuote Update app, which was located in the disk image (.dmg file) along with the main GnuCash app itself. When you installed GnuCash by dragging and dropping the GnuCash app icon to a location on your computer's hard drive (like your Applications folder), you could also consider installing the FinanceQuote Update app into the same folder as you installed the main GnuCash app.

Launch the FinanceQuote Update app by double-clicking it to begin the Finance::Quote installation process. You can re-run the FinanceQuote Update app program as often as you like to ensure the Finance::Quote module remains up to date.

Installing Finance::Quote on macOS from a Terminal prompt

New security requirements for macOS 10.14.6 and 10.15.0 put an end to the FinanceQuote Update app. Users must now use Terminal.app to install Finance Quote.

sudo /Applications/Gnucash.app/Contents/Resources/bin/gnc-fq-update

Compiled binaries on Apple Silicon (aka M1 or M2) processors can be native or Intel. The latter run under a special program called Rosetta2 and GnuCash is one such program (because of a bug in WebKit that prevents reports from displaying when GnuCash is built for Apple Silicon). The Perl binaries that Apple supplies are multi-architecture ("universal" in Apple-speak) but left to itself cpan will install only native binaries resulting in GnuCash not being able to use them. You can tell cpan to install Finance::Quote for Intel with

sudo arch -x86_64 /Applications/Gnucash.app/Contents/Resources/bin/gnc-fq-update

but that has risks: If cpan decides to update itself or if you use cpan for other purposes you can wind up with a mix of Apple Silicon and Intel binaries that can break your perl installation. It's better to set the environment variable ARCHFLAGS='-arch arm64 -arch arm64e -arch x86_64' to get cpan to always make universal binaries. To do that for Finance::Quote only you can run

sudo ARCHFLAGS='-arch arm64 -arch arm64e -arch x86_64' /Applications/Gnucash.app/Contents/Resources/bin/gnc-fq-update

but if you use perl for other things you might prefer to set ARCHFLAGS in you shell profile so that cpan always builds universal binaries.

If you've already run cpan or gnc-fq-update without having set ARCHFLAGS you may need to clean /Library/Perl/<perl-version>. There may be several versions in /Library/Perl especially if you've upgraded your macOS from previous versions instead of having a clean install or used the Migration Assistant to load a new Mac from an old one. The only one that matters is the one corresponding to the current version of /usr/bin/perl. To check that run

/usr/bin/perl --version

You can ignore any micro version numbers. A safe way to clean e.g. /Library/Perl/5.30 is

sudo mv /Library/Perl/5.30 /Library/Perl/saved-5.30
sudo mkdir /Library/Perl/5.30
sudo cp /Library/Perl/saved-5.30/AppendToPath /Library/Perl/5.30/

Once you've completed reinstalling all of your extra perl modules you can compare 5.30 and saved-5.30 to make sure you didn't miss anything. Once you're satisfied you can safely delete /Library/Perl/saved-5.30.

Credit for the environment variable belongs to this Stack Overflow answer and it also provides more background. The procedure to clear out cpan-installed modules is from Bug 798928 comment 11.

The gnc-fq-update script always runs the macOS system Perl runtime (/usr/bin/perl), and disregards the Perl installed by package managers. Doing so ensures GnuCash, when launched from Finder, can locate Finance::Quote correctly.

Installing Finance::Quote on Linux

On a Linux computer, the recommended way to install Finance::Quote is by searching in your OS distribution's package manager for finance-quote. Note that your distribution's package maintainer may prefix or suffix the package name with perl, lib, or both. For example, in Ubuntu 18.04 and later, the package is called libfinance-quote-perl. We also recommend that you check the version of Finance::Quote offered by your OS package repositories to ensure it is a recent-enough version.

gnc-fq-update

This will begin the installation procedure for Finance::Quote and all of its dependencies.

Note for (Ubuntu based) distributions

Some of them removed it from the package. In this case you can

1. download it from github e.g. into your personal ~/bin directory,
2. Execute

   $ which perl
   /usr/bin/perl
   

   to get the proper path to your perl executable,
3. In the first line replace @-PERL-@ with that path—here /usr/bin/perl—

   remove the trailing .in from its name and

   mark the file as executable.

A discussion of how to fix it in Ubuntu can be found at gnucash-user/2012-September.

Since GnuCash version 2.6.12, this helper script uses CPAN (see the next section) to install the following Perl modules:

• Date::Manip
• Finance::Quote
• and their dependencies

Installing Finance::Quote using CPAN

CPAN is

1. the Comprehensive Perl Archive Network, which provides a collection of free Perl software (called modules),
2. a program with which you can obtain the perl Finance::Quote module along with all of its dependencies from there.

If the methods listed above for your specific Operating System or distribution fail, you may nevertheless be able to install Finance::Quote by directly interfacing with CPAN yourself.

To do so using CPAN:

sudo perl -MCPAN -e shell
# Either, if F::Q is missing, install it with
  install Finance::Quote
# or, if F::Q is outdated, update it with
  upgrade Finance::Quote
# finally check for Date::Manip
  install Date::Manip
# and exit:
  q

On the first run of cpan it needs some configuration:

$ cpan
CPAN.pm requires configuration, but most of it can be done automatically.
If you answer 'no' below, you will enter an interactive dialog for each
configuration option instead.
 
Would you like to configure as much as possible automatically? [yes]

It is usually safe to accept the defaults.

Sources

FAQ#Q: How do I install Finance::Quote on a Mac?

Windows#Finance::Quote

FAQ#Q: How do I fix a "system error" or "unknown error" when getting stock quotes?

Finding the right Source and Symbol

Not all sources offer all commodities and different sources use different symbols. Common symbols are:

• Ticker symbols: 1-4 character abbreviation of company names, often used for US shares;
• National Security Identification Numbers (NSIN): like CUSIP, often used by national fund companies;
• ISIN: International Security Identification Numbers, at least in the EU they are more and more replacing the different NSINs;
• sometimes completed by an appendix indicating the market place.

If your commodity is a mutual fund and F::Q offers its fund's company as a source (deka, dws, ...) look for the symbol on the mutual fund's website.

If there is a source for its registered exchange (AEX, ASX, ...) do the same.

In other cases google the ISIN to get a list of possible sources.

Global players: Alpha Vantage and Yahoo* are stronger in shares and Morningstar* in funds.

gnucash-cli -V --quote dump <Source> <Symbol>

Source Alphavantage, US

This source was introduced with Finance::Quote version 1.41.

Finance::Quote's alphavantage and currency sources require since then an AlphaVantage API key that you can get free from the AlphaVantage Website. You can set this key in the GnuCash preferences and it will then be used by GnuCash as well as gnucash-cli.

Note

For the obsolete command line scripts like gnc-fq-dump you will need to set an environment variable ALPHAVANTAGE_API_KEY.

Currency Problem in 2022

GnuCash temporarily stopped being able to retrieve currency exchange rates using a free AlphaVantage API key from about Aug 15 2022 because AlphaVantage made the method F::Q used to obtain exchange rates unavailable for free API keys.

F::Q has been modified to work with AlphaVantage free API keys and this is available in F::Q version 1.53 which was released on CPAN Oct 12 2022. Unfortunately in F::Q 1.53, which uses the FX_DAILY API, currency quotes are not available for Crypto and Precious Metals.

F::Q 1.53 has been updated into the GnuCash 4.12-1 Linux Flatpak.

See Bug 798599.

Around Oct 9 2022 AlphaVantage removed the recent requirement that the CURRENCY_EXCHANGE_RATE API require a Premium API Key, so F::Q has reverted the changes in Pull 230 to use FX_DAILY instead of CURRENCY_EXCHANGE_RATE for currency quotes. This is in F::Q 1.54 which was released Dec 27 2022. F::Q 1.54 has not yet been updated into the latest Linux Flatpak.

Some sources are multiple sources. Multiple sources will be tried, until a price is obtained. If you use a multiple source that includes alphavantage, then you should use an AlphaVantage API key. See A.1.3. Finance::Quote Sources - Multiple sources

To use the API key

in Gnucash—the program

it can be entered in:

GnuCash versions since 2.6.20/2.7.4

(in the Program) Edit->Preferences tab Online Quotes;

GnuCash up to 2.6.19/2.7.3

It has to be set in the environment.local file:

1. Quit GnuCash if it's running;
2. you'll need administrator privileges in most cases, see the docs of your OS;
3. use any text editor (Windows users should prefer Notepad to WordPad or Word)and add

   ALPHAVANTAGE_API_KEY=##############
   

   to the environment.local file, substituting your key for "#############".

in the Helper Scripts gnc-fq-dump and gnc-fq-helper

To use Alpha Vantage sources outside of GnuCash, it is necessary to put the ALPHAVANTAGE_API_KEY into your command line's environment like

Linux or macOS

ALPHAVANTAGE_API_KEY=############## gnc-fq-dump alphavantage CSCO

or

export ALPHAVANTAGE_API_KEY=##############
gnc-fq-dump alphavantage CSCO

Windows

cd \Program Files (x86)\gnucash\bin
set ALPHAVANTAGE_API_KEY=##############
gnc-fq-dump alphavantage CSCO

Tip

To have the key available in every session you can also add it to your OS's environment or your command shell configuration. See your OS's manual.

Alpha Vantage has limited the number of stock and currency quotes that may be requested in a given period using their free API key. If this limit is exceeded, GnuCash will show "unknown error". Finance::Quote v#1.48 and later copes with this for stock quotes, and v1.49 copes with this for currency quotes, although v1.50 (yet to be released as at Jun 14 2020) copes better. Paid Premium Alpha Vantage subscriptions do not have this limit.

Searching for a Symbol

You can search for a symbol by entering the following in a web browser (e.g. Chrome or Firefox) address field

https://www.alphavantage.co/query?function=SYMBOL_SEARCH&keywords=Search Key Words&apikey=#############
e.g.
https://www.alphavantage.co/query?function=SYMBOL_SEARCH&keywords=International Business Machines&apikey=#############

Substitute your API key for "#############". Using a space to separate keywords works in Chrome and Firefox but some web browsers may need %20 instead of each space. E.g.

https://www.alphavantage.co/query?function=SYMBOL_SEARCH&keywords=International%20Business%20Machines&apikey=#############

Notes on Specific Exchanges

Australian Stock Exchange

Quotes may be obtained by using source Australian Stock Exchange or Yahoo as JSON. These are asx and yahoo_json respectively in gnc-fq-dump.

Getting quotes from Alpha Vantage for stocks listed on the ASX in currency AUD using a .AX suffix on the stock symbol (e.g. CBA.AX) stopped working sometime between 18 Mar 2018 and 30 May 2020.

London Stock Exchange'

It has been reported on GnuCash User Email List that LSE stocks that previously Alpha Vantage was able to provide quotes for (e.g. BP.L), stopped working on 25 Jun 2020.

Source Yahoo

On 1 November 2017 Yahoo! discontinued its csv interface, which had been the primary source that Finance::Quote used for all currency quotes and the following stock quotes:

yahoo* (with exception of json and yql^[1]), canada, usa, nyse, nasdaq, vanguard.

The Finance::Quote maintainers have set up a new source, Alpha Vantage, to replace most of the discontinued Yahoo sources.

To update yahoo sources that no longer work, use the Security Editor in GnuCash to edit every security with Get Online Quotes enabled that uses a discontinued Yahoo! source and either

• disable (uncheck) Get Online Quotes or
• change the source to "Yahoo as JSON", "Yahoo as YQL"^[1] or

  GnuCash 2.6.20/2.7.7 and newer

  "Alphavantage, US";

  older

  change the the type to "Unknown"

  and the source to "alphavantage".

If using "Yahoo as JSON" or "Yahoo as YQL"^[1] for a non-US stock, you may have to append a suffix to the end of the stock symbol to tell Finance::Quote what stock exchange the stock is listed on. E.g. CBA.AX gets the quote price for stock CBA on the Australian Stock Exchange in currency AUD. See Exchanges and data providers on Yahoo Finance.

Tip

you can still test currencies by

gnc-fq-dump -v yahoo_json USDEUR=X

Updating enabled Quotes from outside GnuCash

To update all enabled quotes, you can run

GnuCash 4.0 and later

Linux

gnucash-cli --quotes get /path/to/file.gnucash

macOS

/Applications/Gnucash.app/Contents/MacOS/gnucash-cli --quotes get /Users/<username>/Documents/test.gnucash

Windows

gnucash-cli.exe --quotes get file://C:/path/to/file.gnucash

GnuCash 3.11 and earlier

Linux

gnucash --add-price-quotes /path/to/file.gnucash

macOS

/Applications/Gnucash.app/Contents/MacOS/Gnucash --add-price-quotes /Users/<username>/Documents/test.gnucash

Windows

gnucash.exe --add-price-quotes file://C:/path/to/file.gnucash

Warnings

Windows Paths

On Windows if the path includes a "disk letter" then you must pass a "file URI" or GnuCash will confuse the drive letter for an URI scheme and fail to open it. e.g. file://C:/path/to/file.gnucash

Open Files

Updating quotes will modify the GNUCash file/database. As multi-user access is not supported, the file/database should be closed prior to updating quotes.

Multiple Perl installations on macOS

GnuCash was designed to work on a macOS system with only the Apple-supplied Perl installation, which is in /usr/bin/perl. Some macOS users may install another copy of Perl, via package managers like MacPorts or Homebrew, or directly. Usually, these installations have their own location for installing modules like Finance::Quote. They do not consult the system location.

macOS invokes the GnuCash GUI application in a way which leads it to the Apple-supplied Perl installation, even if others are present. Also, gnc-fq-update always installs Finance::Quote to this this location. However, when you invoke gnucash-cli from a Terminal command line, it uses whichever Perl installation your search path $PATH leads it to.

If you have multiple Perl installations on a macOS system, gnucash-cli might use a different Perl installation, and a different set of modules, than the GnuCash GUI application uses. To find out which copy of perl runs, run the command: which perl

So, either be sure that your Terminal environment invokes the Apple-supplied Perl installation in /usr/bin/perl (probably by using a different $PATH), or be sure that Finance::Quote is also installed in the Perl installation which your Terminal environment uses.

If you are using MacPorts, there is a port for Finance::Quote. Install it using the MacPorts command:

sudo port install p5-finance-quote

To see which in directories a Perl installation looks for modules, run the command:

perl -e 'print join("\n", @INC), "\n";'

The Apple-supplied Perl installation usually lists directories in /Library/Perl, /Network/Library/Perl, and /System/Library/Perl. A MacPorts Perl installation will list directories in /opt/local/lib/perl5/.

Cron and Non-X Usage - Linux & macOS (macOS TBC?)

GConf Error: Failed to contact configuration server; the most common cause is a missing or misconfigured D-Bus session bus daemon. 
See http://projects.gnome.org/gconf/ for information. 
(Details -  1: Not running within active session)

One resolution for this, courtesy of SyncEvolution - The Missing Link, is to launch dbus for the duration of the quote retrieval with a cron command similar to:

GnuCash 4.0 and later

env `dbus-launch` sh -c 'trap "kill $DBUS_SESSION_BUS_PID" EXIT; gnucash-cli --quotes get /path/to/file.gnucash'

GnuCash 3.11 and earlier

env `dbus-launch` sh -c 'trap "kill $DBUS_SESSION_BUS_PID" EXIT; gnucash --add-price-quotes /path/to/file.gnucash'

Note: This has been documented in Bug #639776.

Importing Historical Prices or Quotes

If your GnuCash version is built with Python Bindings, you can use the scripts shown on these pages:

• Stocks/get prices and
• Importing fund or stock prices from an OFX file.

Windows and macOS builds do not include Python Bindings.

Technical Details

The technical details of Finance::Quote and how GnuCash uses it differ depending on which OS or distribution you use.

On most systems, you can get the path where Finance::Quote is installed by running:

perldoc -lm Finance::Quote

You can list the directories where Perl looks for modules using the simple Perl program:

perl -e 'print join("\n", @INC), "\n";'

Technical details on Linux

Finance::Quote is stored where your system stores other Perl modules. This location depends on the installation method which was used.

• installed by package manager: in /usr/share/perl5/Finance or /usr/share/perl5/vendor/Finance
• installed by CPAN or by gnc-fq-update: /usr/share/perl5/site/Finance
• if you compiled and installed from source: /usr/local/share/perl/5.xx.x/Finance

Technical details on Windows

Strawberry Perl's location for Perl modules is C:\Strawberry\perl\site\lib\Finance .

Technical details on macOS

The Apple-supplied Perl installation has the Perl executable at /usr/bin/perl. It stores modules at /Library/Perl/5.xx/Finance, where xx depends on the version of Perl in use when you installed Finance::Quote.

sudo gnc-fq-update

sudo cpan -i

When you upgrade macOS, you may have to reinstall Finance::Quote. This is because the newer macOS version may have a newer Perl version, which will have a different xx in the path to the module storage location. The older version directories are not included in Perl's path to this location (via @INC).

For macOS Version 11.6 (Big Sur) Finance::Quote may be inoperable due to missing modules. Use the following commands to correct the problem:

sudo cpan -i B::Keywords
sudo cpan -i Test2
sudo cpan -i DateTime
sudo cpan -i DateTime::Locale
sudo cpan -i DateTime::Format::Strptime
sudo cpan -i Mozilla::CA

Once these modules have been installed, it's probably best to repeat the GnuCash supplied installation again

cd /Applications/Gnucash/Contents/Resources/bin
sudo ./gnc-fq-update

If you have installed Perl via MacPorts or Homebrew, you probably have multiple Perl installations on your system. Each installation has its own set of modules. You may need to install Finance::Quote in each of these locations. See Multiple Perl installations on macOS above for advice.

The reason is that GnuCash installs two executables in macOS: the GnuCash GUI application, and a command-line application gnucash-cli. If you have multiple Perl installations, you may find that these executables use different Perl installations. This is because the GUI apps are started by the macOS LaunchServices, which uses a standard environment and standard search path, while command-line applications use the environment and search path which you customised using your shell's startup files. The straightforward way to use gnucash-cli to retrieve quotes is to install a second copy of Finance::Quote in the Perl installation which it finds.

sudo port install p5-finance-quote

Within p5-finance-quote are subports specific to Perl versions, e.g. p5.26-finance-quote and p5.28-finance-quote. It is these subports which actually install the Finance::Quote module. When you install p5-finance-quote, MacPorts installs the appropriate subports, and necessary other Perl modules.

port info p5\*-finance-quote

port contents installed and p5\*-finance-quote

Homebrew provides ways to install Perl modules. See Gems, Eggs and Perl Modules in the Homebrew documentation. [We welcome people who use both GnuCash and a Homebrew installation of Perl to flesh out this description. —Editors]

If you install Perl using Homebrew, be aware that Homebrew does not preserve modules across Perl updates. After you update Perl with Homebrew, reinstall Finance::Quote.

Trouble Shooting

Broken or outdated Finance::Quote installation

Try the steps below. After each step, run GnuCash and see if that solution resolved the problem of retrieving stock quotes.

Note for Microsoft Windows users to run perl scripts like gnc-fq-check

1. Open a command line window:

   Windows 10 (not in Tablet Mode)

   1. Click in the Cortana Ask me anything field to the right of the Start button,
   2. begin typing cmd, a search menu should appear. The menu should display Command Prompt.
   3. Left-click or tap the Command Prompt icon.

   Windows 8 (or Windows 10 in Tablet Mode)

   From the Start screen, begin typing cmd, a search menu should appear. The menu should display Command Prompt. Left-click or tap the Command Prompt icon.

   Windows 7

   click Start button, type cmd in the Search programs and files field, press Enter

   Windows XP

   click Start button, All Programs, Accessories, Command Prompt

2. Change to the drive containing the GnuCash program files (usually C drive) if that is not already the current drive:

   C:
   

3. Change to the ...\gnucash\bin directory which contains the required gnc-fq-xxx perl script:

   32 bit version of Windows

   cd \Program Files\gnucash\bin
   

   64 bit version of Windows

   cd \Program Files (x86)\gnucash\bin
   

4. Prefix any gnc-fq-xxx perl script command with perl and a space:

   perl gnc-fq-check
   

1. Windows only

   Recent versions of Finance::Quote require a more recent version of perl on Windows. If you encounter trouble with the installation, uninstall whichever perl you have, both with Start, Settings, Apps for recent versions of Windows (or Control Panel for older versions) and Windows Explorer (delete folder C:\Strawberry), then run Install Online Price Retrieval, which will install a recent version of Strawberry Perl for you. N.B.: You don't necessarily want to do that if you're using perl for other purposes, but in that case you probably already know how to upgrade perl.

2. Make sure you're running the latest version of Finance::Quote. Use gnc-fq-check to check what version you are running. Compare this with the latest release at CPAN or Finance::Quote Releases. The CPAN link is a search, and Finance::Quote will be the first hit; the latest version number and release date are under the name.
   On Windows or macOS you can update to the latest F::Q release by running the Online Quote Retrieval Installation program again or from the Unix command line run gnc-fq-update. The providers periodically change interfaces and it's important to keep Finance::Quote up to date to deal with the changes.

   macOS only

   If the GnuCash GUI app can retrieve quotes but the command line gnucash-cli fails with a message, "No quotes retrieved. Finance::Quote isn't installed properly", then check to see if you have multiple Perl installations. If so, gnucash-cli may be using a different Perl installation than the GnuCash GUI app uses. See Multiple Perl installations on macOS above.

3. Use gnc-fq-dump from the command line to check your F::Q sources and commodity symbols, and if a currency conversion rate is available between your Default Currency (see Preferences, Accounts) and other currencies used by accounts.
4. If the output of the gnc-fq-dump command seems ok but Gnucash still fails to get the quote, run from a command line:

   Linux

   echo '(yahoo_json "CSCO")' | gnc-fq-helper
   

   macOS

   echo '(yahoo_json "CSCO")' | /Applications/Gnucash.app/Contents/Resources/bin/gnc-fq-helper
   

   Windows

   echo (yahoo_json "CSCO") | perl gnc-fq-helper
   

   You should get something that looks like (("CSCO" (symbol . "CSCO") ..... (currency . "USD"))). There you can also find bad things like trailing blanks.

   • gives an error message about a missing file instead, that's your problem. This is a dependency that gnucash doesn't know about and so doesn't check for it. You will need to satisfy the missing dependency.

   But usually, at least under linux, it helps to run

   gnc-fq-update
   

   as root.

   For Windows see also Windows Finance::Quote.

5. Run gnucash from the command line with the --debug argument (see Tracefile), attempt a quote retrieval, and then contact the developers either via email to a User Mailing List or on IRC.
6. Sometimes it might help to know what module Perl does actually load.

   This command will tell you exactly that for e.g. Tiaacref:

   perldoc -lm Finance::Quote::Tiaacref
   

7. Check if your security software (virus scanner) blocks you as in this user report.

Diagnosing Finance::Quote failures

On files which contain many price quotes from different sources, it is sometimes not obvious which source failed, in particular if a generic error message is thrown, e.g. "There was a system error during retrieving price quotes".

To diagnose which requests are issued, start gnucash with additional log output

gnucash --log gnc.scm=debug

and get quotes with "Tools->Price Database->Get Quotes".

gnucash.trace (Linux: /tmp/gnucash.trace) contains the relevant log output, e.g.

* 11:31:01 DEBUG <gnc.scm> ALPHAVANTAGE_API_KEY=XXXXXXXXXXXXXXXXXX
* 11:31:01 DEBUG <gnc.scm> handling-request: (fondsweb LU0804734787 IE00BFNM3G45 DE0009769794 IE00BFNM3P36 FR0010524777 IE00BFNM3D14 DE0008476516 LU1136260384 IE00B3VWMM18 DE0009807008 LU0533033238 GB00B0H6D894 IE00B3RBWM25 LU0823414635 LU0119891520)
* 11:31:06 DEBUG <gnc.scm> results: ((LU0804734787 (symbol . LU0804734787) (gnc:time-no-zone . 2021-11-03 12:00:00) (last . 39303/100) (currency . EUR)) (IE00BFNM3G45 (symbol . IE00BFNM3G45) (gnc:time-no-zone . 2021-11-04 12:00:00) (last . 46/5) (currency . USD)) (DE0009769794 (symbol . DE0009769794) (gnc:time-no-zone . 2021-11-04 12:00:00) (last . 16107/100) (currency . EUR)) (IE00BFNM3P36 (symbol . IE00BFNM3P36) (gnc:time-no-zone . 2021-11-04 12:00:00) (last . 709/100) (currency . USD)) (FR0010524777 (symbol . FR0010524777) (gnc:time-no-zone . 2021-11-04 12:00:00) (last . 931/20) (currency . EUR)) (IE00BFNM3D14 (symbol . IE00BFNM3D14) (gnc:time-no-zone . 2021-11-04 12:00:00) (last . 181/25) (currency . EUR)) (DE0008476516 (symbol . DE0008476516) (gnc:time-no-zone . 2021-11-04 12:00:00) (last . 931/50) (currency . EUR)) (LU1136260384 (symbol . LU1136260384) (gnc:time-no-zone . 2021-11-04 12:00:00) (last . 1482/5) (currency . EUR)) (IE00B3VWMM18 (symbol . IE00B3VWMM18) (gnc:time-no-zone . 2021-11-04 12:00:00) (last . 14307/50) (currency . EUR)) (DE0009807008 (symbol . DE0009807008) (gnc:time-no-zone . 2021-11-04 12:00:00) (last . 1012/25) (currency . EUR)) (LU0533033238 (symbol . LU0533033238) (gnc:time-no-zone . 2021-11-04 12:00:00) (last . 21227/50) (currency . EUR)) (GB00B0H6D894 (symbol . GB00B0H6D894) (gnc:time-no-zone . 2021-11-04 12:00:00) (last . 763/50) (currency . EUR)) (IE00B3RBWM25 (symbol . IE00B3RBWM25) (gnc:time-no-zone . 2021-11-04 12:00:00) (last . 3103/25) (currency . USD)) (LU0823414635 (symbol . LU0823414635) (gnc:time-no-zone . 2021-11-04 12:00:00) (last . 69591/50) (currency . EUR)) (LU0119891520 (symbol . LU0119891520) (gnc:time-no-zone . 2021-11-04 12:00:00) (last . 36979/50) (currency . EUR)))
* 11:31:06 DEBUG <gnc.scm> handling-request: (alphavantage DAI.DE)
* 11:31:06 DEBUG <gnc.scm> results: #<eof>

Here the passing request to fondsweb is listed and the result as well as the failing request to alphavantage. As describe above this can be validated with gnc-fq-helper

$ echo '(alphavantage "DAI.DE")'|gnc-fq-helper
Can't use an undefined value as a HASH reference at /usr/share/perl5/Finance/Quote/AlphaVantage.pm line 228.
$ echo '(yahoo_json "DAI.DE")'|gnc-fq-helper
(("DAI.DE" (symbol . "DAI.DE") (gnc:time-no-zone . "2021-11-05 12:00:00") (last . #e87.59) (currency . "EUR")))
$

Documentation

• Development Snapshot
• 5.9 Help

Standards

• full ISO 10383 list of market-identifier-codes

Notes

Back to: Using GnuCash