rCAX API query function

library(rCAX)

The main behind the scenes function is rcax_GET(path, key = NULL, query=NULL, ...) which appears in functions rcax_table_query() and rcax_datasets().

`rcax_GET` arguments

path

path is whatever comes after https://api.streamnet.org/api/v1 in an API call.

For HLI tables the url is

https://api.streamnet.org/api/v1/ca

so path="ca". I don’t think you need ca.json since JSON is the default. But maybe would be good to add that to make code more robust.

key

The API key. rCAX includes a read-only API key but if you need to use your own, see section below.

query

This has to be a LIST of your query parameters (stuff that appears after ? in the url for an API call). So like this:

list(table_id="whatevertableidis")

CAX Query URL

The basic format of a query to the CAX API will look like this

https://api.streamnet.org/api/v1/ca.json?table_id=4EF09E86-2AA8-4C98-A983-A272C2C2C7E3&XApiKey=<your stored key>&filter=[{"field":"popid","value":"7","type":"string"}]

Here we are filtering on popid equal to 7 using the filter specified with JSON. See rcax_filter() for a function to create the JSON from a list of colnames and values.

The rcax_GET() call would look like

qlist <- list(
  table_id=4EF09E86-2AA8-4C98-A983-A272C2C2C7E3,
  filter=rcax_filter(list(popid=7))
)
rcax_GET("ca", query=qlist)

This will make the API URL

https://api.streamnet.org/api/v1/ca

We don’t need to pass in a key. rcax_GET() will look this up from the .REnviron file using check_key().

Finding the table id

The table_id are stored in rCAX:::caxtabs as internal data using a call to rcax_datasets(). The function returns the name and id for the tables in the CAX API. caxtabs will need to be updated or checked periodically.

In rcax_table_query(), the table_id is looked up using a table name. The table names for the HLI short code names are hard coded in rcax_table_name(). If the names change, they should be updated here.

API key

{rCAX} includes a “read-only” API key. Thus for normal read-only use, you do not need an API key. If you need to use your own key, contact StreamNet. You can pass in your own key into calls via GETargs$key.

Alternatively you can set it as as an environment variable called CAX_KEY in your .Renviron file by pasting this text into that file: CAX_KEY='youractualkeynotthisstring'. To do this, install the {usethis} package.

install.packages("usethis")

Then run this code to find or create your .Renviron file. It will tell you where the .Renviron file is.

usethis::edit_r_environ()

Open that file and paste in CAX_KEY = "whateveryourkeyis" into the file and save. After you edit the file, you will need to restart R. If you are in RStudio use Session > Restart R. Now your API will be visible to {rCAX}. Note, if for some reason, you need to access to this key in your code, use Sys.getenv("CAX_KEY", ""). This retrieves variables defined in the .Renviron file, which are loaded into the system environment when you start up R.