| Title: | Interface to the 'Hawkin Dynamics' Force Platform API |
|---|---|
| Description: | Provides a secure and configurable interface to the 'Hawkin Dynamics' API for accessing athlete performance data, tests, and metadata. The package supports profile-based authentication with secure credential storage via the operating system keychain, automatic access token refresh, and region-aware API routing. Designed for reproducible analysis, data synchronization workflows, and production deployment. |
| Authors: | Lauren Green [aut, cre] |
| Maintainer: | Lauren Green <[email protected]> |
| License: | MIT + file LICENSE |
| Version: | 2.0.0 |
| Built: | 2026-07-19 15:42:28 UTC |
| Source: | https://github.com/cran/hawkinR |
Defines the S7 classes and methods for managing authentication state, secure credential storage, and session configuration.
Create a new athlete or athletes for an account. Bulk create up to 500 athletes at a time.
create_athletes(athleteData, ...)create_athletes(athleteData, ...)
athleteData |
A data frame of the athletes to be created. The data frame must follow the schema: |
... |
Optional arguments.
|
The data frame passed as the argument must use the following schema:
| Column Name | Type | Inclusion | Description |
| name | chr | REQUIRED | athlete's given name (First Last) |
| image | chr | optional | URL path to image. default = null |
| active | logi | optional | athlete is active (TRUE). default = null |
| teams | list | optional | a single team id as a string or list of team ids. default = [defaultTeamId] |
| groups | list | optional | a single group id as a string or list of group ids. default = [] |
| external property | chr | optional | External properties can be added by adding any additional columns of equal length. The name of the column will become the external property name, and the row value will become the external property value. Use "lowercase" or "snake_case" styles for column names. |
If successful, a confirmation message will be printed with the number of successful athletes created. If there are failures, a data frame containing the athletes that failed to be created will be returned with columns:
| Column Name | Type | Description |
| reason | chr | Reason for failed creation |
| name | chr | Athlete's given name (First Last) |
## Not run: # Example data frame following the required schema df <- data.frame( name = c("John Doe", "Jane Smith"), image = c("https://example.com/johndoe.jpg", "https://example.com/janesmith.jpg"), active = c(TRUE, FALSE), teams = I(list("team1", c("team2", "team3"))), groups = I(list(NULL, "group1")), external_property = c("value1", "value2") ) # Create athletes using the example data frame create_athletes(athleteData = df) ## End(Not run)## Not run: # Example data frame following the required schema df <- data.frame( name = c("John Doe", "Jane Smith"), image = c("https://example.com/johndoe.jpg", "https://example.com/janesmith.jpg"), active = c(TRUE, FALSE), teams = I(list("team1", c("team2", "team3"))), groups = I(list(NULL, "group1")), external_property = c("value1", "value2") ) # Create athletes using the example data frame create_athletes(athleteData = df) ## End(Not run)
Get the athletes for an account. Inactive players will only be included if
includeInactive parameter is set to TRUE.
get_athletes(includeInactive = FALSE, ...)get_athletes(includeInactive = FALSE, ...)
includeInactive |
FALSE by default to exclude inactive players in database. Set to TRUE if you want inactive players included in the return. |
... |
Optional arguments.
|
Response will be a data frame containing the athletes that match this query. Each athlete includes the following variables:
| Column Name | Type | Description |
| id | chr | athlete's unique ID |
| name | chr | athlete's given name (First Last) |
| active | bool | athlete is active (TRUE) |
| teams | chr | team ids separated by "," |
| groups | chr | group ids separated by "," |
| image | chr | URL to the athlete's profile image. NA when never set or cleared. |
| position | chr | Free-text playing position (e.g. "Forward"). NA when blank. |
| dob | chr | Date of birth as an ISO-8601 date string (YYYY-MM-DD). NA when blank. |
| sport | chr | Free-text sport name (e.g. "Basketball"). NA when blank. |
| height | num | Athlete height in centimeters when present. NA otherwise. |
| lastTestedOn | num | Unix epoch seconds of the athlete's most recent test session. NA when no tests on file. |
| external | chr | external properties will have a column of their name with the appropriate values for the athlete of NA if it does not apply
|
The optional profile columns (image, position, dob, sport, height, lastTestedOn) and any external property columns only appear when at least one athlete in the response has that field populated.
## Not run: # This is an example of how the function would be called. If you only wish to call active players, # you don't need to provide any parameters. df_athletes <- get_athletes() # If you want to include all athletes, including inactive athletes, include the optional # `includeInactive` parameter. df_wInactive <- get_athletes( includeInactive = TRUE) ## End(Not run)## Not run: # This is an example of how the function would be called. If you only wish to call active players, # you don't need to provide any parameters. df_athletes <- get_athletes() # If you want to include all athletes, including inactive athletes, include the optional # `includeInactive` parameter. df_wInactive <- get_athletes( includeInactive = TRUE) ## End(Not run)
Retrieves the raw Center of Pressure (COP) time-series data for a specific test trial ID. COP data is exclusive to the "Free Run" test type — any other test type returns a 404.
get_cop(testId, ...)get_cop(testId, ...)
testId |
character. The unique identifier for the test trial. |
... |
Optional arguments.
|
A HawkinCOP object. The data data frame contains the columns
time_s, cop_x, cop_y, left_cop_x, left_cop_y, right_cop_x, and
right_cop_y. COP values are in millimeters relative to plate center and
may be NA for samples where no weight is on a given plate.
Retrieves the raw force-time data for a specific test trial ID.
get_forcetime(testId, ...)get_forcetime(testId, ...)
testId |
character. The unique identifier for the test trial. |
... |
Optional arguments.
|
A HawkinForceTime object.
Retrieves raw force-time data for multiple tests. This function acts as a wrapper
for both get_tests and get_forcetime.
get_forcetime_bulk( test_ids = NULL, export = FALSE, export_dir = NULL, format = c("csv", "json", "rds", "rda", "tsv", "parquet"), file_naming = c("test_id"), deidentify = FALSE, ... )get_forcetime_bulk( test_ids = NULL, export = FALSE, export_dir = NULL, format = c("csv", "json", "rds", "rda", "tsv", "parquet"), file_naming = c("test_id"), deidentify = FALSE, ... )
test_ids |
Optional. A character vector of specific Test IDs, or a data frame
containing an |
export |
logical. If TRUE, data is written to files in |
export_dir |
character. The directory path to save exported files. |
format |
character. Options: "csv", "tsv", "json", "rds", "parquet". |
file_naming |
character vector. Properties to construct the filename. |
deidentify |
logical. If TRUE, replaces |
... |
Additional arguments passed to |
When export = FALSE (the default), a named list of raw
force-time results, one element per requested test. When
export = TRUE, a character vector of the file paths written to
export_dir, returned invisibly. Returns NULL if no matching
tests are found.
Get the group names and ids for all the groups in the org.
get_groups(...)get_groups(...)
... |
Optional arguments.
|
Response will be a data frame containing the groups that are in the organization. Each group has the following variables:
| Column Name | Type | Description |
| id | chr | group's unique ID |
| name | chr | group's given name |
## Not run: # This is an example of how the function would be called. df_groups <- get_groups() ## End(Not run)## Not run: # This is an example of how the function would be called. df_groups <- get_groups() ## End(Not run)
Get the metrics and ids for all the metrics in the system.
get_metrics(testType = "all")get_metrics(testType = "all")
testType |
Supply a value of type string. Must be canonical test Id, test type name, or test name abbreviation. Names | Abbreviations: "Countermovement Jump" | "CMJ", "Squat Jump" | "SJ", "Isometric Test" | "ISO", "Drop Jump" | "DJ", "Free Run" | "FREE", "CMJ Rebound" | "CMJR", "Multi Rebound" | "MR", "Weigh In" | "WI", "Drop Landing" | "DL", "TS Isometric Test" | "TSISO", "TS Free Run" | "TSFREE" |
Response will be a data frame containing the tests metrics that are in the HD system. The parameter
testType can be used to filter and return only metrics of the specified type.
The returned data frame will follow the following schema:
| Column Name | Type | Description |
| canonicalTestTypeID | chr | Canonical Test Id |
| testTypeName | chr | Given Test Name |
| id | chr | camelCase Test Name |
| label | chr | Outward facing label or title |
| label_unit | chr | Outward facing label or title w/ unit of measure |
| header | chr | header of data frame output |
| units | chr | Unit of measure (if any) |
| description | chr | Description or definition of metric |
## Not run: # This is an example of how the function would be called. df_testsMetrics <- get_metrics(testType = "CMJ") ## End(Not run)## Not run: # This is an example of how the function would be called. df_testsMetrics <- get_metrics(testType = "CMJ") ## End(Not run)
Get the tag names and ids for all the tags in the system.
get_tags(...)get_tags(...)
... |
Optional arguments.
|
Response will be a data frame containing the tags that are in the organization. Each tag has the following variables:
| Column Name | Type | Description |
| id | chr | tag's unique ID |
| name | chr | tag's given name |
| description | chr | description of tag provided by user |
## Not run: # Use active connection df_tags <- get_tags() # Use a specific profile by name df_tags_dev <- get_tags(profile = "my_dev_profile") ## End(Not run)## Not run: # Use active connection df_tags <- get_tags() # Use a specific profile by name df_tags_dev <- get_tags(profile = "my_dev_profile") ## End(Not run)
Get the team names and ids for all the teams in the org.
get_teams(...)get_teams(...)
... |
Optional arguments.
|
Response will be a data frame containing the teams that are in the organization. Each team has the following variables:
| Column Name | Type | Description |
| id | chr | team's unique ID |
| name | chr | team's given name |
## Not run: # This is an example of how the function would be called. df_teams <- get_teams() ## End(Not run)## Not run: # This is an example of how the function would be called. df_teams <- get_teams() ## End(Not run)
Retrieves test data from the Hawkin Dynamics API. This function replaces all previous
get_tests_* functions. It can filter by athlete, team, group, date range, or sync timestamp.
get_tests( from = NULL, to = NULL, sync = FALSE, athleteId = NULL, typeId = NULL, teamId = NULL, groupId = NULL, includeInactive = FALSE, includeEid = FALSE, ... )get_tests( from = NULL, to = NULL, sync = FALSE, athleteId = NULL, typeId = NULL, teamId = NULL, groupId = NULL, includeInactive = FALSE, includeEid = FALSE, ... )
from |
Optionally supply a time frame start value. Accepts either:
Optional. If not supplied, no lower bound is applied and all available history is returned. |
to |
Optionally supply a time frame end value. Accepts either:
Optional. If not supplied, no upper bound is applied (results run through the most recent test). |
sync |
The result set will include updated and newly created tests. This parameter is best suited to keep your database in sync with the Hawkin database. If you do not supply this value you will receive every test. |
athleteId |
Supply an athlete’s id to receive tests for a specific athlete |
typeId |
Supply a value of type string. Must be canonical test Id, test type name, or test name abbreviation. Names | Abbreviations: "Countermovement Jump" | "CMJ", "Squat Jump" | "SJ", "Isometric Test" | "ISO", "Drop Jump" | "DJ", "Free Run" | "FREE", "CMJ Rebound" | "CMJR", "Multi Rebound" | "MR", "Weigh In" | "WI", "Drop Landing" | "DL", "TS Free Run" | "TSFR", "TS Isometric Test" | "TSISO" |
teamId |
Supply a team’s ID, a list of team IDs, or a string of a comma separated team id’s to receive tests from the specified teams. A maximum of 10 teams can be fetched at once. |
groupId |
Supply a group’s ID, a list of group IDs, or a string of a comma separated group id’s to receive tests from the specified groups. A maximum of 10 groups can be fetched at once. |
includeInactive |
Logical. Default |
includeEid |
Logical. Default |
... |
Optional arguments.
|
Pagination: This function uses cursor-based pagination (API v1.13+) to reliably fetch all matching tests regardless of dataset size. The API returns pages of up to 1,000 tests each. The function loops automatically until all pages are retrieved.
If from is provided, it is used as a time-range filter.
If from is NOT provided, no lower bound is applied and all available
history is returned. Pagination handles arbitrarily large result sets.
If to is NOT provided, no upper bound is applied (results run through the
most recent test).
Schema Handling:
Because metrics may be added to the system over time, older test results might have fewer
columns than newer ones. This function uses dplyr::bind_rows to combine pages, filling
missing columns with NA where necessary.
Athlete columns:
The athlete block is prefixed with athlete_ and includes the core fields
(athlete_id, athlete_name, athlete_active, athlete_teams, athlete_groups),
the API v1.14 profile fields when present (athlete_image, athlete_position,
athlete_dob, athlete_sport, athlete_height, athlete_lastTestedOn), and one
athlete_<key> column per external (custom) property. Athletes missing a given
external key receive NA.
A data frame containing test trials and their metrics. Each row represents a single test trial. (if specified).
## Not run: # Call for all tests (active connection) dfAllTests <- get_tests() # Call for all tests within a specific time frame dfFromTo <- get_tests(from = "2023-08-01", to = "2023-08-10") # Include inactive tests dfAll <- get_tests(from = "2023-08-01", includeInactive = TRUE) ## End(Not run)## Not run: # Call for all tests (active connection) dfAllTests <- get_tests() # Call for all tests within a specific time frame dfFromTo <- get_tests(from = "2023-08-01", to = "2023-08-10") # Include inactive tests dfAll <- get_tests(from = "2023-08-01", includeInactive = TRUE) ## End(Not run)
Get the test type names and ids for all the test types in the system.
get_testTypes()get_testTypes()
Response will be a data frame containing the tests that are in the HD system. Each test type includes the following variables:
| Column Name | Type | Description |
| canonicalId | chr | test's unique canonical ID |
| name | chr | test's given name |
| abbreviation | chr | test given name abbreviation |
## Not run: # This is an example of how the function would be called. df_tests <- get_testTypes() ## End(Not run)## Not run: # This is an example of how the function would be called. df_tests <- get_testTypes() ## End(Not run)
Manages the API session state, including the access token lifecycle and regional endpoints.
HawkinAuth( config = HawkinConfig(), access_token = NULL, expires_at = NULL, region = "Americas" )HawkinAuth( config = HawkinConfig(), access_token = NULL, expires_at = NULL, region = "Americas" )
config |
HawkinConfig. The configuration settings. |
access_token |
character. The ephemeral Bearer token. |
expires_at |
POSIXct. The timestamp when the access token expires. |
region |
character. The data region ("Americas", "Europe", "APAC"). |
An S7 object of class HawkinAuth representing the API session
state, including its config, access_token, expires_at,
region, and the computed read-only base_url.
base_url: The computed API base URL for the region (read-only).
Stores environment and profile configuration settings.
HawkinConfig( profile = "default", org_id = "v1", environment = "development", log_level = "INFO" )HawkinConfig( profile = "default", org_id = "v1", environment = "development", log_level = "INFO" )
profile |
character. The profile name used for credential lookup (default: "default"). |
org_id |
character. The organization ID for API paths (default: "v1"). |
environment |
character. "development" (keyring) or "production" (env vars). |
log_level |
character. Logging verbosity ("INFO", "DEBUG", "WARN"). |
An S7 object of class HawkinConfig storing environment and
profile configuration settings (profile, org_id,
environment, and log_level).
Deletes a stored Refresh Token from the system keychain.
hd_auth_reset(profile = "default")hd_auth_reset(profile = "default")
profile |
character. The name of the profile to remove. |
No return value, called for side effects. Deletes the stored refresh
token for profile from the operating system credential store.
Securely saves your Hawkin Dynamics Refresh Token to your operating system's credential store (Keychain on macOS, Credential Manager on Windows).
hd_auth_store(profile = "default", token = NULL)hd_auth_store(profile = "default", token = NULL)
profile |
character. A name for this set of credentials (default: "default"). |
token |
character. Optional. If NULL (default), a secure prompt will appear. |
No return value, called for side effects. Stores the refresh token
for profile in the operating system credential store.
When using the token parameter directly (e.g., hd_auth_store(token = "...")),
be aware that the token string may be recorded in your .Rhistory file.
For maximum security, omit the token parameter to use the secure OS prompt instead.
Initializes a connection to the Hawkin Dynamics Cloud. This function creates the session object, performs the initial authentication, and sets it as the active connection for subsequent data calls.
hd_connect( profile = "default", org_id = "v1", environment = "development", region = "Americas", log_level = "INFO" )hd_connect( profile = "default", org_id = "v1", environment = "development", region = "Americas", log_level = "INFO" )
profile |
character. The name of the stored profile credential to use (default: "default"). |
org_id |
character. Your Organization ID. Defaults to "v1" for standard users. |
environment |
character. "development" to use local keychain, or "production" to use Environment Variables. |
region |
character. The API region: "Americas" (default), "Europe", or "APAC". |
log_level |
character. Logging verbosity: "INFO", "DEBUG", or "WARN". |
Invisibly returns the authenticated HawkinAuth object.
This function initializes the logger with customization parameters, including the output destination and log thresholds for both stdout and log file.
initialize_logger( log_output = "stdout", log_threshold_stdout = "INFO", log_file = "hawkinRlog.log", log_threshold_file = "INFO" )initialize_logger( log_output = "stdout", log_threshold_stdout = "INFO", log_file = "hawkinRlog.log", log_threshold_file = "INFO" )
log_output |
A character string specifying the log output destination. Options are "stdout", "file", or "both". Default is "stdout". |
log_threshold_stdout |
A character string specifying the log threshold for stdout. Options are "TRACE", "DEBUG", "INFO", "WARN", "ERROR", "FATAL". Default is "INFO". |
log_file |
A character string specifying the name of the custom log file. |
log_threshold_file |
A character string specifying the log threshold for the log file. Options are "TRACE", "DEBUG", "INFO", "WARN", "ERROR", "FATAL". Default is "INFO". |
The function sets up the logging configuration with the specified output destination
and log thresholds. If "stdout" is chosen, logs will be output to the console.
If "file" is chosen, logs will be written to a file named "hawkinRlog.log" by default.
The log_file parameter can be used to use a different file name and location.
If "both" is chosen, logs will be output to both the console and the log file.
Users can specify different log thresholds for stdout and log file.
No return value, called for side effects. Configures the logger
package's layout, threshold, and appender according to the arguments.
## Not run: # Log messages as stdout with a DEBUG threshold initialize_logger(log_output = "stdout", log_threshold_stdout = "DEBUG") # Log to file in 'app' directory with a TRACE threshold initialize_logger( log_output = "file", log_file = "app/mylog", log_threshold_file = "TRACE" ) ## End(Not run)## Not run: # Log messages as stdout with a DEBUG threshold initialize_logger(log_output = "stdout", log_threshold_stdout = "DEBUG") # Log to file in 'app' directory with a TRACE threshold initialize_logger( log_output = "file", log_file = "app/mylog", log_threshold_file = "TRACE" ) ## End(Not run)
This data frame contains metrics from all tests.
MetricDictionaryMetricDictionary
A data frame with 484 rows and 7 variables:
The unique id of the canonical test type (character).
The given / common name of the test type (character).
PascalCase formatted name of the metric (character).
The metric label found in app and cloud UI (character).
The metric name returned from the API (character).
header of data frame output (character).
Metric unit of measure (character).
A verbose description of the metric (character).
Generated for demonstration purposes.
Update an athlete or athletes for an account. Bulk update up to 500 athletes at a time.
update_athletes(athleteData, ...)update_athletes(athleteData, ...)
athleteData |
Provide a data frame of the athlete or athletes to be updated. |
... |
Optional arguments.
|
The data frame passed as the argument must use the following schema:
| Column Name | Type | Inclusion | Description |
| id | chr | REQUIRED | athlete's Hawkin Dynamics unique ID |
| name | chr | optional | athlete's given name (First Last) |
| image | chr | optional | URL path to image. default = null |
| active | logi | optional | athlete is active (TRUE). default = null |
| teams | list | optional | a single team id as a string or list of team ids. default = [defaultTeamId] |
| groups | list | optional | a single group id as a string or list of group ids. default = [] |
| external property | chr | optional | External properties can be added by adding any additional columns of equal length. The name of the column will become the external property name, and the row value will become the external property value. Use "lowercase" or "snake_case" styles for column names. |
If optional fields are not present in an update request, those properties will be left unchanged. However, when updating external properties, custom properties that are not present will be removed.
If successful, a confirmation message will be printed with the number of successful athletes updated. If there are failures, a data frame containing the athletes that failed to be updated will be returned with columns:
| Column Name | Type | Description |
| reason | chr | Reason for failed update |
| name | chr | Athlete's given name (First Last) |
## Not run: # Example data frame following the required schema df <- data.frame( id = c("uniqueAthleteIdOne", "uniqueAthleteIdTwo"), name = c("John Doe", "Jane Smith"), image = c("https://example.com/johndoe.jpg", "https://example.com/janesmith.jpg"), active = c(TRUE, FALSE), teams = I(list("team1", c("team2", "team3"))), groups = I(list(NULL, "group1")), external_property = c("value1", "value2") ) # Update athletes using the example data frame update_athletes(athleteData = df) ## End(Not run)## Not run: # Example data frame following the required schema df <- data.frame( id = c("uniqueAthleteIdOne", "uniqueAthleteIdTwo"), name = c("John Doe", "Jane Smith"), image = c("https://example.com/johndoe.jpg", "https://example.com/janesmith.jpg"), active = c(TRUE, FALSE), teams = I(list("team1", c("team2", "team3"))), groups = I(list(NULL, "group1")), external_property = c("value1", "value2") ) # Update athletes using the example data frame update_athletes(athleteData = df) ## End(Not run)