API Integration

GymAware Cloud API integration guide

The GymAware API is included free with the GymAware Cloud Pro annual license.

This guide is aimed at developers of athlete monitoring systems that wish to make use of the data from GymAware Powertools.

The GymAware Powertool is a Linear Position Transducer used by Strength and Conditioning Coaches to measure the Power and Velocity of athletes while weight training.

The GymAware system is made up of several components.

• The Power Tool
• An Apple iPad
• The GymAware Cloud (optional)

The GymAware Cloud is multi user. We refer to users of the GymAware cloud as Staff (as opposed to athletes that generally do not need to log into the GymAware system directly). Generally, you would have one Staff account per coach you wish to have access to GymAware.

Staff of an active account with the GymAware Cloud can configure their iPads to log into the cloud and all data collected from the Powertools is then automatically loaded into the cloud account.

The Staff member can then choose to allow access to this data by configuring their API settings.

The Account ID is an identifier used to refer to whole account and is not tied to one Staff member. It is not the login of any of the staff that have access to the account.

Authorisation tokens are managed by the staff and only one token should be given to each application that is to access the GymAware data.

Overview

• Create a cloud account. If you do not have one use Trial Signup
• Log into the cloud account from an iPad and collect some sets. Download the GymAware App
• Review the sets from the GymAware Cloud. Login
• Setup an Account Token and note the Account ID API Page
• Enter the Account ID and Account Token into the partner application

Setting Up your Tokens

In order to access the Kinetic GymAware Cloud API via an external application, you first need the Account ID and an API Token.

Log into your cloud account. Go to the API section under settings.

If you already have an api key they will be listed under the section "API Tokens".

To generate a new token, enter a description of what you will use it for and click save to submit the page.

A new token will now be available in the box showing the current time and your current IP address.

API EndPoints

The GymAware Cloud API get endpoints all return a newline separated stream of json objects.

 

Refresh Token

https://gymaware.kinetic.com.au/api/refresh

Calling this endpoint will invalidate your existing access token and replace it with a new one.

All followup requests will need to use the token returned by this endpoint.

Post

Post Query Parameters

None

Post Result Object Keys

• accountID: The Account ID for future requests.
• token: The Access Token for future requests.

Staff

list the active staff accounts.
https://gymaware.kinetic.com.au/api/staff
Get
Get Query Parameters
None

Get Object Keys
  staffReference: string: A unique identifier of this athlete

Squad

https://gymaware.kinetic.com.au/api/squad

Get
lists the squads of the given staff member.
Get Query Parameters
  staffReference: The staff account reference as seen on the staff get api

Get Object Keys
  squadReference: string: A unique identifier of this athlete
  name: string: A text description of the squad.
  isActive: bool: If true squad will show on ipads
  athleteReferences: list: array of athleteReference as from the athlete get api

Post
Add a new squad to a staff profile.
Post Query Parameters
  name: string describing the squad.
  athleteReferences: array of athleteReference as from the athlete get api

Put
Update an existing squad.
Put Query Parameters
  squadReference: The squad reference as seen on the squad get api
  name: string describing the squad.
  isActive: 0 to hide a squad from the iPads. 1 to show.
  athleteReferences: array of athleteReference as from the athlete api

Delete
Remove a squad from gymaware (this will not delete athletes in the squad).

  squadReference: The squad reference as seen on the squad get api

 

Athlete Information

https://gymaware.kinetic.com.au/api/athletes

The athletes endpoint used to access the athletes configured in your gymaware account.

The athletes endpoint supports the get and post http method.

Get

Get Query Parameters

None (A raw request will fetch all athletes data).

Get Object Keys

• athleteReference: string: A unique identifier of this athlete
• displayName: string: Athletes name as seen in app (may be formed from firstName, LastName)
• firstName: string: Athletes given name
• lastName: string: Athletes family name
• jerseyNumber: string: If this athlete plays a team sport they may have a Player Number
• position: string: An athlete grouping on where they play (ie Linemen, Backs, Offensive, Defensive)
• sport: string: Some accounts have athletes who perform different sports (ie Hockey, Football)
• address: string: Where is the athlete based, usually just a city or club name.
• phone: string: Contact number for the athlete.
• born: string: ISO 8601 YYYY-MM-DD format birth date.
• photo: string: url of the user photo on our servers.
• modified: float: utc seconds since the epoch

Post

Post Query Parameters

The post method is used to send a new Athlete to GymAware

If the athlete is in conflict with GymAware the status code will be set to 409 and the Exception header will be set with the reason.

• firstName: string: Athletes given name
• lastName: string: Athletes family name
• jerseyNumber: string: If this athlete plays a team sport they may have a Player Number
• position: string: An athlete grouping on where they play (ie Linemen, Backs, Offensive, Defensive)
• sport: string: Some accounts have athletes who perform different sports (ie Hockey, Football)
• address: string: Where is the athlete based, usually just a city or club name.
• phone: string: Contact number for the athlete.
• born: string: ISO 8601 YYYY-MM-DD format birth date.

A successful post will echo back the new athlete to the client.

• athleteReference: string: A unique identifier of this athlete
• displayName: string: Athletes name as seen in app (may be formed from firstName, LastName)
• firstName: string: Athletes given name
• lastName: string: Athletes family name
• jerseyNumber: string: If this athlete plays a team sport they may have a Player Number
• position: string: An athlete grouping on where they play (ie Linemen, Backs, Offensive, Defensive)
• sport: string: Some accounts have athletes who perform different sports (ie Hockey, Football)
• address: string: Where is the athlete based, usually just a city or club name.
• phone: string: Contact number for the athlete.
• born: string: ISO 8601 YYYY-MM-DD format birth date.
• photo: string: url of the user photo on our servers.
• modified: float: utc seconds since the epoch

Delete

Delete Query Parameters

The delete method is used to remove an athlete from the system

If the athlete is not available or has already been remove a 404 can be returned.

athleteReference: string: A unique identifier of this athlete
permanent: integer: 0 will archive the athlete, 1 will immediately delete the athlete.

A successful delete will return a message confirming the action

action: 'Athlete Deleted' or 'Athlete Archived. It be removed after your accounts Data Retention period.'}

Summary of GymAware Data

https://gymaware.kinetic.com.au/api/summaries

The summaries endpoint used to access the GymAware sets uploaded to your cloud account from your powertools.

The summaries endpoint supports the get http method. It returns a stream of json objects.

Get

Get Query Parameters

• start: float: optional, (must include end with start) UTC seconds since the epoch. A time window of the 'recorded' time to download (max 1 month per request at 10,000 lines)
• end: float: optional, (must include start with end) UTC seconds since the epoch, A time window of the 'recorded' time to download (max 1 month per request at 10,000 lines)
• modifiedSince: float: optional, Alternative to start and end, fetch all results with a 'modified' time greater then modifiedSince.
• athleteReference: string: optional, A unique identifier of the athlete

Get Result Object Keys

• reference: string: A unique identifier of this GymAware set
• recorded: float: utc seconds since the epoch
• modified: float: utc seconds since the epoch
• athleteReference: string: A unique identifier of the athlete
• athleteName: string: Athletes name as seen in app (may be formed from firstName, LastName)
• athleteWeight: float: Athletes body mass in kg.
• exerciseName: string: The general name of the exercise (ie Deadlift)
• barWeight: float: The lift mass in kg.
• repCount: integer: How many reps were marked up in the set.
• notes : string: Free text field entered on the set.
• targets: object: Information on the targets the athlete was aiming for during the lift (see below).
• height: float: The height of the highest rep (Useful for jumps).
• dip: float: The height of the lowest dip (Useful in squats).
• meanVelocity: float: The mean velocity of the best rep (m/s).
• peakVelocity: float: The peak velocity of the peak rep (m/s).
• meanPower: float: The mean power of the best rep (W).
• peakPower: float: The peak power of the best rep (W).
• meanWattsPerKg: float: The mean power of the best rep divided by the athlete's body mass (W/kg).
• peakWattsPerKg: float: The peak power of the best rep divided by the athlete's body mass (W/kg).
• velocityZone: string: The velocity zone category.

• sensor: contains the sensor serial number in the f.1000 or g.1000 format (showing if it is flex or GymAware hardware).

• hardware: contains the hardware major version: 16 for LE, 20 for RS, 129 for flex.

targets

• analysis: string: Analysis parameter used by target.
• mode: string: Was the set measured against a personal target, a squad target, the athlete's last set or the athlete's personal best.
• preset: object: Target 'min' and 'max' at time of collection.
• squad: object: Target 'min' and 'max' at time of collection.
• last: object: Target 'min' and 'max' at time of collection.
• best: object: Target 'min' and 'max' at time of collection.

Rep Stats of GymAware Data

https://gymaware.kinetic.com.au/api/reps

Information on GymAware sets including details on individual reps.

Get

Get Query Parameters

• start: float: optional, (must include end with start) UTC seconds since the epoch. A time window of the 'recorded' time to download (max 1 month per request at 10,000 lines)
• end: float: optional, (must include start with end) UTC seconds since the epoch, A time window of the 'recorded' time to download (max 1 month per request at 10,000 lines)
• modifiedSince: float: optional, Alternative to start and end, fetch all results with a 'modified' time greater then modifiedSince.
• athleteReference: string: optional, A unique identifier of the athlete

Get Result Object Keys

• reference: string: A unique identifier of this GymAware set
• recorded: float: utc seconds since the epoch.
• modified: float: utc seconds since the epoch.
• athleteReference: string: A unique identifier of the athlete.
• athleteName: string: Athletes name as seen in app (may be formed from firstName, LastName).
• athleteWeight: float: Athletes body mass in kg.
• exerciseName: string: The general name of the exercise (ie Deadlift).
• exerciseReference: string: A unique identifier of the exercise type.
• barWeight: float: The lift mass in kg.
• repCount: integer: How many reps where marked up in the set.
• reps: list: An array of reps (matching repCount), With analysis of that rep.

• sensor: contains the sensor serial number in the f.1000 or g.1000 format (showing if it is flex or GymAware hardware).

• hardware: contains the hardware major version: 16 for LE, 20 for RS, 129 for flex.

reps

• REPNUM: integer: order of the reps within the set.
• Analysis Label: float: for each analysis type in the analysis endpoint there will be an additional value here

Analysis Types

https://gymaware.kinetic.com.au/api/analysis

Information on analysis types.

Get

Get Query Parameters

• None

Get Result Object Keys

• label: string: A unique identifier of this analysis type
• isPeak: bool: is the "best aggregate" of this type the highest value
• isMin: bool: is the "best aggregate" of this type the lowest value
• isMean: bool: is the "best aggregate" of this type the average value
• isConcentric: bool: this value is concerned with the concentric phase of the lift
• isEccentric: bool: this value is concerned with the eccentric phase of the lift

Personal Best of GymAware Data

https://gymaware.kinetic.com.au/api/bests

Personal best information per athlete, per exercise, per weight.

Get

Get Query Parameters

• start: float: optional, (must include end with start) utc seconds since the epoch, A time window of the 'recorded' time to download (max 3 months per request)
• end: float: optional, (must include start with end) utc seconds since the epoch, A time window of the 'recorded' time to download (max 3 months per request)

Get Result Object Keys

• athleteReference: string: A unique identifier of the athlete
• athleteName: string: Athletes name as seen in app (may be formed from firstName, LastName)
• exerciseName: string: The general name of the exercise (ie Deadlift)
• barWeight: float: The lift mass in kg.
• height: float: The height of the highest rep (Useful for jumps).
• dip: float: The height of the lowest dip (Useful in squats).
• meanVelocity: float: The mean velocity of the best rep (m/s).
• peakVelocity: float: The peak velocity of the peak rep (m/s).
• meanPower: float: The mean power of the best rep (W).
• peakPower: float: The peak power of the best rep (W).
• meanWattsPerKg: float: The mean power of the best rep divided by the athletes body mass (W/kg).
• peakWattsPerKg: float: The peak power of the best rep divided by the athletes body mass (W/kg).

Exercise Descriptions

https://gymaware.kinetic.com.au/api/exercises

Information on exercises performed during a set.

Get

Get Query Parameters

• None

Get Result Object Keys

• reference: string: A unique identifier of this Exercise
• modified: float: utc seconds since the epoch
• category: string: The general class of exercise
• name: string: The basic type of exercise.
• subname: string: A narrower form of the exercise.

Logout

https://gymaware.kinetic.com.au/api/logout

A convenience endpoint to unauthenticate your http basic session. Returns 401

Supports GET and POST with no arguments.

Testing the API

Browser

Go to the api endpoint you would like to access: https://gymaware.kinetic.com.au/api/athletes which will prompt you with a dialog asking for User Name and Password.

The User Name is your Account ID. The Password is one of your API Tokens.

Curl

To test calls to the api you can use the command line program curl.

curl -u ACCOUNT_ID https://gymaware.kinetic.com.au/api/athletes

You will be prompted for a password,

Enter host password for user 'ACCOUNT_ID':

Enter one of your account tokens as the password.

Example App

There is a simple example python app using the API available at https://bitbucket.org/KineticPerformance/gymawareapi.