nert

Using Your .Renviron File

You can store the TERN API Key in your .Renviron file as follows:

1. Open your .Renviron file. (An easy way to open this file is to use the {usethis} package in your R session, e.g., usethis::edit_r_environ().) In your .Renviron file, add a new line to set a variable called TERN_API_KEY, and paste in the API key you copied earlier as the value for the variable. Note that this is the variable that the {nert} package automatically looks for during the authentication, so be sure to double-check that the spelling and case are correct for the variable name.

   TERN_API_KEY='<paste your key here>'

   

2. Save your .Renviron file, and restart your R session so that the change is applied. Once you have restarted your R session, you can then test that the {nert} package is reading your API key properly by running nert::get_key() at the R command console. If the API key was successfully read by {nert}, then you should see your API key appear verbatim as output.

   

3. Finally, you can quickly test that the data download from the TERN Data Portal is working correctly by downloading a data raster. The below R code retrieves the SMIPS “totalbucket” soil moisture data raster for January 1st, 2024 using the nert::read_smips() function, and then uses the {terra} package’s terra::extract() function to get a point value for the soil moisture measurement at the Adelaide CBD (at approximately 138.6007 decimal degrees Easting for the longitude, and -34.9285 decimal degrees Northing for the latitude):

   library(nert)
   library(terra)
   
   r <- read_smips(date = "2024-01-01")
   
   extract(r, xy = TRUE, data.frame(lon = 138.6007, lat = -34.9285))
   #>   ID smips_totalbucket_mm_20240101        x         y
   #> 1  1                      46.07692 138.6037 -34.93254

At this stage your {nert} package is now working, and you can use it to easily download COG data from the TERN Data Portal.

Using the {keyring} Package for Secure Storage

If you prefer a more secure method, you can use the {keyring} package to store your TERN API Key in your system’s credential store.

1. If you don’t have the {keyring} package installed, you can install it with:

   install.packages("keyring")

2. Once {keyring} is installed, you can store your API key using the keyring::keyring_create() and keyring::key_set() functions as follows:

   library(keyring)
   
   keyring_create("nert")
   key_set("TERN_API_KEY", keyring = "nert")

   This will create a new keyring called nert, with a new key called TERN_API_KEY. The function will then prompt you for the actual key value, which you can paste from the TERN website where you copied it earlier. You can then verify that the key was stored as expected by using the keyring::key_get() function:

   key_get("TERN_API_KEY", keyring = "nert")

3. Finally, you can quickly check that the TERN API key is working with the {nert} package correctly by trying to download a raster. The below R code retrieves the SMIPS “totalbucket” soil moisture data raster for January 1st, 2024 using the nert::read_smips() function, and then uses the {terra} package’s terra::extract() function to get a point value for the soil moisture measurement at the Adelaide CBD (at approximately 138.6007 decimal degrees Easting for the longitude, and -34.9285 decimal degrees Northing for the latitude). Note that we explicitly specify to use the TERN_API_KEY we stored in the nert keyring by setting the api_key argument:

   library(nert)
   library(keyring)
   
   r <- read_smips(
     date = "2024-01-01",
     api_key = key_get("TERN_API_KEY", keyring = "nert")
   )
   
   extract(r, xy = TRUE, data.frame(lon = 138.6007, lat = -34.9285))

Reading TERN Data

You can use the nert::read_smips() function to retrieve rasters for the SMIPS datasets available on the TERN Data Portal, using the date argument to specify the date for the raster to be retrieved, and the collection argument to specify which specific SMIPS dataset to download. For instance, the following R code retrieves the “SMindex” raster for June 30, 2025:

library(nert)
r <- read_smips(date = "2025-06-30", collection = "SMindex")

Note that {nert} re-exports tidyterra::autoplot() for ease of visualising the TERN data.

autoplot(r)
#> <SpatRaster> resampled to 501270 cells.

However, if you wish to fetch only data for a single point or points, you can use the terra::extract() function. Since the rasters are stored on the TERN Data Portal as Cloud-Optimised GeoTIFFs (COGs), terra::extract() is very time- and space-efficient, streaming only the bytes needed for the spatial extent that you ask for. The below R code downloads only the data at the coordinates specified, rather than fetching the entire dataset:

library(terra)

extract(r, xy = TRUE, data.frame(lon = 138.6007, lat = -34.9285))
#>   ID smips_smi_perc_20250630        x         y
#> 1  1               0.1554503 138.6037 -34.93254

Reading rasters for the other available datasets works mostly the same way. For example, the below R code retrieves the raster for the Australian Soil Classification Map using the nert::read_asc() function. Since this is a static dataset, you do not need to specify a date. By default, the soil classifications are retrieved:

asc <- read_asc()

autoplot(asc)
#> <SpatRaster> resampled to 500388 cells.

If you wanted to see the confusion index instead (which provides a measure of the uncertainty associated with each classification), you can specify that dataset using the collection argument:

asc_ci <- read_asc(collection = "CI")

The SLGA soil attribute rasters work similarly, but have an additional depth parameter that you can specify. For instance, the following R code fetches and views the raster for the soil clay content at a depth of 30-60cm by specifying the depth argument:

cly <- read_slga("CLY", depth = "030_060")

autoplot(cly)
#> <SpatRaster> resampled to 500388 cells.

That’s it, you’re all set!