Catapult Connect API Usage Guide
User Manual:
Open the PDF directly: View PDF 
.
Page Count: 11
| Download | |
| Open PDF In Browser | View PDF |
Catapult Connect API
USAGE GUIDE
v1.0
Table of Contents
About Catapult Connect ........................................................................................................................... 3
Features ....................................................................................................................................................... 3
Technical Documentation ........................................................................................................................ 4
Authentication ............................................................................................................................. 4
Requesting an access token ..................................................................................................................... 4
Refreshing an access token...................................................................................................................... 5
Making data requests .............................................................................................................................. 5
Athletes ........................................................................................................................................ 6
Activities ....................................................................................................................................... 7
Parameters .................................................................................................................................. 8
Statistics ....................................................................................................................................... 9
Statistics for a specific activity ................................................................................................................. 9
Statistics per period for a specific activity .............................................................................................. 10
Usage Policy ............................................................................................................................................. 11
Catapult Connect API – Usage Guide – v1.0
About Catapult Connect
Catapult Connect exists to bring a brand-new level of accessibility to your athlete
performance data. Connect is a secure, cloud-hosted Application Programming Interface
(API) for querying metrics captured via wearable devices and analysed in OpenField
software. Only data synced to OpenField Cloud is accessible through Connect.
Features
Connect is designed to expose all of the information you’re used to seeing in OpenField
Cloud, and contains endpoints for
•
Athletes
Lists athletes and associated information recorded in your OpenField account
•
Activities
Lists activities and associated information recorded in your OpenField account
•
Parameters
List the parameters for which measures are captured within OpenField, including
Player Load, heart rate, banded velocity and acceleration metrics, amongst many
others
•
Statistics
Lists recorded metrics for a set of specified parameters and according to
supplied filters
Catapult Connect API – Usage Guide – v1.0
Technical Documentation
Connect is a REST API that returns JSON for all requests.
The Base URL for Connect differs according to the region your OpenField account has
been created in:
•
Asia-Pacific
OpenField URL: https://openfield.catapultsports.com
Connect Base URL: https://connect-au.catapultsports.com/api/v4
•
North America
OpenField URL: https://us.catapultsports.com/
Connect Base URL: https://connect-us.catapultsports.com/api/v4
•
Europe, the Middle East and Africa, Latin America
OpenField URL: https://eu.catapultsports.com/
Connect Base URL: https://connect-eu.catapultsports.com/api/v4
In the examples below, replace BASE_URL with the correct Base URL for your OpenField
region.
AUTHENTICATION
Access to Connect is controlled by oAuth2 authentication and requires a valid Client ID
and Secret (supplied by OpenField Support) in addition to active OpenField credentials.
In the examples below, replace CLIENT_ID and CLIENT_SECRET with the token provided
to you, and USERNAME and PASSWORD with your OpenField credentials.
Requesting an access token
When no token is present, send a GET request to /oauth/token. The following must be
provided:
•
Client ID/Client Secret, provided in the query string in the request
•
Using basic authentication, the username and password associated with this
account
Example Request:
curl –u "USERNAME:PASSWORD"
https://BASE_URL/oauth/token\?client_id\=CLIENT_ID\&client_secret\=CLIEN
T_SECRET
Catapult Connect API – Usage Guide – v1.0
Example Response:
{"access_token":"IbtBBvCu30xixwBxF5zpyL4wfrPuCm3jGCJToI95","token_type":
"Bearer","expires":1411352773,"expires_in":3600,"refresh_token":"Ef3yALA
EvmZhFIL8MuniOyBDDyCX72mmSHQd7lS7"}
Error Response (username/password incorrect):
401: Unauthorized
Error Response (any missing parameters):
401: Unauthorized
The access_token in the response should be used to make API subsequent Connect
requests, and should replace ACCESS_TOKEN in the examples below.
Refreshing an access token
Access tokens will by default expire after one hour (3600 seconds), after which all
requests will result in an error response of type 410: Gone. Once expired,
the refresh_token returned from the original authentication request can be used to
obtain a new access token without having to fully re-authenticate.
Example Request:
curl https://BASE_URL/oauth/refresh?client_id\=CLIENT_ID\&client_secret\
=CLIENT_SECRET\&refresh_token\=REFRESH_TOKEN
Example Response:
{"access_token":"4d4DrMnI8b0RXmVFYo8cxDxO4Jq434HGrOPUGBMZ","token_type":
"Bearer","expires":1411353506,"expires_in":3600}
Error Response (invalid refresh token):
401: Unauthorized
This request returns a new access token to use in future API requests.
Making data requests
All endpoints require the token to be provided in the request header. The access_token
from the above endpoints should be used to request data by adding an 'Authorization'
header with the value Bearer ACCESS_TOKEN.
Catapult Connect API – Usage Guide – v1.0
Example:
curl: --header "Authorization: Bearer
4d4DrMnI8b0RXmVFYo8cxDxO4Jq434HGrOPUGBMZ"
ATHLETES
A list of athletes/players for the account can be retrieved by accessing the /athletes
endpoint.
Example request:
curl https://BASE_URL/athletes --header "Authorization: Bearer
ACCESS_TOKEN"
Example response:
[
{
]
"id": "fff0377a-5b53-4fe8-8bc0-098cc3a0949e",
"first_name": "Scott",
"last_name": "Higginbotham",
"jersey": "R8",
"nickname": "",
"height": 0,
"weight": 0,
"date_of_birth": "0",
"velocity_max": "10",
"acceleration_max": "10",
"heart_rate_max": "220",
"player_load_max": "10",
"max_player_load_per_minute": 12,
"tag_list": [
"Wide Receiver",
"Rehab"
],
"tags": [
{
"id": "9b8baf9f-e4d4-41ce-93a7-635f130bfeb4",
"tag_type_id": "c7ff448a-6d16-4e27-9bce-a686cd908e82",
"tag_type_name": "Position",
"tag_name": "Wing"
}, {
"id": "0a3f1746-b64c-435b-a3d0-573f96e14879",
"tag_type_id": "d6c99680-0570-4435-8984-a4895b0c1a1c",
"tag_type_name": "Training Group",
"tag_name": "Rehab"
}
]
},
...
Catapult Connect API – Usage Guide – v1.0
The athlete id property listed in the example response can be used to filter requests for
data relating to a particular athlete.
ACTIVITIES
A list of activities can be retrieved from the /activities endpoint.
Example request:
curl https://BASE_URL/activities --header "Authorization: Bearer
ACCESS_TOKEN"
Example response:
[
{
"id": "803ac529-700c-4735-8e34-1ecf36ca8145",
"name": "SOO3 QLD v NSW",
"start_time": "1499854408",
"end_time": "1499860657",
"venue": {
"name": "Suncorp",
"width": 68,
"length": 117,
"rotation": 1,
"lat": "-37.830258052762",
"lng": "144.95438003888"
},
"periods": [
{
"id": "6122d61b-88cb-4729-9eb3-3b07fd2d98bd",
"name": "1",
"start_time": 1499854408.73,
"end_time": 1499857004.39
},
{
"id": "f98fd5a6-cb8b-4803-beb3-2d93c0fb1543",
"name": "2",
"start_time": 1499858086.21,
"end_time": 1499860657.34
}
]
"tag_list": [
"State of Origin 2018",
"Win"
],
"tags": [
{
"id": "9b8baf9f-e4d4-41ce-93a7-635f130bfeb4",
"tag_type_id": "c7ff448a-6d16-4e27-9bce-a686cd908e82",
"tag_type_name": "Activity",
"tag_name": "State of Origin 2018"
}, {
"id": "0a3f1746-b64c-435b-a3d0-573f96e14879",
"tag_type_id": "d6c99680-0570-4435-8984-a4895b0c1a1c",
Catapult Connect API – Usage Guide – v1.0
}
]
"tag_type_name": "Activity",
"tag_name": "Win"
]
},
..
The activity id property listed in the example response can be used to filter requests for
data relating to a particular activity.
The period id property for each element in the array of returned periods can be used to
filter requests for data relating to a particular period.
PARAMETERS
The /parameters endpoint provides a list of parameters (sports metrics) captured within
OpenField, including Player Load, heart rate, banded velocity and acceleration metrics,
amongst many others.
Example request:
curl https://BASE_URL/parameters --header "Authorization: Bearer
ACCESS_TOKEN"
Example response:
[
{
"id": "00025054-617c-45f1-ae03-a768ebfcd893",
"parameter_type_id": "417654ed-209f-4c6f-a028-62c10f873d18",
"name": "IMA Accel Medium",
"original_name": "IMA Accel Medium",
"slug": "ima_band2_accel_count",
"calculation": ""
},
{
"id": "003eb200-194c-4bce-8573-756f8df67adc",
"parameter_type_id": "65344b9a-8526-11e2-97f1-53b3868817d9",
"name": "Velocity Band 2 Average Effort Count",
"original_name": "Velocity Band 2 Average Effort Count",
"slug": "velocity_band2_average_effort_count",
"calculation": "",
},
...
{
"id": "0232570c-949d-4bf8-9719-9a29ee8761d3",
"parameter_type_id": "65344b9a-8526-11e2-97f1-53b3868817d9",
"name": "Velocity Band 1 Duration %",
"original_name": "Velocity Band 1 Duration %",
"slug": "velocity_band1_duration_percentage",
"calculation": ""
Catapult Connect API – Usage Guide – v1.0
]
}
STATISTICS
The /stats endpoint provides filtered and grouped performance metrics via a POST
request, with data supplied as a JSON object. The request takes three types of input
parameters:
•
Parameters
A list of one or more parameter (performance metrics) names from the list
supplied through the /parameters endpoint (e.g. average_player_load)
•
Filters
A list of filters to narrow down the query. Where multiple filters are supplied,
returned statistics will match ALL conditions. Each filter element must include a
parameter name, a comparison type (i.e. one of =, !=, >, <, <=, >=) and an array
of filter values, which is a list of ids for the particular type of filter.
•
Groupings
A discrete list of parameters to group the response by, one or more of:
o
o
o
o
o
o
o
o
o
o
o
o
o
o
o
activity
athlete_group
athlete
period
tag
position
team
date
day
week
month
year
swing (baseball only)
pitch (baseball only)
delivery (cricket only)
Statistics for a specific activity
To retrieve statistics for each athlete in a particular activity (using the id retrieved from
the /activities endpoint):
Example request:
Catapult Connect API – Usage Guide – v1.0
curl https://BASE_URL/stats -X POST --header "Authorization: Bearer
ACCESS_TOKEN" --data '{"filters": [{"name": "activity_id", "comparison":
"=", "values": ["803ac529-700c-4735-8e34-1ecf36ca8145"]}], "parameters":
["total_player_load", "total_duration"],"group_by": ["athlete"]}'
Example response:
[
{
]
"athlete_id": "884fed5b-432d-47d4-9f50-7cf7b4cbb5a3",
"athlete_name": "Jarryd Hayne",
"start_time": 1499854408.73,
"end_time": 1499860657.34,
"total_player_load": 704.58575,
"average_player_load": 352.29288,
"average_player_load_session": 704.58575,
"date": "12/07/2017",
"int_day_id": 1,
"start_time_h": "20:13:28",
"end_time_h": "21:57:37"
},
...
Note: additional fields will be returned certain circumstances. Grouping by a parameter
will result in the id and name to be returned for each value, i.e. activity_id and
activity_name will be included in the response when grouped by activity.
Statistics per period for a specific activity
By comparison to the previous example, in this case a result is returned for each period
in the selected activity. Properties period_id and period_name are now returned as a
result of grouping by period.
Example request:
curl https://BASE_URL/stats -X POST --header "Authorization: Bearer
ACCESS_TOKEN" --data '{"filters": [{"name": "activity_id", "comparison":
"=", "values": ["803ac529-700c-4735-8e34-1ecf36ca8145"]}], "parameters":
["total_player_load", "average_player_load",
"average_player_load_session"],"group_by": ["period", "athlete"]}
Example response:
[
{
"athlete_id": "884fed5b-432d-47d4-9f50-7cf7b4cbb5a3",
"athlete_name": "Jarryd Hayne",
"period_id": "f98fd5a6-cb8b-4803-beb3-2d93c0fb1543",
"period_name": 2,
"start_time": 1499858086.21,
"end_time": 1499860657.34,
Catapult Connect API – Usage Guide – v1.0
"total_player_load": 343.28204,
"average_player_load": 343.28204,
"average_player_load_session": 343.28204,
"date": "12/07/2017",
"periodname_id": 2,
"periodname_name": 2,
"int_day_id": 1,
"start_time_h": "21:14:46",
"end_time_h": "21:57:37"
},
...
]
Usage Policy
Catapult expects all consumers of the Connect API to follow a set of fair-usage guidelines
-- access may otherwise be revoked to ensure a good service for all.
Individual requests should not exceed a rate of more than one per 60s, and should be
made synchronously, not asynchronously.
Catapult Connect API – Usage Guide – v1.0
Source Exif Data:
File Type : PDF File Type Extension : pdf MIME Type : application/pdf Linearized : No Page Count : 11 PDF Version : 1.4 Title : OpenField Release Notes 1.18 Author : Daniel Prior Subject : Producer : Mac OS X 10.13.3 Quartz PDFContext Creator : Word Create Date : 2018:03:28 23:37:38Z Modify Date : 2018:03:28 23:37:38ZEXIF Metadata provided by EXIF.tools