GymAware Cloud API integration guide
The GymAware API is included free with the GymAware Premium Cloud annual license.
What's Included:
- Refresh Token
- Staff
- Squad
- Athlete Information
- Summary of GymAware Data
- Rep Stats of GymAware Data
- Analysis Types
- Personal Best of GymAware Data
- Exercise Descriptions
- New*: Activities
- Testing the API
This guide is aimed at developers of athlete monitoring systems that wish to make use of the data from GymAware RS.
The GymAware RS 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 RS
- 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 GA RS 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 (only allowed for Owners and Admins)
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 , Create One here.
- Log into the cloud account from an iPad and collect some sets. Download the GymAware App
- Review the sets from the GymAware Cloud. Login here.
- Setup an Account Token and note the Account ID API Page (on the Cloud > Settings > Tokens)
- Enter the Account ID and Account Token into the partner application
Setting Up your Tokens
In order to access the GymAware Cloud API via an external application, you first need the Account ID and an API Token.
Log into your cloud account. Go to Settings > Tokens
If you already have an api key they will be listed under the section "API Tokens".
To generate a new token, click "Create Token" and enter a description of what you will use it for and click save to submit the token.
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://cloud.gymaware.com/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://cloud.gymaware.com/api/staff
Get
Get Query Parameters
None
Get Object Keys
staffReference: string: A unique identifier of this athlete
Squad
https://cloud.gymaware.com/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://cloud.gymaware.com/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://cloud.gymaware.com/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)
- 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)
- modifiedSince: float: optional, is required to be within the last 7 days. This option should be used to see ongoing changes and be sent the time of the last time the endpoint was called. Note: This will only return sessions recorded in the last 180 days even if they have been modified recently.
start/end need to be within 60 days of each other. this is intended to be used to review a historic period and should not be called repeatedly on the current period.
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 where marked up in 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 athletes body mass (W/kg).
- peakWattsPerKg: float: The peak power of the best rep divided by the athletes body mass (W/kg).
- velocityZone: string: The velocity zone category.
- activityName: string: The name of the exercise / activity as set by your account
- activityReference: string: A unique identifier for this activity
targets
- analysis: string: Analysis parameter used by target.
- mode: string: Was the set measured against a personal target, a squad target, the athletes last set or the athletes 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://cloud.gymaware.com/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)
- 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)
- modifiedSince: float: optional, is required to be within the last 7 days. This option should be used to see ongoing changes and be sent the time of the last time the endpoint was called. Note: This will only return sessions recorded in the last 180 days even if they have been modified recently.
start/end need to be within 60 days of each other. this is intended to be used to review a historic period and should not be called repeatedly on the current period.
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.
- activityName: string: The name of the exercise / activity as set by your account
-
activityReference: string: A unique identifier for this activity
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://cloud.gymaware.com/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://cloud.gymaware.com/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://cloud.gymaware.com/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.
New*: Activities
Get
Get Query Parameters
- None
- reference: string: A unique identifier for this activity
- name: string: The name of the exercise / activity as set by your account
- description: string: A full description
- category: string: The category that this activitity was assigned to. One of (Jump, Olympic, Upper Body Horizontal Push, Upper Body Horizontal Pull, Upper Body Vertical Push, Upper Body Vertical Pull, Lower Body Push, Lower Body Pull)
- modified: float: a unix timestamp indicating the last time this activity was changed
- vbt: boolean: A flag indicating whether this activity is a VBT Exercise (true), or a custom activity (false)
Logout
https://cloud.gymaware.com/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://cloud.gymaware.com/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://cloud.gymaware.com/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.
Comments
0 comments
Please sign in to leave a comment.