
APIs
apis.Rmd
Set up WildTrax credentials
To obtain an Auth0 token, you must login into WildTrax using Auth0 (Google authorization is currently not supported). You also need to store your WildTrax user name and password as environment variables.
# Note that you need to use 'WT_USERNAME' and 'WT_PASSWORD'
Sys.setenv(WT_USERNAME = 'guest', WT_PASSWORD = 'Apple123')
Authenticate
Next, you use the wt_auth()
function to
authenticate.
# Authenticate
wt_auth()
#> Authentication into WildTrax successful.
The Auth0 token you obtained will last for 12 hours. After that time, you will need to re-authenticate.
Making API calls
Once authenticated, you can now use various functions that call upon
the WildTrax APIs. For instance, you can use
wt_get_download_summary()
to see basic metadata about
projects that you can download data for.
# Download the project summary you have access to
my_projects <- wt_get_download_summary(sensor_id = 'ARU')
head(my_projects)
#> # A tibble: 6 × 7
#> organization_id organization project project_id sensor tasks status
#> <int> <chr> <chr> <int> <chr> <int> <chr>
#> 1 5 ABMI ABMI Adopt-a-Came… 42 ARU 309 Publi…
#> 2 5 ABMI ABMI Amphibian Mo… 382 ARU 1528 Publi…
#> 3 5 ABMI Before-After Dose… 686 ARU 1873 Publi…
#> 4 5 ABMI Before-After Dose… 1174 ARU 1014 Publi…
#> 5 5 ABMI Before-After Dose… 2088 ARU 1212 Publi…
#> 6 5 ABMI Big Grids 381 ARU 2226 Publi…
Using the project_id number in the download summary you can then use
wt_download_report()
to access the species data. You can
also find the project_id number in the url of a WildTrax project,
e.g. https://portal.wildtrax.ca/home/aru-tasks.html?projectId=605&sensorId=ARU.
# Download the project report
my_report <- wt_download_report(project_id = 620, sensor_id = 'ARU', reports = "main", weather_cols = F) %>%
tibble::as_tibble()
head(my_report)
#> # A tibble: 6 × 31
#> organization project_id location location_id location_buffer_m longitude
#> <chr> <int> <chr> <int> <dbl> <dbl>
#> 1 BU 620 CHPP-WP-1 94515 NA -110.
#> 2 BU 620 CHPP-WP-1 94515 NA -110.
#> 3 BU 620 CHPP-WP-1 94515 NA -110.
#> 4 BU 620 CHPP-WP-1 94515 NA -110.
#> 5 BU 620 CHPP-WP-1 94515 NA -110.
#> 6 BU 620 CHPP-WP-1 94515 NA -110.
#> # ℹ 25 more variables: latitude <dbl>, equipment_make <chr>,
#> # equipment_model <chr>, recording_id <dbl>, recording_date_time <dttm>,
#> # task_id <dbl>, aru_task_status <chr>, task_duration <dbl>,
#> # task_method <chr>, species_code <chr>, species_common_name <chr>,
#> # species_scientific_name <chr>, individual_order <int>, tag_id <int>,
#> # individual_count <chr>, vocalization <chr>, detection_time <dbl>,
#> # tag_duration <dbl>, rms_peak_dbfs <dbl>, tag_is_verified <lgl>, …
An easy way to download multiple projects at once is to use
wt_get_download_summary()
and then filter by a substring in
order to get the project ids to download the data.
# Download all of the published Ecosystem Health ARU data to a single object
wt_get_download_summary(sensor_id = "ARU") %>%
tibble::as_tibble() %>%
dplyr::filter(grepl('^Ecosystem Health',project)) %>%
dplyr::mutate(data = purrr::map(.x = project_id, .f = ~wt_download_report(project_id = .x, sensor_id = "ARU", weather_cols = F, reports = "main")))
WildTrax also pre-formats ARU to point count (PC) data depending on the type of analysis you wish to perform. See the Boreal Avian Modelling project website and GitHub repositories to find out more on integration of avian point count and ARU data.
# As ARU format
my_report
#> # A tibble: 388 × 31
#> organization project_id location location_id location_buffer_m longitude
#> <chr> <int> <chr> <int> <dbl> <dbl>
#> 1 BU 620 CHPP-WP-1 94515 NA -110.
#> 2 BU 620 CHPP-WP-1 94515 NA -110.
#> 3 BU 620 CHPP-WP-1 94515 NA -110.
#> 4 BU 620 CHPP-WP-1 94515 NA -110.
#> 5 BU 620 CHPP-WP-1 94515 NA -110.
#> 6 BU 620 CHPP-WP-1 94515 NA -110.
#> 7 BU 620 CHPP-WP-1 94515 NA -110.
#> 8 BU 620 CHPP-WP-1 94515 NA -110.
#> 9 BU 620 CHPP-WP-1 94515 NA -110.
#> 10 BU 620 CHPP-WP-1 94515 NA -110.
#> # ℹ 378 more rows
#> # ℹ 25 more variables: latitude <dbl>, equipment_make <chr>,
#> # equipment_model <chr>, recording_id <dbl>, recording_date_time <dttm>,
#> # task_id <dbl>, aru_task_status <chr>, task_duration <dbl>,
#> # task_method <chr>, species_code <chr>, species_common_name <chr>,
#> # species_scientific_name <chr>, individual_order <int>, tag_id <int>,
#> # individual_count <chr>, vocalization <chr>, detection_time <dbl>, …
# As point count format
head(aru_as_pc)
#> # A tibble: 6 × 23
#> organization project project_id location location_id location_buffer_m
#> <chr> <chr> <int> <chr> <int> <dbl>
#> 1 BU Community - Co… 620 CHPP-WP… 94517 NA
#> 2 BU Community - Co… 620 CHPP-WP… 94518 NA
#> 3 BU Community - Co… 620 CHPP-WP… 89972 NA
#> 4 BU Community - Co… 620 CHPP-WP… 89972 NA
#> 5 BU Community - Co… 620 CHPP-WP… 89972 NA
#> 6 BU Community - Co… 620 CHPP-WP… 89972 NA
#> # ℹ 17 more variables: latitude <dbl>, longitude <dbl>, survey_id <chr>,
#> # survey_date <dttm>, survey_url <chr>, observer <chr>,
#> # survey_distance_method <chr>, survey_duration_method <chr>,
#> # detection_distance <chr>, detection_time <dbl>, species_code <chr>,
#> # species_common_name <chr>, species_scientific_name <chr>,
#> # individual_count <chr>, detection_heard <lgl>, detection_seen <lgl>,
#> # detection_comments <chr>
Species
Downloading the WildTrax species table with
wt_get_species()
also grants you access to other valuable
columns or provides a complete list of the species currently supported
by WildTrax.
# Download the WildTrax species table
spp_table <- wt_get_species()
spp_table |> arrange(species_code)
#> # A tibble: 5,335 × 6
#> species_id species_code species_common_name species_class species_order
#> <dbl> <chr> <chr> <chr> <chr>
#> 1 2780 10 Wolves, Coyotes and Alli… MAMMALIA Carnivora
#> 2 2705 100 Barren-ground Caribou MAMMALIA Artiodactyla
#> 3 2738 105 Porcupine Caribou MAMMALIA Artiodactyla
#> 4 2735 106 Peary Caribou MAMMALIA Artiodactyla
#> 5 2750 107 Varying Lemming MAMMALIA Rodentia
#> 6 2618 108 Bird AVES NA
#> 7 2616 109 Bear MAMMALIA Carnivora
#> 8 2694 110 Train NONE NA
#> 9 2728 114 Kermode Bear MAMMALIA Carnivora
#> 10 2819 129 Opossum MAMMALIA Didelphimorp…
#> # ℹ 5,325 more rows
#> # ℹ 1 more variable: species_scientific_name <chr>
You can also determine which species are allowed in and out of
projects via the wt_get_project_species()
function.
my_project_species <- wt_get_project_species(620)
my_project_species |>
filter(species_allowed_in_project == TRUE)
Data Discover
Explore species and data within WildTrax’s Data Discover by employing the
wt_dd_summary()
function. Access a portion of data, even
without user privileges. Utilize wt_auth()
to uncover data
pertinent to your account or those publicly available on WildTrax.
discover <- wt_dd_summary(sensor = "ARU", species = "White-throated Sparrow", boundary = NULL)
head(discover)
#> $`lat-long-summary`
#> # A tibble: 11 × 5
#> projectId project_name count species_common_name species_scientific_n…¹
#> <int> <chr> <dbl> <chr> <chr>
#> 1 2821 "CWS-ONT-Ontario … 469 White-throated Spa… ZONOTRICHIA ALBICOLLIS
#> 2 142 "ABMI-Ecosystem H… 280 White-throated Spa… ZONOTRICHIA ALBICOLLIS
#> 3 31 "BU-Community - C… 1232 White-throated Spa… ZONOTRICHIA ALBICOLLIS
#> 4 1070 "CWS-ONT-Ontario … 805 White-throated Spa… ZONOTRICHIA ALBICOLLIS
#> 5 19 "ABMI-Ecosystem H… 291 White-throated Spa… ZONOTRICHIA ALBICOLLIS
#> 6 34 "ABMI-Ecosystem H… 239 White-throated Spa… ZONOTRICHIA ALBICOLLIS
#> 7 1855 "CWS-ONT-Ontario … 1126 White-throated Spa… ZONOTRICHIA ALBICOLLIS
#> 8 33 "ABMI-Ecosystem H… 261 White-throated Spa… ZONOTRICHIA ALBICOLLIS
#> 9 1 "ABMI-Ecosystem H… 343 White-throated Spa… ZONOTRICHIA ALBICOLLIS
#> 10 659 "CWS-ONT-Ontario … 528 White-throated Spa… ZONOTRICHIA ALBICOLLIS
#> 11 NA "" 5311 White-throated Spa… ZONOTRICHIA ALBICOLLIS
#> # ℹ abbreviated name: ¹species_scientific_name
#>
#> $`map-projects`
#> # A tibble: 8,906 × 4
#> species_common_name count longitude latitude
#> <chr> <int> <dbl> <dbl>
#> 1 White-throated Sparrow 1 -135. 63.9
#> 2 White-throated Sparrow 1 -114. 49.0
#> 3 White-throated Sparrow 1 -114. 49.1
#> 4 White-throated Sparrow 1 -114. 49.1
#> 5 White-throated Sparrow 1 -114. 49.1
#> 6 White-throated Sparrow 1 -114. 49.1
#> 7 White-throated Sparrow 1 -114. 49.1
#> 8 White-throated Sparrow 1 -114. 49.1
#> 9 White-throated Sparrow 1 -114. 49.1
#> 10 White-throated Sparrow 1 -114. 49.1
#> # ℹ 8,896 more rows
Use custom bounding areas:
# Define a polygon
my_aoi <- list(
c(-113.96068, 56.23817),
c(-117.06285, 54.87577),
c(-112.88035, 54.90431),
c(-113.96068, 56.23817)
)
discover <- wt_dd_summary(sensor = "ARU", species = "White-throated Sparrow", boundary = my_aoi)
head(discover)
library(sf)
# Alberta bounding box
abbox <- read_sf("...shp") |> # Shapefile of Alberta
filter(Province == "Alberta") |>
st_transform(crs = 4326) |>
st_bbox()
discover <- wt_dd_summary(sensor = "ARU", species = "White-throated Sparrow", boundary = abbox)
head(discover)
Sync columns
wt_get_sync()
is the primary function used to access
WildTrax sync APIs, such as getting locations, visits,
equipment, project tasks and tags and more.
my_project_tasks <- wt_get_download_summary('ARU') |>
filter(grepl('Cypress', project)) |>
select(project_id) |>
pull() |>
(\(proj_id) wt_get_sync("download-tasks-by-project-id", option = "data", project = proj_id))()
my_project_tasks