Getting Started With hawkinR

Initializing Your Session

In hawkinR v2.0, we use a modernized connection system. Our API uses bearer token authentication, but the package now manages the exchange of your Integration Key (Refresh Token) for an ephemeral Access Token automatically in the background.

1. Secure Credential Storage

Instead of pasting your secret key into every script, use hd_auth_store(). This saves your key securely in your operating system’s keychain (like macOS Keychain or Windows Credential Manager). You only need to do this once per machine.

library(hawkinR)

# Run this once to save your key securely
hd_auth_store(token = "your_integration_key_here")

2. Connecting to the Cloud

Use hd_connect() to initialize your session. This function performs the initial handshake and sets up your organization settings.

Note: The org_id defaults to “v1” for most users

# Initialize the session using the 'default' profile stored above
hd_connect(region = "Americas")

#> hawkinR -> Successfully authenticated as 'default'

Making Your First Calls

If this is your first time accessing your data through the API, or know you have had changes in your organization since your last session, a good place to start is by calling in your organizational data such as players, teams, and groups. While this information isn’t required to call in your test data, it can allow you to be more specific in your queries and save server processing and loading time when calling in test data.

The package was built to allow you the ability to make requests as specific as you need, and in as few lines of code as possible. To execute this, you will need this organizational information to input the parameters needed for that specificity. Each of these calls can be done in 1 line of code and one function. Each function returns a data frame that can be stored in an R object and used as necessary.

In this example, I will store athlete information in an object called ‘roster’, team information in an object called ‘teams’, and group information in an object named ‘groups’.

Exploring Your Organization

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

Get Athletes:

Returns a data frame with variables of: id, name, active, teams, groups, and external. If an athlete has external fields assigned to them, the string will contain the external name and external ID separated by a colon. And multiple externals will be separated by a comma.

# store player info in object called roster. 'includeInactive' is default to FALSE. Set to TRUE if you want to include inactive athletes.
roster <- get_athletes(includeInactive = FALSE)

id	name	active	teams	groups	external
0kEjAzSLpBwUZc4Yp2Ov	Athlete One	TRUE	09u20ij0dj0	0j20j09jd9ud0j	AMS:dj0203j0dj,GPS:md029j3209j2
1E1zYBv0CKbrKnsKz1vj	Player Two	TRUE	09u20ij0dj0	0j20j09jd9ud0j,92d2098d02j0	AMS:oin208ju09,GPS:od093j32
1lXEZKkNuNwvMLXiqFRr	Person Three	TRUE	9308dj209dj		AMS:j029j0jd20j,GPS:0d28j098h3

Get Teams:

Returns a data frame with variables: id and name.

# store team info in an object called teams.
teams <- get_teams()

id	name
09u20ij0dj0	Team One
9308dj209dj	Team Two

Get Groups:

Returns a data frame with variables: id and name.

# store group info in an object called groups.
groups <- get_groups()

id	name
0j20j09jd9ud0j	Position Group
92d2098d02j0	Grad Year Group

Test Types

Lastly, there are 9 different test collection modes in our software. And thus, we have 9 different test type IDs. These test IDs are what will be passed to get_tests() via the typeId argument, NOT the test name. So it is a good idea to store the test types as an object as well. This also has a single function to execute, which returns a data frame with the test type name and ID.

# store test type IDs in an object called testIds
testIds <- get_testTypes()

name	id
Countermovement Jump	7nNduHeM5zETPjHxvm7s
Squat Jump	QEG7m7DhYsD6BrcQ8pic
Isometric Test	2uS5XD5kXmWgIZ5HhQ3A
Drop Jump	gyBETpRXpdr63Ab2E0V8
Free Run	5pRSUQVSJVnxijpPMck3
CMJ Rebound	pqgf2TPUOQOQs6r0HQWb
Multi Rebound	r4fhrkPdYlLxYQxEeM78
Weigh In	ubeWMPN1lJFbuQbAM97s
Drop Landing	rKgI4y3ItTAzUekTUpvR

Pulling Test Data

The core of the package is the get_tests() function. In v2.0, this single function replaces the multiple get_tests_* functions from previous versions. You can filter by date, athlete, team, or test type directly in one call.

# Example: Pull all CMJ tests from the last 30 days
cmj_tests <- get_tests(
  from = "2023-10-01", 
  typeId = "7nNduHeM5zETPjHxvm7s"
)

With these objects, you can access any of the IDs and information you would need for your test queries. For a deeper dive into filtering data, see the Get Tests vignette.