Currency (Units: A Unit Conversion Program and Scientific Calculator)

## 21 Updating Currency Exchange Rates and CPI ¶

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

### 21.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), not seasonally adjusted—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/). These data update 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.

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