R Package

hawkinR

An R interface to the Hawkin Dynamics API. Simple authentication, region-aware routing, and tidy data frames for sport scientists and analysts.

Version

1.1.5

Platform

R ≥ 3.5.0

License

MIT

Installation

Install hawkinR from GitHub using devtools.

# Install devtools if you don't have it install.packages("devtools") # Install hawkinR from GitHub devtools::install_github("HawkinDynamics/hawkinR")

Authentication

hawkinR uses a simple authentication flow. Set your refresh token as an environment variable and connect.

Set Your Environment Variable

Set HD_REFRESH_TOKEN in your .Renviron file. Run usethis::edit_r_environ() to open it.

Connect to the API

Use get_access(region = "Americas") to authenticate. This exchanges your refresh token for an access token automatically.

Start Querying

All get_*() functions use the active session automatically. No token management needed.

Quick Start

A complete, runnable script to get your first data.

library(hawkinR) # 1. Authenticate with the Hawkin Cloud get_access(region = "Americas") # 2. Get your organization data roster <- get_athletes() teams <- get_teams() groups <- get_groups() # 3. Get test data for the past 30 days tests <- get_tests( from = "2024-01-01", to = "2024-01-31" ) # 4. View your data head(tests)

Regional Endpoints

Set the region parameter in get_access() to match your organization's data residency.

Region	Value	Base URL
Americas	`"Americas"`	`cloud.hawkindynamics.com`
Europe	`"Europe"`	`eu.cloud.hawkindynamics.com`
Asia-Pacific	`"APAC"`	`apac.cloud.hawkindynamics.com`

Tutorials & Guides

User Guide

In-depth tutorials covering authentication, data retrieval, force-time analysis, logging, and integrating hawkinR into web applications.

Getting Started with hawkinR

hawkinR manages the exchange of your Integration Key (Refresh Token) for an ephemeral Access Token automatically in the background.

Setting Up Your Token

Store your refresh token as an environment variable in your .Renviron file. This keeps your key out of your scripts and available across sessions.

# Add this line to your .Renviron file (run usethis::edit_r_environ()) HD_REFRESH_TOKEN="your_token_here"

Connecting to the Cloud

Use get_access() to initialize your session. This exchanges your refresh token for an access token automatically.

library(hawkinR) # Authenticate with the Hawkin Cloud get_access(region = "Americas")

Exploring Your Organization

Once connected, retrieve the structural data of your organization. These IDs are used as filters when pulling performance tests.

# Store organizational data roster <- get_athletes() teams <- get_teams() groups <- get_groups()

Authentication Deep Dive

hawkinR provides flexible authentication options for different deployment scenarios.

Environment Variable (Recommended)

Set your refresh token as an environment variable for persistent, secure access across sessions.

# Add to your .Renviron file (run usethis::edit_r_environ()) HD_REFRESH_TOKEN="your_refresh_token_here"

# Then in your R script library(hawkinR) get_access(region = "Americas")

Direct Token

Pass your refresh token directly for quick testing or one-off scripts.

get_access( refreshToken = "your_refresh_token_here", region = "Americas" )

Cloud Deployment

When deploying to a server (ShinyApps.io, Posit Connect, Docker), set the HD_REFRESH_TOKEN environment variable on your hosting platform.

# Connect using the env var set on your platform get_access(region = "Americas") # The rest of your code remains identical df <- get_tests()

Function	Purpose
`get_access(region)`	Authenticates and initializes the active session
`get_tests(...)`	Fetches data using the current active session

Getting Tests

The get_tests() function is the primary tool for querying performance data. This function provides unified access to test data with flexible filtering.

Note: get_tests_ath(), get_tests_team(), get_tests_group(), and get_tests_type() are deprecated. Use get_tests() with filter parameters instead.

Basic Usage

Provide a date range using standard date strings or Unix timestamps.

get_access(region = "Americas") # All tests all_tests <- get_tests() # Tests from start of 2023 to present tests <- get_tests(from = "2023-01-01")

Filter by Test Type

Use canonical ID, test type name, or abbreviation.

# By abbreviation cmj_data <- get_tests(typeId = "CMJ") sj_data <- get_tests(typeId = "SJ") # By full name iso_data <- get_tests(typeId = "Isometric Test")

Filter by Athletes, Teams, or Groups

# By athlete athlete_id <- roster$id[roster$name == "Some Athlete"] ath_tests <- get_tests(athleteId = athlete_id) # By team (accepts vectors) team_ids <- c("team_id_1", "team_id_2") cohort_data <- get_tests(teamId = team_ids)

Important: Tests can only be filtered by one entity type at a time plus a time frame. You cannot combine teamId and groupId in the same call.

The Sync Parameter

For incremental refresh logic, use sync = TRUE to pull data based on when it was uploaded/modified rather than when the test occurred.

# Pull everything synced in the last 24 hours last_24h <- as.numeric(Sys.time()) - 86400 new_data <- get_tests(from = last_24h, sync = TRUE)

Data Structure

The returned data frame is organized into four logical sections:

Section	Contents
Trial Info	Basic trial metadata (ID, timestamp)
Test Type Info	Details about the movement performed
Athlete Info	Athlete details (name, teams, groups, external)
Metrics	All performance metrics (Force, Velocity, Power, etc.)

Including Inactive Data

By default, only "Active" trials are returned. For auditing, set includeInactive = TRUE.

Accessing Force-Time Data

Use get_forcetime() to access the high-frequency raw data (1000Hz) from test trials.

Fetching a Single Test

Get the unique id from get_tests(), then fetch the raw data.

# Find a CMJ from yesterday recent <- get_tests(typeId = "CMJ", from = Sys.Date() - 1) target_id <- recent$id[1] # Fetch raw force-time data ft_obj <- get_forcetime(testId = target_id) # Access metadata ft_obj@athlete_name #> "John Doe" ft_obj@testType_name #> "Countermovement Jump" # Access the raw data frame head(ft_obj@data)

Plotting

plot( x = ft_obj@data$time_s, y = ft_obj@data$force_combined_N, type = "l", col = "blue", main = paste("Jump Trace:", ft_obj@athlete_name), xlab = "Time (s)", ylab = "Force (N)" )

Logging Features

hawkinR uses the logger package to provide status changes, background processes, and debugging information. Logging is initialized automatically when you call get_access().

Log Levels

Use initialize_logger() to configure logging:

Level	Use Case
`TRACE`	Detailed execution logs including request paths
`DEBUG`	Information useful for debugging
`INFO`	(Default) Standard process updates
`WARN`	Warnings about token expiration or non-critical issues
`ERROR`	Critical failures only

Verbose Debugging

# Detailed TRACE logging get_access(region = "Americas") initialize_logger(log_threshold_stdout = "TRACE") # Logs will show exact API request parameters tests <- get_tests(from = "2023-01-01")

Silent Operation (Production)

# Only log critical failures get_access(region = "Americas") initialize_logger(log_threshold_stdout = "ERROR")

Logging to Files

get_access(region = "Americas") # Redirect logs to a file for auditing logger::log_appender(logger::appender_file("hawkin_audit.log"))

Integrating hawkinR with Web Applications

hawkinR integrates easily with Shiny apps, Plumber APIs, and containerized environments.

Shiny

Use get_access() with the HD_REFRESH_TOKEN environment variable configured on your hosting platform (ShinyApps.io, Posit Connect).

library(shiny) library(hawkinR) # Connect once at app startup (reads HD_REFRESH_TOKEN env var) get_access(region = "Americas") ui <- fluidPage( titlePanel("Hawkin Dashboard"), actionButton("refresh", "Refresh Data"), tableOutput("tests_table") ) server <- function(input, output, session) { test_data <- reactiveVal() observeEvent(input$refresh, { test_data(get_tests(from = Sys.Date() - 7)) }) output$tests_table <- renderTable({ req(test_data()) head(test_data(), 20) }) } shinyApp(ui, server)

Tip: On ShinyApps.io, set the HD_REFRESH_TOKEN environment variable in your app's Settings → Environment Variables panel. On Posit Connect, use the "Vars" tab in the content settings.

Plumber API

Serve Hawkin data as REST endpoints. Connect on startup, let Plumber handle requests.

# plumber.R library(hawkinR) # Connect at startup get_access(region = "Americas") #* Get recent tests #* @param days Number of days to look back #* @get /tests function(days = 7) { get_tests(from = Sys.Date() - as.numeric(days)) } #* Get athlete roster #* @get /athletes function() { get_athletes() }

Docker

Pass the token as an environment variable when running the container.

# Dockerfile FROM rocker/shiny:latest RUN R -e "devtools::install_github('HawkinDynamics/hawkinR')" COPY app/ /srv/shiny-server/ # Run with token injected # docker run -e HD_REFRESH_TOKEN=your_token -p 3838:3838 myapp

API Reference

Function Reference

Complete documentation for all public hawkinR functions — signatures, parameters, return values, and examples.

Authentication

get_access(refreshToken, region, org_name)

Authenticates with the Hawkin Dynamics API by exchanging your refresh token for an access token. Sets the active session for subsequent data calls.

Parameters

Name	Type	Default	Description
`refreshToken`	character	NULL	Your API refresh token. If NULL, reads from `HD_REFRESH_TOKEN` environment variable
`region`	character	"Americas"	API region: "Americas", "Europe", or "APAC"
`org_name`	character	NULL	Optional organization name for display

Returns

Invisibly returns the access token. Sets the active session for use by all get_*() functions.

Example

# Using environment variable (recommended) get_access(region = "Americas") # Using direct token get_access(refreshToken = "your_token", region = "Americas")

Data Retrieval

get_tests(from, to, sync, athleteId, typeId, teamId, groupId, includeInactive)

Retrieves test data from the Hawkin Dynamics API. Supports filtering by athlete, team, group, test type, and date range.

Parameters

Name	Type	Default	Description
`from`	int / chr	NULL	Start time. Unix timestamp or "YYYY-MM-DD"
`to`	int / chr	NULL	End time. Unix timestamp or "YYYY-MM-DD". Defaults to now
`sync`	logical	FALSE	If TRUE, includes updated and newly created tests
`athleteId`	character	NULL	Filter by specific athlete ID
`typeId`	character	NULL	Filter by test type (canonical ID, name, or abbreviation)
`teamId`	chr / list	NULL	Filter by team ID(s). Max 10
`groupId`	chr / list	NULL	Filter by group ID(s). Max 10
`includeInactive`	logical	FALSE	Include inactive tests

Returns

Data frame containing test trials and their metrics. Each row represents a single test trial.

Examples

# All tests (uses active connection) dfAllTests <- get_tests() # Specific date range dfFromTo <- get_tests(from = "2023-08-01", to = "2023-08-10") # Filter by athlete and test type dfFiltered <- get_tests(athleteId = "abc123", typeId = "CMJ")

get_forcetime(testId)

Retrieves the raw force-time data for a specific test trial ID. Returns time-series arrays sampled at 1000 Hz.

Parameters

Name	Type	Default	Description
`testId`	character	—	The unique identifier for the test trial

Returns

A HawkinForceTime object containing force-time series data.

get_metrics(testType)

Get all metrics and their IDs. Can be filtered by test type using canonical ID, name, or abbreviation (e.g., "CMJ", "SJ", "ISO", "DJ").

Parameters

Name	Type	Default	Description
`testType`	character	"all"	Canonical test ID, test type name, or abbreviation

Returns

Data frame with columns: canonicalTestTypeID, testTypeName, id, label, label_unit, header, units, description.

Example

df_metrics <- get_metrics(testType = "CMJ")

Organization

get_athletes(includeInactive)

Get all athletes for an account. Inactive athletes only included if includeInactive is TRUE.

Parameters

Name	Type	Default	Description
`includeInactive`	logical	FALSE	Include inactive athletes

Returns

Data frame with columns: id, name, active, teams, groups, external properties.

Example

# Active athletes only df_athletes <- get_athletes() # Include inactive df_all <- get_athletes(includeInactive = TRUE)

get_teams()

Get team names and IDs for all teams in the organization.

Returns

Data frame with columns: id, name.

Example

df_teams <- get_teams()

get_groups()

Get group names and IDs for all groups in the organization.

Returns

Data frame with columns: id, name.

Example

df_groups <- get_groups()

get_tags()

Get tag names and IDs for all tags in the system.

Returns

Data frame with columns: id, name, description.

Example

df_tags <- get_tags()

Athlete Management

create_athletes(athleteData)

Create new athletes for an account. Bulk create up to 500 athletes at a time.

Parameters

Name	Type	Default	Description
`athleteData`	data.frame	—	Athletes to create. Required column: `name`. Optional: `image`, `active`, `teams`, `groups`, plus any external property columns

Returns

Prints confirmation with count of created athletes. If failures, returns data frame with reason and name columns.

Example

df <- data.frame( name = c("John Doe", "Jane Smith"), active = c(TRUE, TRUE) ) create_athletes(athleteData = df)

update_athletes(athleteData)

Update existing athletes. Bulk update up to 500 at a time. Optional fields not present are left unchanged, but external properties not included will be removed.

Parameters

Name	Type	Default	Description
`athleteData`	data.frame	—	Athletes to update. Required column: `id`. Optional: `name`, `image`, `active`, `teams`, `groups`, external properties

Warning: When updating external properties, any custom properties not present in the request will be removed. Always include all external properties you want to keep.

Configuration

initialize_logger(log_output, log_threshold_stdout, log_file, log_threshold_file)

Initialize the logger with custom output destination and log thresholds for stdout and file.

Parameters

Name	Type	Default	Description
`log_output`	character	"stdout"	"stdout", "file", or "both"
`log_threshold_stdout`	character	"INFO"	"TRACE", "DEBUG", "INFO", "WARN", "ERROR", "FATAL"
`log_file`	character	"hawkinRlog.log"	Custom log file name/path
`log_threshold_file`	character	"INFO"	Log threshold for the file output

Example

# Debug to console initialize_logger(log_output = "stdout", log_threshold_stdout = "DEBUG") # Trace to file initialize_logger(log_output = "file", log_file = "app/mylog", log_threshold_file = "TRACE")

Version History

Changelog

Release notes and version history for hawkinR.

2024

v1.1.0 – v1.1.5

Updated Fixed

Unified get_tests, logging, bug fixes

Updated get_tests() with unified filtering
Deprecated get_tests_* functions
teamId and groupId now accept lists and vectors
Added logging functionality and customization
TruStrength test types support
Various bug fixes for tags, date formatting

2023

v1.0.0 – v1.0.5

Added

Initial release

Core functions: get_tests_*, get_athletes, get_teams, get_groups, get_forcetime
Added get_tags(), typeId abbreviations
Tag details in test outputs
External ID and sync support