Caching requests from the UN Comtrade API

There is four reasons why we might want to use caching for our requests to the UN Comtrade API:

The UN Comtrade API at times can be a bit slow 🐌
Free users only have a limited amount of requests 💸
We might want to insulate our analysis against updates to the official data 📦
It saves energy and is climate friendly to not repeat requests that return the same data every time. 🌍

The package offers a caching option, that is fairly easy to use.

The basics of caching 💽

When you set the respective argument to TRUE, a directory named comtradr will be set up in your cache directory. This is determined by the tools::R_user_dir(which = 'cache') function. It has the default values for a cache as used by cachem::cache_disk.

See here: https://cachem.r-lib.org/reference/cache_disk.html

and here:https://stat.ethz.ch/R-manual/R-devel/library/tools/html/userdir.html

library(comtradr)
#### Now
q <- ct_get_data(reporter = "USA", 
               partner = c("DEU", "FRA", "JPN", "MEX"), 
               flow_direction = "import",
               start_date = 2020,
               end_date = 2023,
               cache = TRUE) # <----- set this argument to TRUE

If you want to modify these parameters, you need to set environment variables. You can use the usethis::edit_r_environ(scope = 'project) function to set them only for your current project.

ℹ️ Restart your R Session after setting the environment variables! 💡

The parameters are:

COMTRADR_CACHE_MAX_SIZE = Maximum size of the cache, in bytes. If the cache exceeds this size, cached objects will be removed according to the value of the evict. Use Inf for no size limit. The default is 1 gigabyte.
COMTRADR_CACHE_MAX_AGE = Maximum age of files in cache before they are evicted, in seconds. Use Inf for no age limit.
COMTRADR_CACHE_MAX_N = Maximum number of objects in the cache. If the number of objects exceeds this value, then cached objects will be removed according to the value of evict. Use Inf for no limit of number of items.
R_USER_CACHE_DIR = Directory where the cached files will be saved.

See here for the details on pruning and other functions of cachem: https://cachem.r-lib.org/reference/cache_disk.html

Careful with outdated data! ⚠️

The current default for the cache age is set to Inf, hence when you have requested data once, it will never downloaded again. For recent data, this can be a very bad idea, as the United Nations might update their data and you will only work with outdated data.

The recommended way is to set the COMTRADR_CACHE_MAX_AGE environment variable as described above. E.g.: to 60*60*24*365 for one year.

To find your cache and empty it by yourself, you can do:

## to delete all files in your cache
tools::R_user_dir('comtradr', which = 'cache') |> 
  fs::dir_delete()

and

## to delete all files in your cache
tools::R_user_dir('comtradr_bulk', which = 'cache') |> 
  fs::dir_delete()

You will have to restart comtradr to re-create the cache and be able to use the package.