# 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 finance-quote-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.

   &app; Version 2.2.6 and before require ActivePerl. in version 5.8.

   &app; Version 2.4 and before require ActivePerl Version 5.16.3 and later.

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

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

    SYNOPSIS
           [...]

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

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. 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, `gnucash-cli` must be on your `PATH`. The currentness of your distribution can be checked under &app-fq;- versions.

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

4. Run `gnucash-cli --quotes info` to check &app-fq; works properly. This 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 Applications from the sidebar, double-click Utilities 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 Control D to terminate the shell followed by Command 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 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.

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

`gnucash-cli --quotes info` produces the following output:

      $ gnucash-cli --quotes info
      Found Finance::Quote version 1.52.
      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         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    six          tesouro_direto
      tiaacref     tmx          tradeville   troweprice   troweprice_direct
      tsp          ukfunds      unionfunds   usa          usfedbonds   yahoo_json
      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

### Displaying Quotes in a Terminal Window

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. It offers two output forms for non-currency securities and one for currency exchange rates.

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

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

              1 EUR = 0.9717 USD

- Stocks

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

                $ gnucash-cli --quotes dump yahoo_json AAPL
                Finance::Quote fields GnuCash uses:
                    symbol: AAPL            <=== required
                      date: 10/14/2022      <=== recommended
                  currency: USD             <=== required
                      last: 138.38          <=\
                       nav:                 <=== one of these
                     price:                 <=/

  - With the `-v` 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 bin/gnucash-cli -V --quotes dump alphavantage INTC
                INTC:
                             method => alphavantage
                           p_change => -1.9304
                               high => 26.6300
                               date => 10/14/2022
                 currency_set_by_fq => 1
                              close => 26.4200
                           currency => USD
                            isodate => 2022-10-14
                                low => 25.7600
                            success => 1
                                net => -0.5100
                               open => 26.4600
                             symbol => INTC
                             volume => 48118005
                               last => 25.9100

    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 the shell environment or in GnuCash preferences.

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

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 Start Windows Administrative Tools Task Scheduler .

2. Select Create 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.