<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE chapter SYSTEM "gnc-gui-C.dtd">
<!-- (Do not remove this comment block.)
Version: 1.0.0
Last modified: August 08th 2021

Maintainers:
  xxx
Author:
  TANIGUCHI Yasuaki <yasuakit@gmail.com>
  Christian Wehling <christian.wehling@web.de>
Translators:
  (translators put your name and email here)
-->
<chapter id="finance-quote"
         xmlns:xi="http://www.w3.org/2001/XInclude">
  <title>Setting Up the Quote Retrieval</title>

  <abstract>
    <para>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.
    </para>
  </abstract>

  <itemizedlist>
    <title>Prerequisites for an Online Quote update with &app-fq; are</title>

    <listitem>
      <para>the &app-perl; language interpreter and
      </para>
    </listitem>

    <listitem>
      <para>the &app-perl;-module &app-fq; with any dependencies
      </para>
    </listitem>

    <listitem>
      <para>the &app-perl;-module JSON::Parse to manage the output of &app-fq;.
      </para>
    </listitem>
  </itemizedlist>

  <note>
    <para>If you get stuck while performing the steps described here, you can reach many helpful users on the
      channels mentioned under <xref linkend="more_help" />.
    </para>
  </note>

  <para>You can also leave out this step and manually update your stock quotes.
  </para>

  <sect1 id="fq-perl-install">
    <title>Installing &app-perl;</title>

    <abstract>
      <para>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.
      </para>
    </abstract>

    <para>To check if &app-perl; is already installed on your system, call the command <userinput>perl
      -v</userinput> in the terminal.
<!-- Fixme: https://bugs.gnucash.org/show_bug.cgi?id=798618 -->
      <informalexample>
<?dbfo pgwide="1"?>
<screen language="console">$ perl -v
This is perl 5, version 30, subversion 0 (v5.30.0) built for x86_64-linux-gnu-thread-multi
</screen>
      </informalexample>
      If you are shown the version number of the &app-perl; interpreter, skip the next details and
      continue instead with <xref linkend="fq-install" />.
    </para>

    <procedure>
      <title>On &lin;</title>

      <step>
        <para>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&rsquo;s package manager for
          installation.
        </para>
      </step>

      <step>
        <para>When using the &app; &flatpak; package, &app-perl; and &app-fq; are already functionally installed.
        </para>
      </step>
    </procedure>

    <procedure>
      <title>On &mac;</title>

      <step>
        <para>&app-perl; is normally already set up under &mac;.
        </para>
      </step>
    </procedure>

    <procedure>
      <title>On &win;</title>

      <step>
        <para>Under &win; run the program &gmi.winOS.inst-fq; to run. This will install
          <ulink url="&url-wp-en;Strawberry_Perl">Strawberry Perl</ulink>.
        </para>
      </step>

      <step>
        <para>For execution you need <emphasis>Administrator privilegies</emphasis>, which are requested in the
          dialog. The installation can take more then 15 minutes.
        </para>
      </step>

      <step>
        <para>If during the installation the error message <computeroutput>No such file or directory
          </computeroutput> or <computeroutput>permission denied</computeroutput> are displayed,
          then it may help to disable the antivirus software temporarily.
        </para>
      </step>
    </procedure>

    <tip>
      <para>Afterwards it&rsquo;s a good idea to include the folder where &app; is installed, under &win; e.g.
        <userinput><replaceable>C:\Program Files (x86)\gnucash\bin</replaceable></userinput>, to
        your <envar>PATH</envar> environment variable. This way it&rsquo;s easier for you to use
        some <xref linkend="fq-command-line" /> when needed. Please refer to the documentation for
        your operating system for more information.
      </para>
    </tip>
  </sect1>

  <sect1 id="fq-install">
    <title>Installing &app-fq;</title>

    <para>To determine if the &app-perl; module &app-fq; is already installed on your system, type
      <userinput>perldoc Finance::Quote</userinput> in a terminal window and check to see if there
      is any documentation available.
      <informalexample>
<?dbfo pgwide="1"?>
<screen language="console">
$ perldoc Finance::Quote
NAME
    Finance::Quote - Get stock and mutual fund quotes from various exchanges

SYNOPSIS
    [...]
</screen>
      </informalexample>
      If you are now shown documentation, then &app-fq; is already installed and you can configure
      periodical quotes update as described in <xref linkend="fq-auto-quote" />. If no documentation
      is displayed, you will have to continue with this chapter.
    </para>

    <note>
      <title>Expected Time Commitment</title>

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

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

    <procedure>
      <title>On &lin;</title>

      <step>
        <simpara>Close &app;.
        </simpara>
      </step>

      <step>
        <simpara>Next, update &app-fq; with <userinput>sudo gnc-fq-update</userinput>.
        </simpara>

        <tip>
          <simpara>If that fails with <computeroutput>sudo: gnc-fq-update: Command not found</computeroutput> enter
            <userinput>which gnc-fq-update</userinput>. It might return a path like
            <computeroutput>/usr/local/bin/gnc-fq-update</computeroutput>. Redo the command with
            that returned path: <userinput>sudo /usr/local/bin/gnc-fq-update</userinput>.
          </simpara>
        </tip>
      </step>

      <step>
        <simpara>Run the <userinput>gnucash-cli --quotes info</userinput> command to verify that the program is
          already in a directory that is entered in the <envar>PATH</envar> environment variable.
          <footnote>
            <simpara>If you&rsquo;ve installed &app; packages provided by your distribution, &app-cli; will be on your
              <envar>PATH</envar>. The &app-fq; version provided by your package manager can be
              checked at <ulink url="&url-repo;perl:finance-quote/versions">
              <citetitle>&app-fq;-versions</citetitle></ulink> or by using your package manager's
              info command.
            </simpara>
          </footnote>
        </simpara>
      </step>

      <step>
        <simpara>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.
        </simpara>
      </step>
    </procedure>

    <procedure>
      <title>On &mac;</title>

      <note>
        <para>You must be logged in with a user id that can administer the mac to use this procedure.
        </para>
      </note>

      <step>
        <simpara>Close &app;.
        </simpara>
      </step>

      <step>
        <simpara>Install &app-xcode;
          <footnote>
            <para>You can install &app-xcode; from the App Store or install the much smaller Xcode command line tools
              by running <userinput> sudo xcode-select --install</userinput> from a Terminal.app
              prompt.
            </para>
          </footnote>
          if it is not installed. It contains devel tools, which are required by CPAN to build and
          test the needed &app-fq; modules.
        </simpara>
      </step>

      <step>
        <simpara>Open a <application>Finder</application> window, select &gm.macOS.appl; from the sidebar,
          double-click &gmi.macOS.appl.util; in the file area, then double-click on
          <guimenu>Terminal</guimenu> to open <application>Terminal</application>.
        </simpara>
      </step>

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

      <step>
        <simpara>Type <userinput>exit</userinput> or
          <keycombo>
            &kc.ctrl;<keycap>D</keycap>
          </keycombo>
          to terminate the shell followed by
          <keycombo>
            &kc.cmd;<keycap>Q</keycap>
          </keycombo>
          to quit <application>Terminal</application>.
        </simpara>
      </step>
    </procedure>

    <procedure>
      <title>On &win;</title>

      <step>
        <simpara>Close &app;.
        </simpara>
      </step>

      <step>
        <simpara>Run &gmi.winOS.inst-fq;. This is a small utility that installs &app-fq; for you.
        </simpara>
      </step>
    </procedure>
  </sect1>

  <sect1 id="fq-command-line">
    <title>Using &app-cli; for Testing and Automation.</title>

    <abstract>
      <para>&app; provides a commandline facility &app-cli; that one can use with the
        <replaceable>--quotes</replaceable> 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.
      </para>
    </abstract>

    <note>
      <para>In &app; version 4.x and earlier one used separate perl programs <userinput>gnc-fq-check</userinput>
        instead of <userinput>gnucash-cli --quote info</userinput> and
        <userinput>gnc-fq-dump</userinput> instead of <userinput>gnucash-cli --quote
        dump</userinput>.
      </para>
    </note>

    <sect2 id="fq-check-version">
      <title>Displaying the Finance::Quote Version and Supported Sources</title>

      <abstract>
        <para>The <replaceable>--quotes info</replaceable> 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.
        </para>
      </abstract>

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

      <para>The input of
        <cmdsynopsis>
          <command>gnucash-cli</command>
          <group choice="req">
            <arg choice="plain">
              -Q
            </arg>

            <arg choice="plain">
              --quotes
            </arg>
          </group>

          <arg choice="plain">
            info
          </arg>
        </cmdsynopsis>
        in the terminal produces the following output:
      </para>

      <informalexample>
<?dbfo pgwide="1"?>
<screen language="console">
$ 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
</screen>
      </informalexample>

      <para>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:
      </para>

      <informalexample>
<?dbfo pgwide="1"?>
<screen language="console">
$ gnucash-cli --quotes info
Failed to initialize Finance::Quote: missing_modules Finance::Quote JSON::Parse
</screen>
      </informalexample>

      <para>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
        <xref linkend="fq-install" />.
      </para>
    </sect2>

    <sect2 id="fq-print-quotes">
      <title>Displaying Quotes in a Terminal Window</title>

      <abstract>
        <para>The <replaceable>--quotes dump</replaceable> 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.
        </para>

        <para>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.
        </para>
      </abstract>

      <tip>
        <para>You may use <userinput>gnucash-cli --quotes dump</userinput> 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 <userinput>gnucash-cli --verbose --quotes
          dump</userinput> to see all of the information returned by &app-fq;.
        </para>
      </tip>

      <para>To display a quote for one or more stocks or the exchange rate for one or more currencies you can
        use <userinput>gnucash-cli --quotes dump</userinput> as follows:
        <cmdsynopsis>
          <command>gnucash-cli</command>
          <group choice="req">
            <arg choice="plain">
              -Q
            </arg>

            <arg choice="plain">
              --quotes
            </arg>
          </group>

          <arg choice="plain">
            dump
          </arg>

          <group choice="opt">
            <arg choice="plain">
              -V
            </arg>

            <arg choice="plain">
              --verbose
            </arg>
          </group>

          <arg choice="plain">
            <replaceable>Source</replaceable>
          </arg>

          <arg choice="plain" rep="repeat">
            <replaceable>Symbol</replaceable>
          </arg>
        </cmdsynopsis>
      </para>

      <para>It offers two output forms for non-currency securities and one for currency exchange rates.
        <variablelist>
          <varlistentry>
            <term>Currencies</term>

            <listitem>
              <para>Currencies use the source <userinput>currency</userinput> and require at least two
                <ulink url="&url-wp-en;ISO_4217">ISO&nbsp;4217</ulink> currency codes; the exchange
                rates are denominated in the first code.
                <footnote>
                  <para>Since &app-fq; 1.41 the default source for currencies is <quote>Alpha Vantage</quote>. See also the
                    notes on <ulink url="&url-wiki;Online_Quotes#Finance::Quote_Sources_-_Currency_Source">wiki:Online_Quotes#Finance::Quote_Sources_-_Currency_Source</ulink>.
                  </para>
                </footnote>
                For example:
                <informalexample>
<?dbfo pgwide="1"?>
<screen language="console">
$ gnucash-cli --quotes dump currency USD GBP EUR
1 GBP = 1.2796 USD

1 EUR = 1.09837 USD
</screen>
                </informalexample>
              </para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>Stocks</term>

            <listitem>
              <para>To retrieve quotes of your securities, please enter the quote source and the desired symbol.
                <itemizedlist>
                  <listitem>
                    <para>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.
                      <informalexample>
<?dbfo pgwide="1"?>
<screen language="console">
$ gnucash-cli --quotes dump yahooweb AAPL
Finance::Quote fields GnuCash uses:
    symbol: AAPL            &lt;=== required
      date: 07/28/2023      &lt;=== recommended
  currency: USD             &lt;=== required
      last: 193.22          &lt;=\
       nav:                 &lt;=== one of these
     price:                 &lt;=/
</screen>
                      </informalexample>
                    </para>
                  </listitem>

                  <listitem>
                    <para>With the <userinput>--verbose</userinput> 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.
                      <informalexample>
<?dbfo pgwide="1"?>
<screen language="console">
$ ALPHAVANTAGE_API_KEY=123456789 gnucash-cli --verbose --quotes dump alphavantage INTC
INTC:
        open =&gt; 34.8200
     isodate =&gt; 2023-07-27
       close =&gt; 34.3600
        date =&gt; 07/27/2023
      symbol =&gt; INTC
    currency =&gt; USD
currency_set_by_fq =&gt; 1
         low =&gt; 34.1100
      volume =&gt; 58890821
     success =&gt; 1
        high =&gt; 35.0300
         net =&gt; 0.1900
        last =&gt; 34.5500
    p_change =&gt; 0.5530
      method =&gt; alphavantage
</screen>
                      </informalexample>

                      <note>
                        <para>Notice that in this case we used alphavantage and provided the
                          <userinput>ALPHAVANTAGE_API_KEY</userinput> on the command line. That's
                          not necessary if the key is already stored in &mc.ed.pref;
                          <xref linkend="prefs-online-quotes" />.
                        </para>
                      </note>
                    </para>
                  </listitem>
                </itemizedlist>
              </para>
            </listitem>
          </varlistentry>
        </variablelist>
      </para>

      <procedure>
        <para>To test if &app-fq; works for currencies inside &app;, do the following:
        </para>

        <step>
          <para>create a transaction with the desired commodity in the book currency,
          </para>
        </step>

        <step>
          <para>make a right click on it,
          </para>
        </step>

        <step>
          <para>select &gmi.ac.ed-ex; in the context menu.
          </para>
        </step>

        <step>
          <para>In the <xref linkend="trans-win-enter" /> window click the <guilabel>Get exchange rate</guilabel>
            button.
          </para>
        </step>
      </procedure>

      <para>If the exchange rate source and the symbol are set, the current rate will be entered in the exchange
        rate field.
      </para>
    </sect2>

    <sect2 id="fq-auto-quote">
      <title>Updating Quotes Automatically with &app-cli;</title>

      <para>With the command <command>gnucash-cli --quotes get &user-datafile;</command>
        <footnote>
          <simpara>This replaces the command <userinput>&app; --add-price-quotes &user-datafile;</userinput> in &app;
            version 4.x and earlier.
          </simpara>
        </footnote>
        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.
        <note>
          <para>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.
          </para>
        </note>
      </para>

      <para>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
        <quote>-</quote>.
        <tip>
          <para>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 <guilabel>statusbar</guilabel>.
          </para>
        </tip>
      </para>

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

      <example>
        <title>Automated quote retrieval every Friday at 4:00 p.m.</title>

        <procedure>
          <title>On &lin; and &mac;</title>

          <para>Register <command>gnucash-cli</command> with <application>cron</application>.
          </para>

          <step>
            <simpara>Run <command>crontab -e</command>.
            </simpara>
          </step>

          <step>
            <para>Add the following line to your crontab:
              <informalexample>
<?dbfo pgwide="1"?>
<screen>
0 16 * * 5 gnucash-cli --quotes get &user-datafile; &gt; /dev/null 2&gt;&amp;1
</screen>
              </informalexample>

              <important>
                <para>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:
                  <informalexample>
<?dbfo pgwide="1"?>
<screen>
0 16 * * 5 env `dbus-launch` sh -c 'trap "kill $DBUS_SESSION_BUS_PID" EXIT;
gnucash-cli --quotes get &user-datafile; &gt; /dev/null 2&gt;&amp;1
</screen>
                  </informalexample>
                  (Do not copy the line breaks into the crontab, they were inserted here only for
                  the purpose of readability).
                </para>
              </important>
            </para>
          </step>
        </procedure>

        <procedure>
          <title>On &win;</title>

          <para>Register <command>gnucash-cli</command> with Task Scheduler.
          </para>

          <step>
            <simpara>Select &mc.winOS.sys.tasks;
            </simpara>
          </step>

          <step>
            <simpara>Select &gmi.winOS.sys.task;.
            </simpara>
          </step>

          <step>
            <simpara>Enter the appropirate items on <guilabel>Create Task</guilabel> Window.
            </simpara>
          </step>
        </procedure>

        <para>Adjust the time to the close of the stock exchange and consider <emphasis>fund quotes</emphasis>,
          that the net asset value (NAV) is determined well after the markets closed. The types have
          their description in <xref linkend="tool-price" />.
<!-- FIXME: adjust the link to a proper ID -->
        </para>
      </example>

      <para>Some users have made additions to the wiki and shared their experiences on the
        <ulink url="&url-wiki-OQ;#Updating_enabled_Quotes_from_outside_GnuCash">Online Quotes Page
        on GnuCash Wiki</ulink>.
      </para>
    </sect2>
  </sect1>
</chapter>
