Using Hawkin R as a Researcher

From Manual Exports to One Line of Code: My hawkinR Workflow

HawkinR is an open-source R package that connects directly to the Hawkin API, letting researchers and practitioners query force-plate testing data straight into R as ready-to-use data frames without manual CSV exports.

In September 2023, I began a PhD at Leeds Beckett University in partnership with Hawkin. My project aims to standardize force-assessment data collection across four leagues, with every player and team tested several times each year. In the 2023-2024 season alone, more than 40 data-collection sessions were completed, many in remote locations across multiple teams. Initially, I exported each session summary from Hawkin Cloud and combined the files manually in a single database. The process worked, but it was slow, vulnerable to missed trials, and increasingly difficult to sustain as the project grew.

Why I turned to hawkinR

I had seen research colleagues use the hawkinR package to pull assessment data directly into reports for players, clubs and external stakeholders, but coding initially felt intimidating. Now, as I enter the fourth year of the project, I can retrieve the previous three years of data into a database in seconds, without needing to become a programmer first.

HawkinR connects testing and analysis directly, linking R to the Hawkin API. Rather than exporting each session manually, I can query the organization’s data from within a reproducible workflow and receive the results as data frames. For my project, this reduces human error, helps ensure no trial is missed, and keeps a player’s records connected even if they move clubs during the season. Real world data collection is messy, but the route from force plates to an analysis ready dataset does not have to be. A simple script rerun and my database is updated. HawkinR's profile-based authentication, regional endpoints and incremental sync keep the entire pipeline, from data collection to analysis-ready dataset inside one reproducible, auditable R workflow.

That makes the package particularly useful when you want to:

The package supports regional endpoints for the Americas, Europe, and Asia-Pacific, so the connection can match where an organization’s data is hosted. Because my research is UK-based, the examples below use the Europe endpoint. The same workflow can be adapted to another region without changing the underlying analysis.

How I use hawkinR

1. Install R and hawkinR

If you already use RStudio, you can install the released version of hawkinR directly from CRAN in your script:

install.packages("hawkinR")

Then load the package:

library(hawkinR)

HawkinR is also available through the public GitHub repository, though CRAN remains the simplest starting point for a reproducible research workflow.

2. Authenticate securely

One major change in the current version of hawkinR is its profile-based authentication.

Profile-based authentication also works well with team-scoped API tokens: these can be restricted to specific teams, so administrators can issue each practitioner a separate profile with access only to the data they need, stored locally on their own device or machine.

This also supports least-privilege access from a research ethics standpoint useful for supervisors managing multiple student projects, since it keeps datasets cleanly separated and limits access to what each project's ethical approval covers. An ethically sound process that guarantees data governance in organisations running multiple projects across different schools within a university or a large, multi-centre organisation.

Rather than placing your API credentials directly into your analysis script, you can securely store your Hawkin Integration Key using your operating system's credential store:

hd_auth_store()

Once your key has been stored, connect to your Hawkin account:

hd_connect(region = "Europe")

Users in other locations can change this to "Americas" or "APAC" to match their organisation’s data residency. hawkinR manages the access-token exchange and refresh process.

This separation between authentication and analysis is useful for reproducibility: your analysis script can contain the code needed to retrieve data without embedding a secret token.

3. Retrieve the organization’s data

Once connected, you can start querying Hawkin data. I begin with small, inspectable requests before scaling up to the full longitudinal dataset. This makes it easier to confirm that athlete identifiers, teams, dates, and test types match the intended research question

For example, retrieve your athlete roster:

roster <- get_athletes()

head(roster)

You can also retrieve teams and groups:

teams <- get_teams()

groups <- get_groups()

To retrieve test data, use get_tests():

tests <- get_tests(

from = "2026-01-01",

to = "2026-01-31"

)

head(tests)

This returns the tests within the specified date range as a data frame for analysis in the wider R ecosystem. I use a short date range first as a quality-control check, then expand or increment the query to build the three-year project database. That approach is far easier to audit than combining dozens of manual exports.

4. Filter the analysis

A major benefit of retrieving the data programmatically is that you can define exactly what you want to analyse.

For example, you might retrieve tests for a particular athlete:

athlete_tests <- get_tests(

athleteId = athlete_id,

from = "2026-01-01",

to = "2026-03-31"

)

From there, you can use familiar R tools to filter, summarize and visualize the resulting data.

For larger organizations, date ranges are particularly important. Instead of repeatedly requesting an entire historical database, I constrain queries using the from and to parameters. This supports a more efficient incremental workflow and makes each data pull easier to inspect.

For an even more efficient update, add sync = TRUE to get_tests(). This turns the from parameter into syncFrom, so the query returns only tests that have been created or edited since that date, rather than re-pulling data that has not changed.

5. Access force-time data

If your analysis goes beyond summary metrics, hawkinR can also retrieve force-time data for an individual test:

force_data <- get_forcetime(

testId = athlete_tests$id[1]

)

The force-time response can include left, right, and combined force data, alongside calculated velocity, displacement, and power at each time interval. It is also possible to pull all trials as waveform data from a single script, making force – time analysis outside of proprietary software exponentially faster and more accessible.

At this point, the workflow moves from convenient data access to new research questions I can answer. In seconds, I can go from a plain-language request to an inspectable force-time waveform, then refine the code for a repeatable analysis. Questions that once carried a prohibitive time cost become realistic to explore, provided the code, variables, and outputs are validated carefully.

What a good workflow looks like for my research

For me, a useful hawkinR workflow must be repeatable, targeted, reproducible and easy to check. It should reduce administration without adding friction for the practitioners and clubs who make the research possible. That means requesting only the data needed, documenting each step and keeping credentials separate from the analysis.

Rather than downloading an entire database every time you want to update an analysis, establish a workflow that retrieves the relevant period or synchronises new records. For example:

library(hawkinR)

hd_connect(region = "Europe")

tests <- get_tests(

from = "2026-09-01",

to = "2026-09-25"

)

# Explore the returned dataset

str(tests)

head(tests)

You can then pass tests into your existing R analysis pipeline—whether that involves dplyr for data manipulation, ggplot2 for visualization, or statistical modelling packages for research.

For the full three-year dataset, an incremental workflow is especially valuable: I can store the timestamp of the latest successful synchronization and use it as the starting point for the next data pull. This avoids repeatedly retrieving the entire history and gives me a clearer audit trail when new testing sessions are added.

The result is a workflow in which Hawkin testing becomes the start of the analysis rather than the end of data collection. For my PhD, that means less time managing files and more time checking data quality, investigating longitudinal change and sharing useful findings with coaches, clubs and researchers. The process also reduces avoidable administration for the practitioners who make the project possible.

If you'd rather not write the code yourself, I've already built and tested a script for this workflow. It pulls your CMJ trials for any date range and team(s)*, writes a clean summary CSV with a trial ID for cross-referencing, and produces an anonymized version alongside your full dataset, so you can share data with multi centre research programs without exposing athlete identities. It runs on your own machine with your own Hawkin Integration Key, so nothing leaves your hands but the file you choose to send.

* Maximum 10 teams per call.