# Setting Up the Quote Retrieval

If you have more than a couple of commodities, you will tire of having to update their quotes constantly. &app; has the ability to automatically download the most recent quote for your commodities using the Internet. This is accomplished through the &app-perl; module &app-fq;, which must be installed in order to activate this feature.

## Prerequisites for an Online Quote update with &app-fq; are

- the &app-perl; language interpreter and

- the &app-perl;-module &app-fq; with any dependencies

- the &app-perl;-module JSON::Parse to manage the output of &app-fq;.

If you get stuck while performing the steps described here, you can reach many helpful users on the channels mentioned under more_help.

You can also leave out this step and manually update your stock quotes.

## Installing &app-perl;

The installation of &app-perl; is essentially dependent on the operating system used. The effort for installation is low and is described in this section.

To check if &app-perl; is already installed on your system, call the command `perl -v` in the terminal.

    $ perl -v
    This is perl 5, version 30, subversion 0 (v5.30.0) built for x86_64-linux-gnu-thread-multi

If you are shown the version number of the &app-perl; interpreter, skip the next details and continue instead with fq-install.

## On &lin;

1. On most systems &app-perl; is probably already installed. If with the previous command does not show a version, then the easiest way is to use your system’s package manager for installation.

2. When using the &app; &flatpak; package, &app-perl; and &app-fq; are already functionally installed.

## On &mac;

1. &app-perl; is normally already set up under &mac;.

## On &win;

1. Under &win; run the program &gmi.winOS.inst-fq; to run. This will install Strawberry Perl.

2. For execution you need Administrator privilegies, which are requested in the dialog. The installation can take more then 15 minutes.

3. If during the installation the error message `No such file or directory` or `permission denied` are displayed, then it may help to disable the antivirus software temporarily.

Afterwards it’s a good idea to include the folder where &app; is installed, under &win; e.g. ``C:\Program Files (x86)\gnucash\bin``, to your `PATH` environment variable. This way it’s easier for you to use some fq-command-line when needed. Please refer to the documentation for your operating system for more information.

## Installing &app-fq;

To determine if the &app-perl; module &app-fq; is already installed on your system, type `perldoc Finance::Quote` in a terminal window and check to see if there is any documentation available.

    $ perldoc Finance::Quote
    NAME
        Finance::Quote - Get stock and mutual fund quotes from various exchanges

    SYNOPSIS
        [...]

If you are now shown documentation, then &app-fq; is already installed and you can configure periodical quotes update as described in fq-auto-quote. If no documentation is displayed, you will have to continue with this chapter.

### Expected Time Commitment

Depending on the quality of your internet connection and CPUs the initial installation can keep your computer one hour or more busy.

The process of installing &app-fq; depends on the system. For the different supported systems, you can follow the instructions below:

## On &lin;

1. Close &app;.

2. Next, update &app-fq; with `sudo gnc-fq-update`.

   If that fails with `sudo: gnc-fq-update: Command not found` enter `which gnc-fq-update`. It might return a path like `/usr/local/bin/gnc-fq-update`. Redo the command with that returned path: `sudo /usr/local/bin/gnc-fq-update`.

3. Run the `gnucash-cli --quotes info` command to verify that the program is already in a directory that is entered in the `PATH` environment variable.

   If you’ve installed &app; packages provided by your distribution, &app-cli; will be on your `PATH`. The &app-fq; version provided by your package manager can be checked at &app-fq;-versions or by using your package manager's info command.

4. If &app-fq; works properly, the command returns the version number of &app-fq; module currently installed as well as a list of sources available via the &app-fq; module. It will also inform you if there is a problem with your installation or if it is missing, and may suggest a fix.

## On &mac;

You must be logged in with a user id that can administer the mac to use this procedure.

1. Close &app;.

2. Install &app-xcode;

   You can install &app-xcode; from the App Store or install the much smaller Xcode command line tools by running `sudo xcode-select --install` from a Terminal.app prompt.

   if it is not installed. It contains devel tools, which are required by CPAN to build and test the needed &app-fq; modules.

3. Open a Finder window, select &gm.macOS.appl; from the sidebar, double-click &gmi.macOS.appl.util; in the file area, then double-click on Terminal to open Terminal.

4. In the Terminal window enter `sudo /Applications/Gnucash.app/Contents/Resources/bin/gnc-fq-update`. That script asks lots of questions. Accept the default for each.

5. Type `exit` or &kc.ctrl;D to terminate the shell followed by &kc.cmd;Q to quit Terminal.

## On &win;

1. Close &app;.

2. Run &gmi.winOS.inst-fq;. This is a small utility that installs &app-fq; for you.

## Using &app-cli; for Testing and Automation.

&app; provides a commandline facility &app-cli; that one can use with the `--quotes` option in a terminal session to check the version and supported source modules, to display the quotes or exchange rates for selected securities or currencies, or to update all of the prices in a book without launching the GUI.

In &app; version 4.x and earlier one used separate perl programs `gnc-fq-check` instead of `gnucash-cli --quote info` and `gnc-fq-dump` instead of `gnucash-cli --quote dump`.

### Displaying the Finance::Quote Version and Supported Sources

The `--quotes info` option returns the version number of the currently installed &app-fq; module and a list of available sources. It informs you also if there is a problem with your installation and gives the reasons.

The latest &app-fq; version is &app-fq-vers;. The list of sources that follows depends on the &app-fq; version.

The input of

              gnucash-cli

                  -Q

                  --quotes

                info

in the terminal produces the following output:

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

If there's a problem with your installation it will tell you about it. For example in this case we're missing the Perl modules Finance::Quote and JSON::Parse:

    $ gnucash-cli --quotes info
    Failed to initialize Finance::Quote: missing_modules Finance::Quote JSON::Parse

In this case, &app-fq; is not installed correctly and therefore cannot be used for quote retrieval with &app;. Please install &app-fq; according to the instructions at fq-install.

### Displaying Quotes in a Terminal Window

The `--quotes dump` option provides quotes for a source and a list of of symbols in a format that is easy for humans to read. This is useful to verify that a particular online quote source is accessible and provides data.

You can also check to see if the symbol you want to use for your online price retrieval is available at the desired quote source.

You may use `gnucash-cli --quotes dump` to test quote sources and symbols individually should &app; report an error during quote retrieval. The command will show the fields required by &app;; use `gnucash-cli --verbose --quotes dump` to see all of the information returned by &app-fq;.

To display a quote for one or more stocks or the exchange rate for one or more currencies you can use `gnucash-cli --quotes dump` as follows:

              gnucash-cli

                  -Q

                  --quotes

                dump

                  -V

                  --verbose

                Source

                Symbol

It offers two output forms for non-currency securities and one for currency exchange rates.

Currencies

- Currencies use the source `currency` and require at least two ISO 4217 currency codes; the exchange rates are denominated in the first code.

  Since &app-fq; 1.41 the default source for currencies is Alpha Vantage. See also the notes on wiki:Online_Quotes#Finance::Quote_Sources_-_Currency_Source.

  For example:

      $ gnucash-cli --quotes dump currency USD GBP EUR
      1 GBP = 1.2796 USD

      1 EUR = 1.09837 USD

Stocks

- To retrieve quotes of your securities, please enter the quote source and the desired symbol.

  - A short form displaying only the fields that &app; uses along with comments indicating whether the fields are optional or required; you can use this to determine if &app; will be able to use the quote to update your book's price database.

        $ gnucash-cli --quotes dump yahooweb AAPL
        Finance::Quote fields GnuCash uses:
            symbol: AAPL            <=== required
              date: 07/28/2023      <=== recommended
          currency: USD             <=== required
              last: 193.22          <=\
               nav:                 <=== one of these
             price:                 <=/

  - With the `--verbose` option a possibly longer output showing all of the fields &app-fq; returned. This can be useful to troubleshoot problems with a &app-fq; source module.

        $ ALPHAVANTAGE_API_KEY=123456789 gnucash-cli --verbose --quotes dump alphavantage INTC
        INTC:
                open => 34.8200
             isodate => 2023-07-27
               close => 34.3600
                date => 07/27/2023
              symbol => INTC
            currency => USD
        currency_set_by_fq => 1
                 low => 34.1100
              volume => 58890821
             success => 1
                high => 35.0300
                 net => 0.1900
                last => 34.5500
            p_change => 0.5530
              method => alphavantage

    Notice that in this case we used alphavantage and provided the `ALPHAVANTAGE_API_KEY` on the command line. That's not necessary if the key is already stored in &mc.ed.pref; prefs-online-quotes.

To test if &app-fq; works for currencies inside &app;, do the following:

1. create a transaction with the desired commodity in the book currency,

2. make a right click on it,

3. select &gmi.ac.ed-ex; in the context menu.

4. In the trans-win-enter window click the Get exchange rate button.

If the exchange rate source and the symbol are set, the current rate will be entered in the exchange rate field.

### Updating Quotes Automatically with &app-cli;

With the command `gnucash-cli --quotes get &user-datafile;`

This replaces the command `&app; --add-price-quotes &user-datafile;` in &app; version 4.x and earlier.

you can receive the current prices of your foreign exchange and securities and write them directly into your &app;-file without starting the user interface. This enables an automatic, regular updating of the prices.

The command fails if exclusive access to the data file is not possible, for example, the data file is opened in another &app; instance, or the last session for the file crashed.

The specified file &user-datafile; depends on the name and location of your data file. This can be determined from the name displayed in the top frame of the &app; window before the -.

The file name can also be found in the list of recently opened files in the &gm.file; menu. If you hover the mouse pointer on the menu item numbered 1 in the list of recently opened files, the full file name is displayed in the statusbar.

You have to register the &app-cli; with a scheduler in order to get Online Quotes automatically and periodically. The method depends on your OS.

#### Automated quote retrieval every Friday at 4:00 p.m.

#### On &lin; and &mac;

Register `gnucash-cli` with cron.

1. Run `crontab -e`.

2. Add the following line to your crontab:

       0 16 * * 5 gnucash-cli --quotes get &user-datafile; > /dev/null 2>&1

   On &lin; if there is no graphic session that has already started the dbus, running on your computer at the time of the quote request, you must do the entry as follows instead:

       0 16 * * 5 env `dbus-launch` sh -c 'trap "kill $DBUS_SESSION_BUS_PID" EXIT;
       gnucash-cli --quotes get &user-datafile; > /dev/null 2>&1

   (Do not copy the line breaks into the crontab, they were inserted here only for the purpose of readability).

#### On &win;

Register `gnucash-cli` with Task Scheduler.

1. Select &mc.winOS.sys.tasks;

2. Select &gmi.winOS.sys.task;.

3. Enter the appropirate items on Create Task Window.

Adjust the time to the close of the stock exchange and consider fund quotes, that the net asset value (NAV) is determined well after the markets closed. The types have their description in tool-price.

Some users have made additions to the wiki and shared their experiences on the Online Quotes Page on GnuCash Wiki.