Soccer
This page explains the data and metrics available for soccer, their format, and the JSON Schema parameters required (in the case of computed data).
For more information about the metrics and their formats, check out the References.
Computed data
Below are all metrics provided for soccer:
first_timestamp: First timestamp of the timeframe.last_timestamp: Last timestamp of the timeframe.total_distance: Total distance (in meters) traveled during the timeframe.average_speed: Average speed (in m/s) of the timeframe.max_speed: Maximum speed (in m/s) reached during the timeframe.distance_per_speed_ranges: Distance run by an athlete per range of speed.accelerations: Numbers and value of each accelerations above a threshold.decelerations: Numbers and value of each decelerations above a threshold.sprint: Number and value of a sprint above a threshold.hid: High intensity distance. Distance traveled by an athlete at a speed above a treshold.athlete_max_hr: Theoretical maximum heartrate of an athlete.hr_avg: Average heartrate of the atlete during the timeframe.hr_max: Maximum heartrate reached by the athlete during the timeframe.hr_min: Minimum heartrate reached by the athlete during the timeframe.hr_plot: History graph of the heartrate of the athlete.timePerHrZone: Time spent with heartrate if each defined heartrate zone.intensity_graph: Distance traveled per slice of X minute.
Example of computed-data retrieved by API
{
"accelerations": {
"threshold_2": {
"threshold": 3,
"values": [
{
"start_time": 1620647640000,
"max_value": 3.148,
"duration": 3.2,
"distance": 10.018,
"initial_speed": 0.282,
"end_speed": 4.897
},
{
"start_time": 1620647653500,
"max_value": 3.001,
"duration": 2.3,
"distance": 9.33,
"initial_speed": 1.462,
"end_speed": 4.763
}
{
"start_time": 1620647810200,
"max_value": 3.94,
"duration": 1.4,
"distance": 5.748,
"initial_speed": 1.046,
"end_speed": 4.303
}
]
},
"threshold_1": {
"threshold": 2,
"values": [
{
"start_time": 1620647750800,
"max_value": 2.615,
"duration": 1.9,
"distance": 4.464,
"initial_speed": 0.423,
"end_speed": 3.048
},
{
"start_time": 1620647753200,
"max_value": 2.585,
"duration": 1.5,
"distance": 6.144,
"initial_speed": 2.147,
"end_speed": 4.274
},
{
"start_time": 1620647806800,
"max_value": 2.176,
"duration": 1.8,
"distance": 3.869,
"initial_speed": 0.325,
"end_speed": 2.639
}
]
}
},
"athlete_max_hr": 189,
"average_speed": 0.9882,
"decelerations": {
"threshold_2": {
"threshold": 3,
"values": [
{
"start_time": 1620647997200,
"max_value": -3.605,
"duration": 2.7,
"distance": 6.633,
"initial_speed": 5.036,
"end_speed": 0.602
},
{
"start_time": 1617113240900,
"max_value": -4.414,
"duration": 1.9,
"distance": 5.28,
"initial_speed": 5.201,
"end_speed": 1.42
},
{
"start_time": 1617113353300,
"max_value": -3.025,
"duration": 3.1,
"distance": 8.25,
"initial_speed": 5.426,
"end_speed": 0.967
}
]
},
"threshold_1": {
"threshold": 2,
"values": [
{
"start_time": 1620647563100,
"max_value": -2.109,
"duration": 1.9,
"distance": 3.345,
"initial_speed": 3.38,
"end_speed": 1.093
},
{
"start_time": 1620647580800,
"max_value": -2.304,
"duration": 1.9,
"distance": 3.61,
"initial_speed": 3.618,
"end_speed": 1.286
},
{
"start_time": 1620647625500,
"max_value": -2.288,
"duration": 1.6,
"distance": 3.096,
"initial_speed": 3.47,
"end_speed": 1.35
}
]
}
},
"distance_per_speed_ranges": [
{
"distance": 3808.1449,
"ratio": 0.9356,
"threshold_low": 0,
"threshold_high": 4
},
{
"distance": 203.196,
"ratio": 0.0499,
"threshold_low": 4,
"threshold_high": 5
},
{
"distance": 58.7397,
"ratio": 0.0144,
"threshold_low": 5,
"threshold_high": 6
},
{
"distance": 0,
"ratio": 0,
"threshold_low": 6,
"threshold_high": []
}
],
"first_timestamp": 1620647416000,
"hid": {
"threshold_1": {
"threshold": 4,
"values": [
{
"start_time": 1620647640600,
"duration": 2.3,
"max_value": 4.9205,
"distance": 10.234429367452526
},
{
"start_time": 1620647654400,
"duration": 1.8,
"max_value": 4.825,
"distance": 7.764227285098559
},
{
"start_time": 1620647668400,
"duration": 2.8,
"max_value": 5.132300000000001,
"distance": 12.575696540185104
}
]
},
"threshold_2": {
"threshold": 5,
"values": [
{
"start_time": 1620647669100,
"duration": 0.9,
"max_value": 5.132300000000001,
"distance": 4.366224612946011
},
{
"start_time": 1620647994600,
"duration": 0.2,
"max_value": 5.0455000000000005,
"distance": 1.0167155193156558
},
{
"start_time": 1620647994900,
"duration": 0.4,
"max_value": 5.0509,
"distance": 1.9831344982124
}
]
}
},
"hr_avg": 0,
"hr_max": 0,
"hr_min": 0,
"last_timestamp": 1617116486900,
"max_speed": 5.8933,
"sprint": {
"threshold_1": {
"threshold": 5,
"values": [
{
"start_time": 1620647669100,
"duration": 0.9,
"max_value": 5.132300000000001,
"distance": 4.366224612946011
},
{
"start_time": 1620647994600,
"duration": 0.2,
"max_value": 5.0455000000000005,
"distance": 1.0167155193156558
},
{
"start_time": 1620647994900,
"duration": 0.4,
"max_value": 5.0509,
"distance": 1.9831344982124
},
{
"start_time": 1617113221100,
"duration": 1.1,
"max_value": 5.298100000000001,
"distance": 5.5218264995377
}
]
}
},
"timePerHrZone": [
{
"percentage_hrmax": 100,
"range_bpm": [
0,
160.65
],
"range_percent_hrmax": [
0,
85
]
},
{
"percentage_hrmax": 0,
"range_bpm": [
160.65,
189
],
"range_percent_hrmax": [
85,
100
]
}
],
"total_distance": 4070.0806
}
Acceleration / Deceleration
For each Acceleration/Deceleration threshold provided at the timeframe create we will provide an "threshold_X" object with the used threshold and a list of occurence of acceleration / deceleration. Each occurence contain time of occurence, duration, distance, initial speed (speed at the begining of the acceleration / deceleration), end speed (speed at the end of the acceleration / deceleration).
In the following example 2 threshold where provided 2 and 2 m/s^2. We got 3 acceleration event >= 2m/s^2, We got 3 acceleration event >= 3m/s^2, we got 3 decceleration event >= 2m/s^2 and we got 3 decceleration event >= 3m/s^2.
"accelerations": {
"threshold_2": {
"threshold": 3,
"values": [
{
"start_time": 1620647640000,
"max_value": 3.148,
"duration": 3.2,
"distance": 10.018,
"initial_speed": 0.282,
"end_speed": 4.897
},
{
"start_time": 1620647653500,
"max_value": 3.001,
"duration": 2.3,
"distance": 9.33,
"initial_speed": 1.462,
"end_speed": 4.763
}
{
"start_time": 1620647810200,
"max_value": 3.94,
"duration": 1.4,
"distance": 5.748,
"initial_speed": 1.046,
"end_speed": 4.303
}
]
},
"threshold_1": {
"threshold": 2,
"values": [
{
"start_time": 1620647750800,
"max_value": 2.615,
"duration": 1.9,
"distance": 4.464,
"initial_speed": 0.423,
"end_speed": 3.048
},
{
"start_time": 1620647753200,
"max_value": 2.585,
"duration": 1.5,
"distance": 6.144,
"initial_speed": 2.147,
"end_speed": 4.274
},
{
"start_time": 1620647806800,
"max_value": 2.176,
"duration": 1.8,
"distance": 3.869,
"initial_speed": 0.325,
"end_speed": 2.639
}
]
}
},
"decelerations": {
"threshold_2": {
"threshold": 3,
"values": [
{
"start_time": 1620647997200,
"max_value": -3.605,
"duration": 2.7,
"distance": 6.633,
"initial_speed": 5.036,
"end_speed": 0.602
},
{
"start_time": 1617113240900,
"max_value": -4.414,
"duration": 1.9,
"distance": 5.28,
"initial_speed": 5.201,
"end_speed": 1.42
},
{
"start_time": 1617113353300,
"max_value": -3.025,
"duration": 3.1,
"distance": 8.25,
"initial_speed": 5.426,
"end_speed": 0.967
}
]
},
"threshold_1": {
"threshold": 2,
"values": [
{
"start_time": 1620647563100,
"max_value": -2.109,
"duration": 1.9,
"distance": 3.345,
"initial_speed": 3.38,
"end_speed": 1.093
},
{
"start_time": 1620647580800,
"max_value": -2.304,
"duration": 1.9,
"distance": 3.61,
"initial_speed": 3.618,
"end_speed": 1.286
},
{
"start_time": 1620647625500,
"max_value": -2.288,
"duration": 1.6,
"distance": 3.096,
"initial_speed": 3.47,
"end_speed": 1.35
}
]
}
},
HID
HID: High Intensitfy Distand is the distance run by an athlete at high intensity (above a threshold of speed). For each hid threshold provided at the timeframe create we will provide an "threshold_X" object with the used threshold and a list of occurence of HID event. Each occurence contain time of occurence, duration, distance, max value of speed. In the following example 2 threshold where provided 4 and 5 m/s. We got 3 HID event >= 4m/s and we got 3 HID event >= 5 m/s.
"hid": {
"threshold_1": {
"threshold": 4,
"values": [
{
"start_time": 1620647640600,
"duration": 2.3,
"max_value": 4.9205,
"distance": 10.234429367452526
},
{
"start_time": 1620647654400,
"duration": 1.8,
"max_value": 4.825,
"distance": 7.764227285098559
},
{
"start_time": 1620647668400,
"duration": 2.8,
"max_value": 5.132300000000001,
"distance": 12.575696540185104
}
]
},
"threshold_2": {
"threshold": 5,
"values": [
{
"start_time": 1620647669100,
"duration": 0.9,
"max_value": 5.132300000000001,
"distance": 4.366224612946011
},
{
"start_time": 1620647994600,
"duration": 0.2,
"max_value": 5.0455000000000005,
"distance": 1.0167155193156558
},
{
"start_time": 1620647994900,
"duration": 0.4,
"max_value": 5.0509,
"distance": 1.9831344982124
}
]
}
},
Sprint
For sprint threshold provided at the timeframe create we will provide an "threshold_X" object with the used threshold and a list of occurence of sprint event. Each occurence contain time of occurence, duration, distance, max value of speed. In the following example 1 threshold was provided 5 m/s. We got 4 sprint >= 5m/s.
"sprint": {
"threshold_1": {
"threshold": 5,
"values": [
{
"start_time": 1620647669100,
"duration": 0.9,
"max_value": 5.132300000000001,
"distance": 4.366224612946011
},
{
"start_time": 1620647994600,
"duration": 0.2,
"max_value": 5.0455000000000005,
"distance": 1.0167155193156558
},
{
"start_time": 1620647994900,
"duration": 0.4,
"max_value": 5.0509,
"distance": 1.9831344982124
},
{
"start_time": 1617113221100,
"duration": 1.1,
"max_value": 5.298100000000001,
"distance": 5.5218264995377
}
]
}
},
Activity
Introduction
An activity is an event that will contain one or several timeframes. Typically an activity can be: a game, a training session, etc.
The purpose of this section is to describe elements contained in the json object.
Example
The following example show you the body of a activity creation request with some parameters passed in the json object.
{
"name": "Example Activity",
"json": {
"type": "training",
"pitch": {
"name": "pitch_name",
"coordinates": [
[
43.709343973495756,
7.193926870296994
],
[
43.64254842506836,
7.1997633571134
],
[
43.68030077128003,
7.27392107195715
],
[
43.72460463193114,
7.23546892351965
]
]
},
"sport": "soccer",
"enu_reference": [
43.698919826987705,
7.223967611263791
]
},
"json_schema": 3,
"owner": 140
}
Required fields
sport
Optional fields
typeenu_referencepitch
Fields definitions
sport
This field provide us the information of which kind of sport will be analyzed. This field is mendatory. We need to know it to be able to apply the correct algorithm.
"sport": "soccer"
type
This field give us an in about the usage of the data. This field is Optional. For now it's not used but in the future it will allow us to include or not certains statistics based on the type of session (practice vs training).
"type": "training"
enu_reference
This field provide us a geographic reference for converting lat/lng position into X/Y/Z position. This field is Optional but highly recommended.
The reference can be a 2D point (Lat[DD]/Lng[DD]) or a 3D coordinates (Lat[DD]/Lng[DD]/alt[m AMSL]). If no altitude is provided 0m will be used.
Without "enu_reference" we wont be able to provide certains proprocessed data nor computed data (see bellow).
"enu_reference": [
46.608219126187405,
6.673927612267701
]
"enu_reference": [
46.608219126187405,
6.673927612267701,
328
]
pitch
This field provide us the four geographic position of the 4 corners of the pitch. This will allow us to rotate the pitch to provide X / Y / Z coordinate in a convenient way. This field is Optional but highly recommended.
The reference can be a 2D point (Lat[DD]/Lng[DD]) or a 3D coordinates (Lat[DD]/Lng[DD]/alt[m AMSL]). If no altitude is provided 0m will be used.
"pitch": {
"name": "pitch_name",
"coordinates": [
[
43.709343973495756,
7.193926870296994
],
[
43.64254842506836,
7.1997633571134
],
[
43.68030077128003,
7.27392107195715
],
[
43.72460463193114,
7.23546892351965
]
]
},
Timeframe
Introduction
A timeframe is an assignement between a Device and Athlete for a defined time period associated to an Activity. Typically a timeframe can be a period, a half-time or a specific exercice during a training session. The purpose of this section is to describe elements contained in the params object.
Example
The following example show you the body of a timeframe creation request with some parameters passed in the params object.
{
"id": 3064,
"uuid": "4cae0495d24cc1453acbda661af",
"start_time": "2020-12-24T12:00:00Z",
"end_time": "2020-12-24T16:00:00Z",
"params": {
"max_hr": 150,
"hr_zones": [
0,
20,
40,
60,
80,
100
],
"birthdate": "1990-05-01",
"speed_ranges": [
1.0,
2.0,
3,
4.0
],
"hid_threshold": [
2.5
],
"hr_plot_points": 250,
"accel_threshold": [
2,
3
],
"sprint_threshold": [
2
],
"intensity_graph_interval": 300
},
"device": 4351,
"activity": 31456,
"athlete": 465,
"owner": 5461,
"json_schema": 2
}
Required fields
None.
Optional fields
max_hrhr_zoneshr_plot_pointsbirthdatespeed_rangeshid_thresholdaccel_thresholdsprint_thresholdintensity_graph_interval
Fields definitions
max_hr
this field provide us what should be considered as the maximum heartrate for the athlete.
"max_hr": 150
hr_zones
This field provide us range of percentage of athlete_max_hr, that will be used to compute the Heartrate per zone.
"hr_zones": [0, 20, 40, 60, 80, 100]
hr_plot_points
Number of points used to render the hr_plot graph.
"hr_plot_points": 250
birthdate
The birthdate of the athlete. This field is used to compute the max_hr if it's not provided.
"birthdate": "1990-05-01"
speed_ranges
distance_per_speed_ranges graph represent the distance run by an athlete per range of speed. This field provide us range of speed (in m/s) that will be used to compute the graph.
The first range will be < first_value, and the last range will be > last_value. In the following example we will have 5 ranges: ];1.0], [1.0;2.0[, [2.0;3.0[, [3.0;4.0[, [4.0;[
"speed_ranges": [1.0, 2.0, 3, 4.0]
hid_threshold
This value provide us the threshold (in m/s) above which we will consider the run beeing "High intensity". It will be used to compute the hid graph.
"hid_threshold": [17.0]
accel_threshold
This value provide us the threshold (in m/s^2) above which we will count the run beeing an "acceleration" / "deceleration".
"accel_threshold": [3.0]
sprint_threshold
This value provide us the threshold (in m/s^2) above which we will count the run beeing a "sprint".
"sprint_threshold": [24.0]
intensity_graph_interval
The intensity_graph represent the distance run per slice of X minute. This value define the size of the slice (in minute).
"intensity_graph_interval": 2
Summary of required parameters for each statistics
| Statistics | Requirements Activity | Requirements Timeframe |
|---|---|---|
first_timestamp | None | None |
last_timestamp | None | None |
average_speed | None | None |
max_speed | None | None |
total_distance | enu_reference or pitch | None |
distance_per_speed_ranges | enu_reference or pitch | speed_ranges |
accelerations / decelerations | enu_reference or pitch | accel_threshold |
sprint | enu_reference or pitch | sprint_threshold |
hid | enu_reference or pitch | hid_threshold |
hr_min | None | None |
hr_avg | None | None |
hr_max | None | None |
timePerHrZone | None | athlete_max_hr, hr_zones |
hr_plot | None | hr_plot_points |
intensity_graph | enu_reference or pitch | intensity_graph_interval |