Package {rCoros}

rCoros: Access COROS Training Hub Fitness Data in R

Description

rCoros provides a tidy interface to the COROS Training Hub API. Authenticate once with coros_login(), then pull activities, daily wellness metrics, HRV, structured workouts, and training schedules — all returned as tibbles ready for analysis with dplyr and ggplot2.

Typical workflow

library(rCoros)
library(dplyr)

# 1. Store credentials (once, in ~/.Renviron)
# COROS_EMAIL=you@example.com
# COROS_PASSWORD=secret

# 2. Authenticate
auth <- coros_login()

# 3. Pull data
acts    <- coros_activities(auth)
metrics <- coros_daily_metrics(auth)
hrv     <- coros_hrv(auth)
sched   <- coros_schedule(auth)
wkts    <- coros_workouts(auth)

# 4. Drill into an activity
detail <- coros_activity_detail(
  auth,
  activity_id = acts$activity_id[[1]],
  sport_type  = acts$sport_type[[1]]
)

API regions

COROS operates separate endpoints for US and EU accounts. Pass region = "eu" to coros_login() if your account was created in Europe.

Credentials

Never hard-code passwords in scripts. Set COROS_EMAIL and COROS_PASSWORD environment variables, ideally in ⁠~/.Renviron⁠.

Author(s)

Maintainer: Matt O'Reilly fermoymatt@gmail.com

Authors:

• Matt O'Reilly fermoymatt@gmail.com

See Also

Useful links:

• https://github.com/mattyoreilly/rCoros

• https://mattyoreilly.github.io/rCoros/

• Report bugs at https://github.com/mattyoreilly/rCoros/issues

List activities

Description

Returns a tidy tibble of activities recorded within a date range, one row per activity.

Usage

coros_activities(
  auth,
  start_day = format(Sys.Date() - 30, "%Y%m%d"),
  end_day = format(Sys.Date(), "%Y%m%d"),
  page = 1L,
  size = 30L,
  n_max = Inf
)

Arguments

Value

A tibble::tibble() with columns:

activity_id

Unique activity identifier (character).

name

Activity name or remark.

sport_type

Numeric sport type code.

sport_name

Human-readable sport name.

date

Date of activity (Date).

start_time

Start timestamp (POSIXct, UTC).

duration_s

Duration in seconds.

duration_min

Duration in minutes.

distance_m

Distance in metres.

distance_km

Distance in kilometres.

elevation_gain

Elevation gain in metres.

avg_hr

Average heart rate (bpm).

calories

Calories (kcal).

training_load

Training load score.

avg_power

Average power (watts).

device

Device name.

Examples

auth <- coros_login()

# All activities in the last 30 days
acts <- coros_activities(auth)

# Running and trail-running only
library(dplyr)
runs <- coros_activities(auth) |>
  filter(sport_type %in% c(100L, 102L))

Fetch detailed metrics for a single activity

Description

Returns a list of three tibbles — a one-row summary, per-lap splits, and time-in-zone heart rate data — for the given activity.

Usage

coros_activity_detail(auth, activity_id, sport_type)

Arguments

Value

A named list with three tibbles:

summary

One-row tibble with overall activity metrics.

laps

One row per lap with splits.

hr_zones

Heart-rate zone breakdown (seconds and percent).

Examples

auth <- coros_login()
acts <- coros_activities(auth)

# Detail for the most recent activity
detail <- coros_activity_detail(
  auth,
  activity_id = acts$activity_id[[1]],
  sport_type  = acts$sport_type[[1]]
)
detail$summary
detail$laps
detail$hr_zones

Fetch daily health and training metrics

Description

Returns a tidy tibble of per-day wellness metrics from the COROS ⁠/analyse/dayDetail/query⁠ endpoint, including HRV, resting heart rate, training load, VO2max, and stamina.

Usage

coros_daily_metrics(
  auth,
  start_day = format(Sys.Date() - 28, "%Y%m%d"),
  end_day = format(Sys.Date(), "%Y%m%d")
)

Arguments

Value

A tibble::tibble() sorted by date with columns:

date

Calendar date (Date).

hrv

Average overnight HRV (ms).

hrv_baseline

Personal HRV baseline (ms).

rhr

Resting heart rate (bpm).

training_load

Daily training load.

load_ratio

Training load ratio (acute:chronic).

tired_rate

Fatigue rate.

ati

Acute training impulse.

cti

Chronic training impulse.

t7d

7-day training load.

t28d

28-day training load.

vo2max

Estimated VO2max (mL/kg/min).

lthr

Lactate threshold heart rate (bpm).

ltsp

Lactate threshold speed.

stamina

Current stamina level.

stamina_7d

7-day stamina level.

performance

Performance score.

tib

Time in bed (minutes).

Examples

auth <- coros_login()

# Last 28 days (default)
metrics <- coros_daily_metrics(auth)

# Custom range
metrics <- coros_daily_metrics(auth, start_day = "20240101", end_day = "20240131")

Fetch recent HRV readings

Description

Retrieves the last ~7 days of overnight HRV data from the COROS dashboard endpoint.

Usage

coros_hrv(auth)

Arguments

Value

A tibble::tibble() sorted by date with columns:

date

Calendar date (Date).

hrv

Average overnight HRV (ms).

baseline

Personal HRV baseline (ms).

hrv_sd

Standard deviation of overnight HRV (ms).

See Also

coros_daily_metrics() for a longer historical HRV series.

Examples

auth <- coros_login()
coros_hrv(auth)

Authenticate with the COROS Training Hub API

Description

Logs in with an email/password pair and returns an auth object that must be passed to every other ⁠coros_*⁠ function. Credentials are read from environment variables by default so they are never hard-coded in scripts.

Usage

coros_login(
  email = Sys.getenv("COROS_EMAIL"),
  password = Sys.getenv("COROS_PASSWORD"),
  region = c("us", "eu")
)

Arguments

Details

Set credentials once per session with:

Sys.setenv(COROS_EMAIL = "you@example.com", COROS_PASSWORD = "secret")

or add them to your ⁠~/.Renviron⁠ file for persistence.

Value

A named list with fields access_token, user_id, base_url, region, and timestamp. Treat this object as opaque and pass it directly to other ⁠coros_*⁠ functions.

Examples

auth <- coros_login()  # reads COROS_EMAIL / COROS_PASSWORD from env

# EU region
auth_eu <- coros_login(region = "eu")

Fetch the training calendar

Description

Returns a tibble of planned activities from the COROS training schedule within the given date window.

Usage

coros_schedule(
  auth,
  start_day = format(Sys.Date(), "%Y%m%d"),
  end_day = format(Sys.Date() + 14, "%Y%m%d")
)

Arguments

Value

A tibble::tibble() with one row per scheduled item and columns:

plan_id

Training plan identifier.

id_in_plan

Item position within the plan.

plan_program_id

Associated workout program identifier.

happen_day

Scheduled date (Date).

name

Workout name.

sport_type

Numeric sport type code.

sport_name

Human-readable sport name.

estimated_min

Estimated duration in minutes.

completed

Logical; TRUE if the workout has been completed.

Examples

auth <- coros_login()

# Upcoming two weeks
schedule <- coros_schedule(auth)

# Narrower window
schedule <- coros_schedule(
  auth,
  start_day = format(Sys.Date(), "%Y%m%d"),
  end_day   = format(Sys.Date() + 7, "%Y%m%d")
)

List structured workout programs

Description

Retrieves all workout programs stored in the COROS Training Hub, returning a list of two tidy tibbles: a summary of each workout and its constituent steps.

Usage

coros_workouts(auth)

Arguments

Value

A named list with two tibbles:

workouts

One row per workout with columns id, name, sport_type, sport_name, duration_min, and n_steps.

steps

One row per step, linked to workouts via workout_id, with columns step_name, duration_s, duration_min, power_low_w, power_high_w, and sets.

Examples

auth <- coros_login()
result <- coros_workouts(auth)
result$workouts
result$steps