Difference between revisions of "Online Quotes"

From GnuCash
Jump to: navigation, search
(Updating enabled Quotes from outside GnuCash: File URL on Windows.)
m (Finding the right Source and Symbol: Correct markup and explain a little more thoroughly.)
(14 intermediate revisions by 4 users not shown)
Line 4: Line 4:
 
| [[De/Aktienhandel | german version]]
 
| [[De/Aktienhandel | german version]]
 
|}
 
|}
 +
 +
GnuCash can automatically retrieve the current share price of marketable commodities (e.g., stocks, mutual funds, currency exchange rates), called a quote, so that you do not need to manually update the prices of these securities in the [https://lists.gnucash.org/docs/C/gnucash-guide/invest-stockprice1.html 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.
  
 
== Overview ==
 
== Overview ==
GnuCash stores the share '''prices''' of investments in the respective buy/sell/split ''transactions'' 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 [http://en.wikipedia.org/wiki/Perl Perl] module called ''Finance::Quote'' ('''F::Q''') to fetch these quotes online.
+
GnuCash stores the share '''prices''' of investments in the respective buy/sell/split ''transactions'' 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 [http://en.wikipedia.org/wiki/Perl Perl] programming language called [https://github.com/finance-quote/finance-quote/blob/master/README.md 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.
 +
 
 +
=== About Finance::Quote ===
 +
 
 +
The '''Finance::Quote''' Perl module is managed at
 +
* [https://github.com/finance-quote GitHub],
 +
* [https://metacpan.org/release/Finance-Quote CPAN] (both recent), and
 +
* [https://sourceforge.net/projects/finance-quote/ SourceForge],
 +
* [http://finance-quote.sourceforge.net/ SourceForge] (hopeless outdated, last news: 2015-Aug-22 Release 1.38).
 +
 
 +
Since the Finance::Quote software is not part of GnuCash proper, if you believe you have found a bug in the Finance::Quote module, there is probably not a lot the GnuCash developers can do to fix the problem for you. Instead, you should report the issue directly to the Finance::Quote developers at the following ''bugtrackers'':
 +
* http://rt.cpan.org/Public/Dist/Display.html?Status=Active&Name=Finance-Quote and
 +
* https://github.com/finance-quote/finance-quote/issues
  
'''Finance::Quote''' is managed at
+
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.
:[https://github.com/finance-quote GitHub],
 
:[https://metacpan.org/release/Finance-Quote CPAN] (both recent), and
 
:[https://sourceforge.net/projects/finance-quote/ SourceForge],
 
:[http://finance-quote.sourceforge.net/ SourceForge] (hopeless outdated, last news: 2015-Aug-22 Release 1.38).
 
There are ''bugtrackers'' at
 
:http://rt.cpan.org/Public/Dist/Display.html?Status=Active&Name=Finance-Quote and
 
:https://github.com/finance-quote/finance-quote/issues.
 
  
Finance::Quote gathers its price data from several websites around the world that provide this information in ''different ways''. Some offer
+
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'',
 
* an '''API''' like ''JSON'' or ''YQL'',
* '''download'''s, usually as ''CSV'' file, and finally  
+
* '''download'''s, usually as ''CSV'' file, and finally,
 
* quite literally by extracting information from the web page itself.
 
* quite literally by extracting information from the web page itself.
'''Because websites change frequently we advise you to keep Finance::Quote up-to-date'''.
 
  
The '''GnuCash Help''' includes [http://www.gnucash.org/docs/v{{MainVersion}}/C/gnucash-help/acct-create.html#Online-price-setup instructions] on setting up online quotes.
+
As these sources change frequently, we advise you to keep Finance::Quote up-to-date. (See below for instructions.)
  
'''Finance::Quote is external to GnuCash.''' Thus, for it to work, you need Perl installed (see below), and occasionally you will need to update it separately from GnuCash.  
+
== Setting up online quotes in GnuCash ==
 +
The '''GnuCash Guide''' includes [{{BuildURL}}/docs/C/gnucash-guide/invest-stockprice1.html#invest-stockprice-auto-configure3 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.
  
===Helper Scripts===
+
Once again, Finance::Quote is ''external to GnuCash.'' Thus, for it to work, you need some additional installed beyond GnuCash itself. This includes the Perl language interpreter itself, the Finance::Quote module, and any dependencies required by this software. Occasionally, you may need to update the Finance::Quote software module (and, more occasionally, the Perl interpreter) separately from GnuCash.
For your convenience, we ship a bunch of <tt>gnc-fq-*</tt> programs, which again are Perl scripts:
 
:;gnc-fq-check: returns the version number and the list of available F::Q modules,
 
:;gnc-fq-update: installs or updates F::Q and its dependencies, if Perl is already installed;
 
:;gnc-fq-dump: returns data for a source and a list of symbols,
 
:;gnc-fq-helper: a filter, which does the same, but in- and output are [https://en.wikipedia.org/wiki/Scheme_(programming_language) Scheme] expressions.
 
  
You might use them for troubleshooting, if Gnucash fails to update quotes.
+
To ease this update process, the GnuCash developers provide several helper scripts.
 +
 
 +
== Helper Scripts ==
 +
For your convenience, we ship several helper programs designed to make it easier to install, update, and diagnose problems with your installation of the Finance::Quote software module. These programs have names that begin with <tt>gnc-fq-*</tt>, and are themselves written in the Perl programming language. Along with your GnuCash installation, you should have the following helper programs:
 +
 
 +
;gnc-fq-check: This program returns the version number of and the list of modules available to the Finance::Quote software. 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.
 +
;gnc-fq-update: This program installs or updates the Finance::Quote software module along with its dependencies. This program normally needs superuser or administrative privileges to succeed.
 +
;gnc-fq-dump: This program returns quote data for a source and a list of symbols. It is useful for checking that a given online quote source is online and functional.
 +
;gnc-fq-helper: This program is a filter, which does the same thing as <code>gnc-fq-dump</code>, but its input and output are [https://en.wikipedia.org/wiki/Scheme_(programming_language) Scheme] expressions. This helps developers to decide, if the error is in GnuCash or F::Q. It shows also trailing spaces in downloaded quotes.
 +
:As an example, in September 2008 an Unilever bond was reported to fail. Here is a sample execution and result of this helper program: <Syntaxhighlight lang="console">
 +
user@host:~$ echo '(yahoo_europe "A0GFY7.SG")' | gnc-fq-helper
 +
(("A0GFY7.SG" (symbol . "A0GFY7.SG") (gnc:time-no-zone . "2008-09-26 16:58:00") (last . 89.50) (currency . "EUR ")))
 +
</Syntaxhighlight>Do you see the error? [{{BugURL}}/show_bug.cgi?id=553902#c4 Solution]
 +
 
 +
Since these helper programs are Perl scripts, you must have a functioning Perl installation before any of these helper programs will run successfully.
 +
 
 +
Note that while [https://en.wikipedia.org/wiki/Unixoid unixoid] operating systems use a [https://en.wikipedia.org/wiki/Shebang_(Unix) shebang] (<code>#!</code>) to associate perl scripts with the Perl interpreter, others might fail. So, if you get an error like <Syntaxhighlight lang="doscon">
 +
C:\>gnc-fq-check
 +
gnc-fq-check is not recognized as an internal or external command, operable program or batch file
 +
</Syntaxhighlight>
 +
 
 +
you should repeat the command with a preceeding <tt>perl</tt>:
 +
<Syntaxhighlight lang="sh">
 +
perl gnc-fq-check
 +
</Syntaxhighlight>
  
 
==Requirements==
 
==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===
 
===Perl===
F::Q relies on [https://en.wikipedia.org/wiki/Perl Perl], which must be installed. Perl is handled differently on the different operating systems.
+
The Finance::Quote module relies on [https://en.wikipedia.org/wiki/Perl 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 <code>perl -v</code> 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.
 +
 
 +
==== Installing Perl on macOS ====
 +
On Apple's macOS computers, Perl is already installed by default. To confirm this, open the Terminal application (usually located in the Utilities folder of your Applications folder), and invoke the <code>perl -v</code> command to see the Perl interpreter's version number.
  
*'''Unix''' (Linux, AIX, *BSD, HPUX, Solaris,...): Perl is probably already installed or gets installed as dependency, if you install Finance::Quote by your systems package manager. Run <code>perl -v</code> on a command line to get the version number.  If that fails, use your package manager to install it.
+
==== Installing Perl on Windows ====
*'''Mac OS X''': Perl is already installed. Open a Terminal application (in the Utilities folder of your Applications folder) and run <code>perl -v</code> to see the version number.
 
 
*'''Windows''': <to be moved from [[Windows#Finance::Quote]] etc.>  
 
*'''Windows''': <to be moved from [[Windows#Finance::Quote]] etc.>  
 
Source: [http://www.perl.org/get.html]
 
Source: [http://www.perl.org/get.html]
 
;Note: While [https://en.wikipedia.org/wiki/Unixoid unixoid] operating systems use a [https://en.wikipedia.org/wiki/Shebang_(Unix) shebang] <code>#!</code> to associate perl scripts with the perl interpreter, others might fail. So, if you get an error like
 
gnc-fq-check is not recognized as an internal or external command, operable program or batch file
 
:you should repeat the command with a preceeding <tt>perl</tt>:
 
:<Syntaxhighlight lang="sh">
 
perl gnc-fq-check
 
</Syntaxhighlight>
 
  
 
===Finance::Quote===
 
===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.
 
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 the ''version'' and the list of ''available modules'' by running
+
You can check to see if your system has Finance::Quote installed by running the <code>gnc-fq-check</code> helper program after you have installed Perl itself. Alternatively, you can open the "About GnuCash" window (from the menu, choose Help &rarr; About, or on macOS, from the menu choose GnuCash &rarr; About GnuCash) and look for a line reading <code>Finance::Quote: {{FQ Version}}</code> or similar; this screen reports the currently installed version of Finance::Quote (<code>{{FQ Version}}</code> in the example given), if it can find one. If GnuCash cannot find a Finance::Quote version, this line will read <code>Finance::Quote: -</code>.
 +
 
 +
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 <code>apt</code> program on Debian-based Linux distributions and the <code>dnf</code> 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 <code>Install Online Price Retrieval</code> program, which is located in the ''GnuCash'' group in the Start Menu. Simply click on it to begin the Finance::Quote installation process. You can re-run the <code>Install Online Price Retrieval</code> program as often as you like to ensure the Finance::Quote module remains up to date.
 +
 
 +
==== Installing Finance::Quote on macOS ====
 +
On a macOS computer, GnuCash provides the <code>FinanceQuote Update</code> app, which is located in the disk image (<code>.dmg</code> file) along with the main GnuCash app itself. When you install GnuCash by dragging and dropping the GnuCash app icon to a location on your computer's hard drive (like your <code>Applications</code> folder), you should also consider installing the <code>FinanceQuote Update</code> app into the same folder as you installed the main GnuCash app.
 +
 
 +
Launch the <code>FinanceQuote Update</code> app by double-clicking it to begin the Finance::Quote installation process. You can re-run the <code>FinanceQuote Update</code> 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 =====
 +
The <code>FinanceQuote Update</code> app is a very simple [https://en.wikipedia.org/wiki/AppleScript#Script_launchers AppleScript Applet] that runs a command equivalent to the following in a Terminal:
 +
 
 
<Syntaxhighlight lang="sh">
 
<Syntaxhighlight lang="sh">
gnc-fq-check
+
sudo /Applications/Gnucash.app/Contents/Resources/bin/gnc-fq-update
 
</Syntaxhighlight>
 
</Syntaxhighlight>
from the command line.
 
  
==== Installing or Updating ====
+
If the <code>FinanceQuote Update</code> applet fails, you can simply run the above command while logged in to a user account with administrative privileges. (Note that a mere <code>su</code> may not be sufficient; you should log out of all user accounts, then log in as the admin user for the computer on which you want to install Finance::Quote, then run the above command from a Terminal.)
Both the ''Microsoft Windows'' and ''MacOS X'' GnuCash packages include update tools for Finance::Quote. In Windows it's called <code>Install Online Price Retrieval</code> and it's located in the GnuCash group in the Start Menu. In OS X it's <code>Update Finance::Quote</code> and it's in the dmg along with GnuCash. On ''Linux'' search in your distributions package manager for ''finance-quote''. They may prefix it with ''perl'', ''lib'' or both.
 
  
'''Note:''' You can re-run the ''Windows'' or ''MacOS'' '''installation tools''' as often as you like or you can use '''CPAN''' as explained below.
+
As with the applet, you can re-run the command as often as you like to ensure the Finance::Quote module remains up to date.
  
Depending on your operating system, there are other advanced ways to install F::Q.
+
==== Installing Finance::Quote on Linux ====
:*'''Linux:'''
+
On a ''Linux'' computer, the recommended way to install Finance::Quote is by searching in your OS distribution's package manager for <code>finance-quote</code>. Note that your distribution's package maintainer may prefix the package name with ''perl'', ''lib'', or both. 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.
::If there is no ''recent'' perl-finance-quote offered by your '''package manager''' do the following:
+
 
::As root (su / sudo) run the GnuCash Finance Quote update script  
+
If no ''recent'' version of the Finance::Quote module is offered by your '''package manager''', you should run the <code>gnc-fq-update</code> helper script manually. As <code>root</code> (using the <code>su</code> and/or the <code>sudo</code> commands) run the GnuCash Finance Quote update script:
::<Syntaxhighlight lang="sh">
+
 
 +
<Syntaxhighlight lang="sh">
 
gnc-fq-update
 
gnc-fq-update
 
</Syntaxhighlight>
 
</Syntaxhighlight>
::It will install Finance::Quote and its dependencies.
 
::;Note for (Ubuntu based) distributions: Some of them removed it from the package. In this case you can
 
:::* download it from [https://raw.github.com/Gnucash/gnucash/maint/libgnucash/quotes/gnc-fq-update.in github] e.g. into your personal <tt>~/bin</tt> directory,
 
:::*In the first line replace <tt>@-PERL-@</tt> with the path to your perl executable, e.g., <tt>/usr/bin/perl</tt>, remove the trailing <tt>.in</tt> from its name and mark the file as executable.
 
:::A discussion of how to fix it in Ubuntu can be found at [https://lists.gnucash.org/pipermail/gnucash-user/2012-September/045931.html].
 
  
::That script, as of 2.6.12, uses CPAN to install:
+
This will begin the installation procedure for Finance::Quote and all of its dependencies.
:::* Date::Manip
 
:::* Finance::Quote
 
:::* and their dependencies
 
  
:*'''MacOs:'''
+
:;Note for (Ubuntu based) distributions: Some of them removed it from the package. In this case you can
::*from a Terminal prompt:
+
::* download it from [https://raw.github.com/Gnucash/gnucash/maint/libgnucash/quotes/gnc-fq-update.in github] e.g. into your personal <tt>~/bin</tt> directory,
::<Syntaxhighlight lang="sh">
+
::*In the first line replace <tt>@-PERL-@</tt> with the path to your perl executable, e.g., <tt>/usr/bin/perl</tt>, remove the trailing <tt>.in</tt> from its name and mark the file as executable.
/Applications/Gnucash.app/Contents/Resources/bin/gnc-fq-update
+
::A discussion of how to fix it in Ubuntu can be found at [{{ListURL}}/pipermail/gnucash-user/2012-September/045931.html gnucash-user/2012-September].
</Syntaxhighlight>
+
 
::*Or use the applet that runs it from Finder in the dmg.
+
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 ====
 +
[https://cpan.org/ CPAN] is the '''Comprehensive Perl Archive Network''', which provides a collection of free Perl software (called modules) from which you can obtain the perl Finance::Quote module along with all of its dependencies. If the methods listed above for your specific Operating System distribution fails, you may nevertheless be able to install Finance::Quote by directly interfacing with CPAN yourself.
  
Using CPAN:
+
To do so using CPAN:
 
<Syntaxhighlight lang="sh">
 
<Syntaxhighlight lang="sh">
 
perl -MCPAN -e shell
 
perl -MCPAN -e shell
Line 103: Line 143:
 
   q
 
   q
 
</Syntaxhighlight>
 
</Syntaxhighlight>
;Note: On the ''first'' run of <code>cpan</code> it needs some configuration:
+
 
CPAN.pm requires configuration, but most of it can be done automatically.
+
On the ''first'' run of <code>cpan</code> it needs some configuration:
If you answer 'no' below, you will enter an interactive dialog for each
+
 
configuration option instead.
+
<pre>
 +
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]
+
Would you like to configure as much as possible automatically? [yes]
:It is usually save to accept the defaults.
+
</pre>
 +
 
 +
It is usually safe to accept the defaults.
  
 
;Sources:
 
;Sources:
Line 123: Line 168:
 
* sometimes completed by an ''appendix'' indicating the market place.
 
* sometimes completed by an ''appendix'' indicating the market place.
  
It is suggested to use <syntaxhighlight lang="sh">gnc-fq-dump -v <Source> <Symbol></syntaxhighlight> on the commandline until you are successful because it is much faster and ways more informative than doing it in GnuCash.
+
It is suggested to use <syntaxhighlight lang="sh">gnc-fq-dump -v <Source> <Symbol></syntaxhighlight> on the commandline until you are successful because it is much faster and ways more informative than doing it in GnuCash. Note that Finance::Quote's <tt>alphavantage</tt> and <tt>currency</tt> sources require AlphaVantage API key that you can get free from the [https://www.alphavantage.co/ AlphaVantage Website].  Command-line programs like <tt> gnc-fq-dump</tt> will obtain the key from the <tt>ALPHAVANTAGE_API_KEY</tt> environment variable.  GnuCash will too if it reads the same shell environment, but it often does not in desktop environments or in MacOS and Microsoft Windows. In that case it can be added to the [[Environment]] file or stored in the <tt>Online Quotes</tt> tab of <tt>Preferences</tt>
 +
 
  
 
If your commodity is a mutual fund and F::Q offers its fund company as source (deka, dws, ...) look on their website, which symbols they use and you are done.
 
If your commodity is a mutual fund and F::Q offers its fund company as source (deka, dws, ...) look on their website, which symbols they use and you are done.
Line 132: Line 178:
  
 
Global players: Alphavantage and Yahoo* are stronger in shares and Morningstar* in funds.
 
Global players: Alphavantage and Yahoo* are stronger in shares and Morningstar* in funds.
+
 
 
==Updating enabled Quotes from outside GnuCash==
 
==Updating enabled Quotes from outside GnuCash==
 
You can run
 
You can run
Line 138: Line 184:
 
gnucash --add-price-quotes /path/to/file.gnucash
 
gnucash --add-price-quotes /path/to/file.gnucash
 
</Syntaxhighlight>
 
</Syntaxhighlight>
or on ''MacOS™'':
+
or on ''macOS'':
 
:<Syntaxhighlight lang="sh">
 
:<Syntaxhighlight lang="sh">
 
  /Applications/Gnucash.app/Contents/MacOS/Gnucash --add-price-quotes /Users/<username>/Documents/test.gnucash
 
  /Applications/Gnucash.app/Contents/MacOS/Gnucash --add-price-quotes /Users/<username>/Documents/test.gnucash
Line 144: Line 190:
 
to  update all enabled quotes.  
 
to  update all enabled quotes.  
  
'''N.B.''': On Microsoft Windows™ if the path includes a disk letter then you must pass a file URI or GnuCash will confuse the drive letter for a URI scheme and fail to open it. e.g.:
+
'''N.B.''': On Windows if the path includes a disk letter then you must pass a file URI or GnuCash will confuse the drive letter for a URI scheme and fail to open it. e.g.:
 
   file://C:/path/to/file.gnucash
 
   file://C:/path/to/file.gnucash
  
Line 151: Line 197:
  
 
===Cron and Non-X Usage===
 
===Cron and Non-X Usage===
If you attempt to do that without [https://en.wikipedia.org/wiki/D-Bus dbus] running (for example, from a [https://en.wikipedia.org/wiki/Cron cron] job or [https://en.wikipedia.org/wiki/Secure_Shell ssh] without X forwarding), you may get errors such as
+
If you attempt to do that without [https://en.wikipedia.org/wiki/D-Bus dbus] running (for example, from a [https://en.wikipedia.org/wiki/Cron cron] job or [https://en.wikipedia.org/wiki/Secure_Shell ssh] without X forwarding), you may get errors such as <SyntaxHighlight lang="Console">
 
+
GConf Error: Failed to contact configuration server; the most common cause is a missing or misconfigured D-Bus session bus daemon.  
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.  
See http://projects.gnome.org/gconf/ for information.  
+
(Details -  1: Not running within active session)
(Details -  1: Not running within active session)
+
</SyntaxHighlight>
 
 
 
One resolution for this, courtesy of [http://www.estamos.de/blog/2009/05/08/running-syncevolution-as-cron-job/ SyncEvolution - The Missing Link], is to launch dbus for the duration of the quote retrieval with a cron command similar to:
 
One resolution for this, courtesy of [http://www.estamos.de/blog/2009/05/08/running-syncevolution-as-cron-job/ SyncEvolution - The Missing Link], is to launch dbus for the duration of the quote retrieval with a cron command similar to:
 
<Syntaxhighlight lang="sh">
 
<Syntaxhighlight lang="sh">
Line 176: Line 221:
 
perldoc -lm Finance::Quote
 
perldoc -lm Finance::Quote
 
</Syntaxhighlight>
 
</Syntaxhighlight>
(Tested on Linux. Please update for: MacOS, Windows)
+
(Tested on Linux and macOS. Please update for Windows.)
  
 
== Documentation ==
 
== Documentation ==
* [https://code.gnucash.org/docs/C/gnucash-help/acct-create.html#Online-price-setup Development Snapshot]
+
* [{{BuildURL}}/docs/C/gnucash-help/acct-create.html#Online-price-setup Development Snapshot]
* [http://www.gnucash.org/docs/v{{Version}}/C/gnucash-help/acct-create.html#Online-price-setup {{Version}} Help]
+
* [{{WebURL}}/docs/v{{MainVersion}}/C/gnucash-help/acct-create.html#Online-price-setup {{Version}} Help]
  
 
----
 
----
 
[[Using GnuCash | Back to: Using GnuCash]]
 
[[Using GnuCash | Back to: Using GnuCash]]

Revision as of 03:33, 12 August 2019

Back to: Using GnuCash german version

GnuCash can automatically retrieve the current share price of marketable commodities (e.g., stocks, mutual funds, currency exchange rates), called a quote, so that you do not need to manually update the prices of these securities 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.

Overview

GnuCash stores the share prices of investments in the respective buy/sell/split transactions 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.

About Finance::Quote

The Finance::Quote Perl module is managed at

Since the Finance::Quote software is not part of GnuCash proper, if you believe you have found a bug in the Finance::Quote module, there is probably not a lot the GnuCash developers can do to fix the problem for you. Instead, you should report the issue directly to the Finance::Quote developers at the following bugtrackers:

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,
  • 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. (See below for instructions.)

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.

Once again, Finance::Quote is external to GnuCash. Thus, for it to work, you need some additional installed beyond GnuCash itself. This includes the Perl language interpreter itself, the Finance::Quote module, and any dependencies required by this software. Occasionally, you may need to update the Finance::Quote software module (and, more occasionally, the Perl interpreter) separately from GnuCash.

To ease this update process, the GnuCash developers provide several helper scripts.

Helper Scripts

For your convenience, we ship several helper programs designed to make it easier to install, update, and diagnose problems with your installation of the Finance::Quote software module. These programs have names that begin with gnc-fq-*, and are themselves written in the Perl programming language. Along with your GnuCash installation, you should have the following helper programs:

gnc-fq-check
This program returns the version number of and the list of modules available to the Finance::Quote software. 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.
gnc-fq-update
This program installs or updates the Finance::Quote software module along with its dependencies. This program normally needs superuser or administrative privileges to succeed.
gnc-fq-dump
This program returns quote data for a source and a list of symbols. It is useful for checking that a given online quote source is online and functional.
gnc-fq-helper
This program is a filter, which does the same thing as gnc-fq-dump, but its input and output are Scheme expressions. This helps developers to decide, if the error is in GnuCash or F::Q. It shows also trailing spaces in downloaded quotes.
As an example, in September 2008 an Unilever bond was reported to fail. Here is a sample execution and result of this helper program:
user@host:~$ echo '(yahoo_europe "A0GFY7.SG")' | gnc-fq-helper
(("A0GFY7.SG" (symbol . "A0GFY7.SG") (gnc:time-no-zone . "2008-09-26 16:58:00") (last . 89.50) (currency . "EUR ")))
Do you see the error? Solution

Since these helper programs are Perl scripts, you must have a functioning Perl installation before any of these helper programs will run successfully.

Note that while unixoid operating systems use a shebang (#!) to associate perl scripts with the Perl interpreter, others might fail. So, if you get an error like
C:\>gnc-fq-check
gnc-fq-check is not recognized as an internal or external command, operable program or batch file

you should repeat the command with a preceeding perl:

perl gnc-fq-check

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.

Installing Perl on macOS

On Apple's macOS computers, Perl is already installed by default. To confirm this, open the Terminal application (usually located in the Utilities folder of your Applications folder), and invoke the perl -v command to see the Perl interpreter's version number.

Installing Perl on Windows

Source: [1]

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.59 or similar; this screen reports the currently installed version of Finance::Quote (1.59 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. 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

On a macOS computer, GnuCash provides the FinanceQuote Update app, which is located in the disk image (.dmg file) along with the main GnuCash app itself. When you install GnuCash by dragging and dropping the GnuCash app icon to a location on your computer's hard drive (like your Applications folder), you should 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

The FinanceQuote Update app is a very simple AppleScript Applet that runs a command equivalent to the following in a Terminal:

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

If the FinanceQuote Update applet fails, you can simply run the above command while logged in to a user account with administrative privileges. (Note that a mere su may not be sufficient; you should log out of all user accounts, then log in as the admin user for the computer on which you want to install Finance::Quote, then run the above command from a Terminal.)

As with the applet, you can re-run the command as often as you like to ensure the Finance::Quote module remains up to date.

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 the package name with perl, lib, or both. 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.

If no recent version of the Finance::Quote module is offered by your package manager, you should run the gnc-fq-update helper script manually. As root (using the su and/or the sudo commands) run the GnuCash Finance Quote update script:

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
  • download it from github e.g. into your personal ~/bin directory,
  • In the first line replace @-PERL-@ with the path to your perl executable, e.g., /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 the Comprehensive Perl Archive Network, which provides a collection of free Perl software (called modules) from which you can obtain the perl Finance::Quote module along with all of its dependencies. If the methods listed above for your specific Operating System distribution fails, you may nevertheless be able to install Finance::Quote by directly interfacing with CPAN yourself.

To do so using CPAN:

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.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

Because not all sources offer all commodities and different sources use different symbols, it is the high art to find the right combination. Common symbols are:

  • Ticker symbols: 1-4 character abbreviation of company names, often used for US shares;
  • National Security Identification Numbers: 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.
It is suggested to use
gnc-fq-dump -v <Source> <Symbol>
on the commandline until you are successful because it is much faster and ways more informative than doing it in GnuCash. Note that Finance::Quote's alphavantage and currency sources require AlphaVantage API key that you can get free from the AlphaVantage Website. Command-line programs like gnc-fq-dump will obtain the key from the ALPHAVANTAGE_API_KEY environment variable. GnuCash will too if it reads the same shell environment, but it often does not in desktop environments or in MacOS and Microsoft Windows. In that case it can be added to the Environment file or stored in the Online Quotes tab of Preferences


If your commodity is a mutual fund and F::Q offers its fund company as source (deka, dws, ...) look on their website, which symbols they use and you are done.

Is there 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: Alphavantage and Yahoo* are stronger in shares and Morningstar* in funds.

Updating enabled Quotes from outside GnuCash

You can run

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

or on macOS:

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

to update all enabled quotes.

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

 file://C:/path/to/file.gnucash

Warning About 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.

Cron and Non-X Usage

If you attempt to do that without dbus running (for example, from a cron job or ssh without X forwarding), you may get errors such as
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:

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.

Technical Details

Where the F::Q files are stored depends on your OS/Distro:

  • Linux depends on the way it was installed:
    • by package manager: /usr/share/perl5/[vendor/]Finance/Quote
    • by CPAN or gnc-fq-update: /usr/share/perl5/site/Finance/Quote
    • self compiled: /usr/local/share/perl/5.xx.x/Finance/Quote
  • Windows: C:\Perl\site\lib\Finance\Quote

You can get the path by running:

perldoc -lm Finance::Quote

(Tested on Linux and macOS. Please update for Windows.)

Documentation

  • Development Snapshot
  • [[[:Template:WebURL]]/docs/v5/C/gnucash-help/acct-create.html#Online-price-setup 5.5 Help]

Back to: Using GnuCash