### Retrieving Venue Configurations

Source: https://context7.com/sbgsports/catapultr/llms.txt

Shows how to fetch venue configurations, including field dimensions and coordinates. Includes examples for getting all venues and specific venue details using `ofCloudGetVenues` and `ofCloudGetVenue`.

```r
# Get all venues
venues <- ofCloudGetVenues(token)
print(venues[, c("id", "name", "centre_latitude", "centre_longitude")])

# Get specific venue details
venue <- ofCloudGetVenue(token, venues$id[1])
print(venue)
```

--------------------------------

### Install catapultR Package (Other Platforms)

Source: https://github.com/sbgsports/catapultr/blob/main/README.md

Installs the catapultR package from GitHub source on non-Windows platforms. It first checks for and installs the 'devtools' package if not already present, then installs catapultR with vignettes.

```r
if (!require("devtools")) install.packages("devtools")
devtools::install_github("SBGSports/catapultr", dependencies=TRUE, build_vignettes=TRUE)
```

--------------------------------

### Install catapultR Package (Windows)

Source: https://github.com/sbgsports/catapultr/blob/main/README.md

Installs the catapultR package and its dependencies on Windows systems. It first ensures necessary R packages are installed and then installs catapultR from a GitHub binary.

```r
imports <- c('dplyr', 'httr', 'jsonlite', 'xml2', 'purrr', 'readr', 'signal', 'stringr', 'tibble', 'tidyr', 'magrittr', 'R6', 'crul') 
install.packages(imports[!(imports %in% installed.packages()[,"Package"])], dependencies = TRUE)
utils::install.packages("https://github.com/SBGSports/catapultr/raw/main/catapultR.zip")
```

--------------------------------

### Retrieving Velocity and Acceleration Band Configurations

Source: https://context7.com/sbgsports/catapultr/llms.txt

Shows how to fetch velocity and acceleration band configurations for an athlete. Includes examples for getting all band types and specific band details, distinguishing current bands from historical ones. Uses `ofCloudGetBands` and `ofCloudGetBand`.

```r
# Get all band types for an athlete
bands <- ofCloudGetBands(token, athlete_id)
print(bands)

# Get specific band details with history
velocity_bands <- ofCloudGetBand(token, athlete_id, "Velocity2")
# Rows with end_time == 0 are current bands
current_bands <- velocity_bands[velocity_bands$end_time == 0, ]
print(current_bands)

accel_bands <- ofCloudGetBand(token, athlete_id, "Gen2Acceleration")
```

--------------------------------

### Retrieving Allocated Modules

Source: https://context7.com/sbgsports/catapultr/llms.txt

Demonstrates how to fetch a list of modules allocated to the account, which controls available features. Uses the `ofCloudGetModules` function and provides examples of module names.

```r
modules <- ofCloudGetModules(token)
print(modules)
# Example: "HighFrequencyData", "Gen2VelocityBands.Released", "apiScope:catapultR"
```

--------------------------------

### GET /sensor-data

Source: https://context7.com/sbgsports/catapultr/llms.txt

Retrieves 10Hz sensor data for athletes.

```APIDOC
## GET /sensor-data

### Description
Retrieves high-frequency (10Hz) sensor data including GPS, LPS, and IMA metrics.

### Method
GET

### Endpoint
ofCloudGetActivitySensorData(token, athlete_id, activity_id, ...)

### Parameters
#### Query Parameters
- **athlete_id** (string) - Required - The athlete identifier.
- **activity_id** (string) - Required - The activity identifier.
- **stream_type** (string) - Optional - 'gps' or 'lps'.
- **parameters** (array) - Optional - List of metrics (e.g., 'lat', 'long', 'v', 'a').

### Response
#### Success Response (200)
- **data** (dataframe) - 10Hz sensor stream data.
- **stream_type** (string) - The type of stream returned.

### Response Example
{
  "stream_type": "gps",
  "data": [{"ts": 1672567200, "lat": -37.8, "long": 144.9}]
}
```

--------------------------------

### Retrieving Activity Annotations

Source: https://context7.com/sbgsports/catapultr/llms.txt

Explains how to fetch annotations (tags, comments) for activities, periods, and athletes. Includes examples for retrieving specific annotation details and categories. Uses `ofCloudGetActivityAnnotations`, `ofCloudGetPeriodAnnotations`, `ofCloudGetAthleteAnnotations`, and `ofCloudGetAnnotationCategories`.

```r
# Get activity annotations
activity_annotations <- ofCloudGetActivityAnnotations(token, activity_id)
print(activity_annotations[, c("id", "name", "comment", "category_id")])

# Get period annotations
period_annotations <- ofCloudGetPeriodAnnotations(token, period_id)

# Get athlete annotations
athlete_annotations <- ofCloudGetAthleteAnnotations(token, athlete_id)

# Get specific annotation details
annotation_details <- ofCloudGetAthleteAnnotations(token, athlete_id, annotation_id = 123)

# Get annotation categories
categories <- ofCloudGetAnnotationCategories(token)
print(categories[, c("id", "name")])
```

--------------------------------

### Access catapultR Vignettes, Help, and Version

Source: https://github.com/sbgsports/catapultr/blob/main/README.md

Provides R code to access the package vignettes, display help documentation, and check the installed version of the catapultR package.

```r
browseVignettes("catapultR")
help(package="catapultR")
packageVersion("catapultR")
```

--------------------------------

### GET /ofCloudGetAthleteDevicesInActivity

Source: https://context7.com/sbgsports/catapultr/llms.txt

Retrieves the list of athlete-device mappings associated with a specific activity ID.

```APIDOC
## GET /ofCloudGetAthleteDevicesInActivity

### Description
Fetches all athlete-device mappings for a given activity to identify which athletes participated and which devices were used.

### Method
GET

### Endpoint
/ofCloudGetAthleteDevicesInActivity

### Parameters
#### Query Parameters
- **token** (string) - Required - Authentication token
- **activity_id** (string) - Required - Unique identifier for the activity

### Request Example
GET /ofCloudGetAthleteDevicesInActivity?token=abc123&activity_id=act_001

### Response
#### Success Response (200)
- **athletes** (array) - List of athlete objects containing athlete_id and device_id

#### Response Example
{
  "athletes": [
    {"athlete_id": "ath_1", "device_id": "dev_001"}
  ]
}
```

--------------------------------

### Retrieving Aggregated Statistics

Source: https://context7.com/sbgsports/catapultr/llms.txt

Explains how to get aggregated statistics for activities with options for grouping and filtering. Supports multiple filters and querying annotation statistics. Uses the `ofCloudGetStatistics` function.

```r
# Get statistics grouped by athlete for an activity
parameters <- c("total_player_load", "total_distance", "total_duration")
grouping <- c("athlete", "activity")
filter1 <- list(
  name = "activity_id",
  comparison = "=",
  values = c(activity_id)
)

stats <- ofCloudGetStatistics(
  token,
  params = parameters,
  groupby = grouping,
  filters = filter1
)
print(stats)

# Multiple filters
filter2 <- list(
  name = "athlete_id",
  comparison = "=",
  values = c(athlete_id)
)
stats <- ofCloudGetStatistics(
  token,
  params = c("total_player_load", "max_velocity"),
  groupby = c("athlete", "activity", "period"),
  filters = c(filter1, filter2)
)

# Query annotation statistics
stats <- ofCloudGetStatistics(
  token,
  params = parameters,
  groupby = c("athlete", "annotation_category", "annotation"),
  filters = filter1,
  annotationStats = TRUE
)
```

--------------------------------

### GET /activities/{activity_id}/periods

Source: https://context7.com/sbgsports/catapultr/llms.txt

Retrieves the list of periods associated with a specific activity.

```APIDOC
## GET /activities/{activity_id}/periods

### Description
Retrieves all periods defined within a specific activity.

### Method
GET

### Endpoint
ofCloudGetPeriods(token, activity_id)

### Parameters
#### Path Parameters
- **activity_id** (string) - Required - The unique identifier for the activity.

### Response
#### Success Response (200)
- **id** (string) - Period ID
- **name** (string) - Period name
- **start_time** (datetime) - Start timestamp
- **end_time** (datetime) - End timestamp

### Response Example
{
  "id": "p123",
  "name": "First Half",
  "start_time": "2023-01-01T10:00:00Z",
  "end_time": "2023-01-01T10:45:00Z"
}
```

--------------------------------

### GET /athletes

Source: https://context7.com/sbgsports/catapultr/llms.txt

Retrieves athlete information from the OpenField account.

```APIDOC
## GET /athletes

### Description
Retrieves a list of all athletes associated with the account or filtered by activity.

### Method
GET

### Endpoint
ofCloudGetAthletes(token) or ofCloudGetAthletesInActivity(token, activity_id)

### Parameters
#### Query Parameters
- **activity_id** (string) - Optional - Filter athletes by specific activity.

### Response
#### Success Response (200)
- **id** (string) - Athlete ID
- **first_name** (string) - First name
- **last_name** (string) - Last name
- **jersey** (string) - Jersey number

### Response Example
[
  {"id": "a1", "first_name": "John", "last_name": "Doe", "jersey": "10"}
]
```

--------------------------------

### GET /ofCloudGetActivitySensorData

Source: https://context7.com/sbgsports/catapultr/llms.txt

Retrieves high-frequency (10 Hz) sensor data for a specific athlete within an activity.

```APIDOC
## GET /ofCloudGetActivitySensorData

### Description
Retrieves detailed sensor metrics including velocity, player load, and heart rate for a specific athlete during an activity.

### Method
GET

### Endpoint
/ofCloudGetActivitySensorData

### Parameters
#### Query Parameters
- **token** (string) - Required - Authentication token
- **athlete_id** (string) - Required - The ID of the athlete
- **activity_id** (string) - Required - The ID of the activity
- **parameters** (array) - Required - List of metrics to fetch (e.g., ts, cs, v, a, pl, hr)

### Request Example
GET /ofCloudGetActivitySensorData?token=abc123&athlete_id=ath_1&activity_id=act_001&parameters=v,pl,hr

### Response
#### Success Response (200)
- **data** (object) - Contains time-series sensor data for the requested parameters

#### Response Example
{
  "data": {
    "ts": [0, 0.1, 0.2],
    "v": [0, 2.5, 3.1],
    "pl": [0, 0.01, 0.02],
    "hr": [60, 65, 70]
  }
}
```

--------------------------------

### Retrieving User Settings

Source: https://context7.com/sbgsports/catapultr/llms.txt

Demonstrates how to fetch user-specific settings, such as unit preferences for velocity and distance. Uses the `ofCloudGetUserSettings` function.

```r
settings <- ofCloudGetUserSettings(token)
print(settings)  # Shows velocity_unit, distance_unit, etc.
```

--------------------------------

### Retrieving Activity Efforts (Velocity and Acceleration)

Source: https://context7.com/sbgsports/catapultr/llms.txt

Shows how to fetch generation 2 velocity and acceleration efforts for an athlete's activity. Requires checking module availability and specifies parameters like velocity/acceleration bands, stream type, and time range. Uses `ofCloudGetActivityEfforts` and `ofCloudGetPeriodEfforts`.

```r
# Check if effort modules are available
modules <- ofCloudGetModules(token)
print(modules)
# Requires "Gen2VelocityBands.Released" or "Gen2AccelerationBands.Released"

# Get velocity efforts
velocity_efforts <- ofCloudGetActivityEfforts(
  token, athlete_id, activity_id,
  velocityOrAcceleration = TRUE,  # TRUE = velocity, FALSE = acceleration
  bands = c(5, 6, 7, 8),          # Velocity bands 1-8
  stream_type = "gps",            # "gps" or "lps"
  from = NA, to = NA
)

print(velocity_efforts[, c("start_time", "end_time", "distance", "max_velocity")])

# Get acceleration/deceleration efforts
accel_efforts <- ofCloudGetActivityEfforts(
  token, athlete_id, activity_id,
  velocityOrAcceleration = FALSE,
  bands = c(-3, -2, -1, 1, 2, 3)  # Decel: -3,-2,-1; Accel: 1,2,3
)

# Get efforts for a period
period_efforts <- ofCloudGetPeriodEfforts(
  token, athlete_id, period_id,
  velocityOrAcceleration = TRUE,
  bands = NA  # All bands
)
```

--------------------------------

### Retrieving Available Statistics Parameters

Source: https://context7.com/sbgsports/catapultr/llms.txt

Demonstrates how to retrieve a list of all available parameters that can be used for querying statistics. Uses the `ofCloudGetParameters` function and displays parameter ID, name, and units.

```r
# Get all available parameters
params <- ofCloudGetParameters(token)
print(params[, c("id", "name", "units")])
```

--------------------------------

### Retrieving Customer Information

Source: https://context7.com/sbgsports/catapultr/llms.txt

Shows how to retrieve customer or organization-level information. Uses the `ofCloudGetCustomerInfo` function.

```r
customer <- ofCloudGetCustomerInfo(token)
print(customer)
```

--------------------------------

### Accessing and Filtering Events

Source: https://context7.com/sbgsports/catapultr/llms.txt

Demonstrates how to access specific types of events (acceleration, impact) from a data object and filter events for a given period using `ofCloudGetPeriodEvents`. Requires authentication token, athlete ID, and period ID.

```r
accel_events <- events[["ima_acceleration"]]
impact_events <- events[["ima_impact"]]

print(accel_events[, c("start_time", "end_time", "peak_acceleration")])

period_events <- ofCloudGetPeriodEvents(
  token, athlete_id, period_id,
  events = c("ima_jump"),
  ima_acceleration_intensity_threshold = 2.5
)
```

--------------------------------

### Retrieving Team Information

Source: https://context7.com/sbgsports/catapultr/llms.txt

Demonstrates how to retrieve a list of teams associated with the account. Uses the `ofCloudGetTeams` function and displays team ID and name.

```r
teams <- ofCloudGetTeams(token)
print(teams[, c("id", "name")])
```

--------------------------------

### Process Activity Data with catapultR

Source: https://context7.com/sbgsports/catapultr/llms.txt

This R code snippet demonstrates how to iterate through a list of activities, retrieve athlete-device mappings, fetch 10 Hz sensor data for each athlete, and store the processed data. It includes error handling for API calls and combines data from multiple sources.

```R
activity_data <- list()
for (i in seq_len(nrow(activities))) {
  print(paste("Processing:", activities$name[i]))

  athletes <- ofCloudGetAthleteDevicesInActivity(token, activities$id[i])
  if (is.null(athletes)) next

  for (j in seq_len(nrow(athletes))) {
    safe_sensor <- purrr::safely(ofCloudGetActivitySensorData)
    result <- safe_sensor(
      token, athletes$athlete_id[j], activities$id[i],
      parameters = c("ts", "cs", "v", "a", "pl", "hr")
    )

    if (is.null(result$error) && !is.null(result$result)) {
      data <- result$result$data[[1]]
      data$athlete_id <- athletes$athlete_id[j]
      data$activity_name <- activities$name[i]
      activity_data[[length(activity_data) + 1]] <- data
    }
  }
}

all_data <- bind_rows(activity_data)
summary_stats <- all_data %>%
  group_by(athlete_id, activity_name) %>%
  summarise(
    max_velocity = max(v, na.rm = TRUE),
    total_player_load = max(pl, na.rm = TRUE),
    avg_heart_rate = mean(hr, na.rm = TRUE),
    .groups = "drop"
  )
print(summary_stats)
```

--------------------------------

### Export Data to Catapult Focus Format

Source: https://context7.com/sbgsports/catapultr/llms.txt

Converts activity, period, and event data into a JSON format compatible with Catapult Focus for video integration. It supports custom timeline colors and precision rounding.

```r
# Convert events to Focus format
focus_events <- eventsToFocus(dfEvents = df_events, event_name = "movement", player_name = "Player 1", col = "blue")

# Export to JSON
jsonlite::write_json(focus_events, "events_focus.json", pretty = TRUE)
```

--------------------------------

### Manage Athletes and Device Mappings

Source: https://context7.com/sbgsports/catapultr/llms.txt

Functions to retrieve athlete rosters and their associated device mappings for specific activities or periods. This allows for mapping sensor data to individual athletes.

```r
athletes <- ofCloudGetAthletes(token)
athletes_in_activity <- ofCloudGetAthletesInActivity(token, activity_id)
athlete_devices <- ofCloudGetAthleteDevicesInActivity(token, activity_id)
activity_dicts <- dplyr::bind_rows(athlete_devices$activity_dictionaries)
```

--------------------------------

### Retrieve Activities from OpenField Cloud

Source: https://context7.com/sbgsports/catapultr/llms.txt

Retrieves all activities associated with the OpenField account, with options to filter by time range and check synchronization status. It also supports parallel fetching for multiple time intervals.

```R
# Get all activities from the last 7 days
to <- as.integer(Sys.time())
from <- to - 7 * 24 * 60 * 60  # 7 days ago

activities <- ofCloudGetActivities(token, from = from, to = to)

# View activity details
print(activities[, c("id", "name", "start_time", "end_time", "venue_name")])

# Get activities with sync status (shows synced/unsynced file counts)
activities <- ofCloudGetActivities(token, from = from, to = to, syncStatus = TRUE)
print(activities[, c("name", "synced", "unsynced")])

# Parallel fetch for multiple time intervals
from_vec <- c(from, from + 3*24*60*60)
to_vec <- c(from + 3*24*60*60, to)
activities_list <- ofCloudGetActivitiesEx(token, from = from_vec, to = to_vec, syncStatus = FALSE)
# Returns list with entry for each interval
```

--------------------------------

### Retrieve Activity and Period Metadata

Source: https://context7.com/sbgsports/catapultr/llms.txt

Functions to fetch activity lists, specific activity details, and associated periods. These are essential for identifying the IDs required for subsequent data requests.

```r
activities <- ofCloudGetActivities(token, from = from, to = to)
activity_id <- activities$id[1]
periods <- ofCloudGetPeriods(token, activity_id)
activity_details <- ofCloudGetActivity(token, activity_id, syncStatus = TRUE)
```

--------------------------------

### Authenticate with OpenField Cloud using OAuth2.0

Source: https://context7.com/sbgsports/catapultr/llms.txt

Authenticates with OpenField Cloud using username/password credentials to obtain an ofCredentials R6 object. Supports regional endpoints and provides both standard and safe (error-returning) functions. Includes an option to auto-detect the region.

```R
library(catapultR)

# Standard authentication with region, credentials, and client info
token <- ofCloudGetToken(
  sRegion = "APAC",           # Region: "APAC", "EMEA", "America", "China"
  sName = "username",         # OpenField username
  sPwd = "password",          # OpenField password
  sStage = "main",            # Stage: "main" (production), "alpha", "beta"
  sClientID = "clientID",     # OAuth client ID
  sClientSecret = "clientSecret",  # OAuth client secret
  traceURL = FALSE            # Set TRUE to debug API calls
)

# Safe version that returns list with error/result instead of throwing
result <- safe_ofCloudGetToken("EMEA", "user", "pass", "main", "clientID", "secret")
if (!is.null(result$error)) {
  parsed <- ofCloudParseError(result$error)
  print(paste("Error:", parsed$status_code, parsed$message))
} else {
  token <- result$result
}

# Auto-detect region by trying all regions
result <- safe_ofCloudGetTokenEx("user", "pass", "main", "clientID", "secret")
token <- result$result
```

--------------------------------

### Create OpenField Cloud Credentials from API Token

Source: https://context7.com/sbgsports/catapultr/llms.txt

Creates an ofCredentials object from an existing API token string. This is useful when tokens are managed externally or stored securely. It supports specifying token expiration time and refresh tokens.

```R
# Create token from existing API token string
# Get token from OpenField Cloud > Settings > API Tokens
token <- ofCloudCreateToken(
  sToken = "your_api_token_string",
  sRegion = "EMEA",
  sStage = "main",
  tokenExpireTime = as.integer(Sys.time()) + 3600,  # POSIX time when token expires
  traceURL = FALSE,
  refresh_token = "optional_refresh_token"
)

# Using environment variable for token
token <- ofCloudCreateToken(
  sToken = Sys.getenv("OFToken"),
  sRegion = "EMEA",
  traceURL = TRUE
)

# Create token with explicit URL (for internal/AWS deployments)
token <- ofCloudCreateTokenWithURL(
  sToken = "token",
  explicitURL = "openfield.catapultsports.com",
  tokenExpireTime = 0,
  traceURL = FALSE,
  refresh_token = NULL,
  secure = TRUE  # Use HTTPS and Bearer auth
)
```

--------------------------------

### Retrieve IMA Events and Efforts

Source: https://context7.com/sbgsports/catapultr/llms.txt

Fetches Inertial Measurement Analysis (IMA) events such as accelerations, jumps, and impacts for specific athletes within an activity.

```r
all_events <- ima_events()
events <- ofCloudGetActivityEvents(token, athlete_id, activity_id, events = c("ima_acceleration", "ima_impact"))
```

--------------------------------

### Access 10Hz Sensor Data

Source: https://context7.com/sbgsports/catapultr/llms.txt

Retrieves high-frequency sensor data (GPS/LPS) for athletes. Supports filtering by time, stream type, specific parameters, and pagination for large datasets.

```r
sensor_data <- ofCloudGetActivitySensorData(token, athlete_id, activity_id, parameters = c("ts", "cs", "lat", "long", "v", "a", "hr", "pl"))
sensor_data_list <- ofCloudGetActivitySensorDataEx(token, athlete_ids, activity_id, parameters = c("ts", "cs", "v", "a", "pl"))
```

--------------------------------

### Retrieve Periods within an Activity from OpenField Cloud

Source: https://context7.com/sbgsports/catapultr/llms.txt

Retrieves all periods (time segments) within a specific activity. This function is essential for analyzing data within defined segments of an athlete's session.

```R
# Example usage for ofCloudGetPeriods would go here
# Assuming 'token' and an 'activity_id' are available:
# periods <- ofCloudGetPeriods(token, activity_id = "your_activity_id")
# print(periods)
```

--------------------------------

### Handle Mixed GPS and LPS Data

Source: https://context7.com/sbgsports/catapultr/llms.txt

Specialized function for activities where tracking systems switch between GPS and LPS across different periods. Returns a combined data stream.

```r
sensor_data <- ofCloudGetMixedPeriodsActivitySensorData(token, athlete_id, activity_id, parameters = c("ts", "cs", "lat", "long", "xy", "v"))
```

--------------------------------

### Handle API Errors

Source: https://context7.com/sbgsports/catapultr/llms.txt

Parses API error responses to extract status codes and messages. This is useful for debugging authentication issues or invalid API requests.

```r
result <- safe_ofCloudGetToken("APAC", "user", "wrong_password", "main", "id", "secret")
if (!is.null(result$error)) {
  parsed <- ofCloudParseError(result$error)
  print(paste("Status:", parsed$status_code))
}
```

--------------------------------

### Process High-Frequency CSV Data

Source: https://context7.com/sbgsports/catapultr/llms.txt

Functions for reading and writing 100Hz CSV files generated by OpenField. These functions automatically handle metadata extraction and allow for custom column type definitions.

```r
# Read 100 Hz CSV file with metadata
hiFreq <- read_CATcsv(ofDataFileCSV())

# Modify data and write back
hiFreq$data <- hiFreq$data %>% dplyr::filter(Velocity > 0)
write_CATcsv(hiFreq, "modified_data.csv")
```

--------------------------------

### Validate and Refresh OpenField Cloud Authentication Token

Source: https://context7.com/sbgsports/catapultr/llms.txt

Validates the provided authentication token and refreshes it if it has expired or is close to expiring. This ensures continued access to the OpenField Cloud API without manual re-authentication.

```R
# Validate token before making API calls
result <- safe_ofCloudValidateToken(token, minTimeToExpiry = 3)
if (!is.null(result$error)) {
  print("Token refresh failed, need to re-authenticate")
} else {
  token <- result$result  # Updated token with refreshed credentials
}

# Check token expiration time
expireTime <- token$getTokenExpireTime()
print(paste("Token expires at:", as.POSIXct(expireTime, origin = "1970-01-01")))
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.