20.1 Currency Exchange Rates

The units program database includes currency exchange rates and prices for some precious metals. Of course, these values change over time, sometimes very rapidly, and units cannot provide real-time values. To update the exchange rates, run units_cur, which rewrites the file containing the currency rates, typically /var/lib/units/currency.units or /usr/local/com/units/currency.units on a Unix-like system or C:\Program Files (x86)\GNU\units\definitions.units on a Windows system.

This program requires Python 3 (https://www.python.org). The program must be run with suitable permissions to write the file. To keep the rates updated automatically, run it using a cron job on a Unix-like system, or a similar scheduling program on a different system.

Reliable free sources of currency exchange rates have been annoyingly ephemeral. The program currently supports several sources:

• ExchangeRate-API.com (https://www.exchangerate-api.com).
  The default currency server. Allows open access without an API key, with unlimited API requests. Rates update once a day, the US dollar (‘USD’) is the default base currency, and you can choose your base currency with the -b option described below. You can optionally sign up for an API key to access paid benefits such as faster data update rates.
• FloatRates (https://www/floatrates.com).
  The US dollar (‘USD’) is the default base currency. You can change the base currency with the -b option described below. Allowable base currencies are listed on the FloatRates website. Exchange rates update daily.
• The European Central Bank (https://www.ecb.europa.eu).
  The base currency is always the euro (‘EUR’). Exchange rates update daily. This source offers a more limited list of currencies than the others.
• Fixer (https://fixer.io).
  Registration for a free API key is required. With a free API key, base currency is the euro; exchange rates are updated hourly, the service has a limit of 1,000 API calls per month, and SSL encryption (https protocol) is not available. Most of these restrictions are eliminated or reduced with paid plans.
• open exchange rates (https://openexchangerates.org).
  Registration for a free API key is required. With a free API key, the base currency is the US dollar; exchange rates are updated hourly, and there is a limit of 1,000 API calls per month. Most of these restrictions are eliminated or reduced with paid plans.

The default source is FloatRates; you can select a different one using -s option described below.

Precious metals pricing is obtained from Packetizer (www.packetizer.com). This site updates once per day.

20.2 US Consumer Price Index

The units program includes the US Consumer Price Index (CPI) published by the US Bureau of Labor Statistics: specifically, the Consumer Price Index for All Urban Consumers (CPI-U), Series CUUR0000SA0. The units_cur command updates the CPI and saves the result in cpi.units in the same location as currency.units. The data are obtained via the BLS Public Data API (https://www.bls.gov/developers/). This data updates once a month. When units_cur runs it will only attempt to update the CPI data if the current CPI data file is from a previous month, or if the current date is after the 18th of the month.

20.3 Invoking units_cur

You invoke units_cur like this:

units_cur [options] [currency_file] [cpi_file]

By default, the output is written to the default currency and CPI files described above; this is usually what you want, because this is where units looks for the files. If you wish, you can specify different filenames on the command line and units_cur will write the data to those files. If you give ‘-’ for a file it will write to standard output.

The following options are available:

-h

--help

Print a summary of the options for units_cur.

-V

--version

Print the units_cur version number.

-v

--verbose

Give slightly more verbose output when attempting to update currency exchange rates.

-s source

--source source

Specify the source for currency exchange rates; currently supported values are ‘floatrates’ (for FloatRates), ‘eubank’ (for the European Central Bank), ‘fixer’ (for Fixer), and ‘openexchangerates’ (for open exchange rates); the last two require an API key to be given with the -k option.

-b base

--base base

Set the base currency (when allowed by the site providing the data). base should be a 3-letter ISO currency code, e.g., ‘USD’. The specified currency will be the primitive currency unit used by units. You may find it convenient to specify your local currency. Conversions may be more accurate and you will be able to convert to your currency by simply hitting Enter at the ‘You want:’ prompt. This option is ignored if the source does not allow specifying the base currency. (Currently only floatrates supports this option.)

-k key

--key key

Set the API key to key for currency sources that require it.

--blskey BLSkey

Set the US Bureau of Labor Statistics (BLS) key for fetching CPI data. Without a BLS key you should be able to fetch the CPI data exactly one time per day. If you want to use a key you must request a personal key from BLS.