library(rCAX)
#> Access and use of data in the CAX databases requires acceptance of the terms of use: rcax_termsofuse().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 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/caso 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.
The API key. rCAX includes a read-only API key but if you need to use your own, see section below.
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")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/caWe don’t need to pass in a key. rcax_GET() will look
this up from the .REnviron file using
check_key().
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.
{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.