*/current, location data
API with processed real-time geolocation data, for TV graphics, speed monitor, gap time calculation, ...
URL
https://racemap.com/api/data/v1/:eventId/current
Method GETLive sample https://racemap.com/api/data/v1/6336f41309be310001a5894b/current
Corresponding map https://racemap.com/player/100KmDuathlon2018_API-liveSample
Set various query parameters according to your need when calling the API endpoint, e.g. in order to smoothen gap values.
deviceId
startNumber
interpolation
currentSpeedDuration
liveDelay
- The
deviceId
of a chosen reference device for calculationgapAverage
,gap
,gapChase
andgapDistance
. - String for API ?deviceId=6336f41309be310001a58977
- The
startNumber
of a chosen reference device for calculationgapAverage
,gap
,gapChase
andgapDistance
. - String for API ?startNumber=053
true
orfalse
- Default: true
- The raw geodata from the GPS devices is converted into a grid. The interpolation interval specifies the time difference between consecutive coordinates in this grid.
- Default interpolation interval: 10 sec. Adjust the interpolation interval in the advanced settings of the tracking map.
- Duration in seconds to average the
speed
values in the API. IfcurrentSpeedDuration
is set to 120, then the averagespeed
of the last 2 minutes is calculated. - Default: ten times the interpolation interval. If the interpolation interval is set to 2, then the
currentSpeedDuration
is 20. - Maximum value: 1800
- String for API ?currentSpeedDuration=120
- Duration in seconds from the timestamp recording a location until this location is provided in the API.
- Default: 20, according to "Live delay time" in advanced settings of the tracking map. The set
liveDelay
query parameter processes the values in the API without impact on the visualization. - Maximum value: 1800
- String for API ?liveDelay=200
You can call the same API endpoint with different query parameters at the same time.
You can also combine queries with & in one call eg.
https://racemap.com/api/data/v1/6336f41309be310001a5894b/current?liveDelay=600&interpolation=false¤tSpeedDuration=600&deviceId=6336f41309be310001a58977
Field | Description [unit] | Sample |
---|---|---|
name | Name of event | "100km Duathlon" |
location | Location | "Dresden" |
startTime | Start time in UTC | "2022-01-24T15:00:10.000Z" |
endTime | End time in UTC | "2022-01-24T22:59:45.000Z" |
starters | Array for participant objects | |
Field | Description [unit] | Sample |
---|---|---|
id | Unique Racemap ID of participant | "61a2122f181c0a0ff7b53765" |
name | Name | "CLV Megware" |
startNumber | Bib number | "001" |
importId | "UniqueImportId_1" or "null"
if no importId exists | |
current | Object for real-time location data | null
if no locations within startTime and endTime |
current
-object provides the latest data- (*) calculated only for events with a shadowtrack, projection of device locations on the shadowtrack within 100 m distance from shadowtrack
gapAverage
,gap
,gapChase
andgapDistance
are calculated for the leader by default. Leader: device with the smallesttoFinish
value. Attention: Each time a leader reaches the finish the device closest to the finish becomes the new leader. The speed value of the next leader may impact fluctuating gap values. Reference: If query withdeviceId
orstartNumber
, then calculation with reference values instead of leader.
Field | Description [unit] | Sample |
---|---|---|
time | Timestamp in UTC when geolocation was recorded, if interpolation=true then linear interpolation between the latest two points | "2022-01-24T16:33:47.012Z" |
lng | Current longitude of participant | 13.727678288 |
lat | Latitude | 50.976534023 |
elv | Altitude above zero on shadowtrack [m] | 85.2 or null
if device is not on shadowtrack |
speed | Average speed [m/s] depending on currentSpeedDuration . If event has a shadowtrack, than projection on shadowtrack. If event without shadowtrack, than same value as speedRaw . | 5.2727 |
speedRaw | Average speed [m/s] depending on currentSpeedDuration. Calculation with interpolated raw coordinates. | 4.9574 |
fromStart * | Distance from first geolocation of shadowtrack along shadowtrack [m] | 9962.6826 |
toFinish * | Distance to last geolocation of shadowtrack along shadowtrack [m] | 89097.3173 |
distanceToShadowTrack * | Distance from shadowtrack [m] if more than 100 m | 175.9 |
eta * | Estimated time of arrival [s], time to reach last geolocation of shadowtrack, prediction with speed | 16897.77 |
gapAverage * | Duration [s] to reach current toFinish value of the leader, prediction with leader's average speed for current segment between device and leader.
| 2360.36 or null if reference is behind device, toFinish of reference is greater than toFinish of device |
gap * | Duration [s] to reach current toFinish value of the leader, prediction with speed value of leader, if speed < 1 km/h then prediction with default speed value of the event, | 1205.68 or -581.20 if reference is behind device |
gapChase * | Duration [s] to reach current toFinish value of the leader, prediction with speed value of device, if speed < 1 km/h then prediction with default speed value of the event | 968.81 or -73.02 if reference is behind device |
gapDistance * | Distance [m] to reach current toFinish value of the leader. | 3364.91 or -554.03 if reference is behind device |
{
"name": "Sample live API | 100km Duathlon",
"location": "🇩🇪 Dresden",
"startTime": "2022-11-21T10:13:31Z",
"endTime": "2022-11-21T14:12:55Z",
"starters": [
{
"id": "6336f41309be310001a5894c",
"name": "🔥 Flaming 🔥 Sideburns 🔥",
"startNumber": "001",
"importId": "UniqueImportId_1",
"current": {
"time": "2022-11-21T14:04:30.421Z",
"lng": 13.878789334666667,
"lat": 51.070914418,
"elv": 244,
"speed": 5.614035087719298,
"speedRaw": 4.273781783603631,
"fromStart": 47792.806666666664,
"toFinish": 50567.193333333336,
"distanceToShadowTrack": 6.6575740360137345,
"eta": 9007.281,
"gapAverage": 2768,
"gap": 2071.573,
"gapChase": 2213.993,
"gapDistance": 12429.438666666669
}
},
{
"id": "6336f41309be310001a58977",
"name": "Vorausfahrer",
"startNumber": "📢",
"importId": null,
"current": {
"time": "2022-11-21T14:04:30.421Z",
"lng": 13.819698388666668,
"lat": 51.10816512466666,
"elv": 239,
"speed": 6,
"speedRaw": 5.752663856878707,
"fromStart": 60222.24533333333,
"toFinish": 38137.75466666667,
"distanceToShadowTrack": 4.357202339570443,
"eta": 6356.292,
"gapAverage": 14,
"gap": 0,
"gapChase": 0,
"gapDistance": 0
}
},
{
"id": "6336f41309be310001a5897e",
"name": "Harzer Roller Club",
"startNumber": "022",
"importId": null,
"current": null
}
]
}
The below parameters and settings smoothen the values in the API.
- Call the
gapAverage
value instead ofgap
value - Interpolation=true
- Query parameter
currentSpeedDuration
Use
gapAverage
instead of gap
if you need smoothly changing gap values e.g. for TV production. 
the average speed of the reference device smoothens the
gapAverage
values in the APIComparison | interpolation=true | interpolation=false |
---|---|---|
Use case | Values changing smoothly with each call | Latest values with a minimum delay |
Calculation | Linear interpolation between latest coordinate in the time grid and the coordinate before | Latest coordinate without interpolation from the time grid |
Refresh rate | Up to 1 sec | Report interval of GPS device |
Recommended interpolation interval | report interval of GPS device | report interval of GPS device |
Recommended liveDelay | 5 sec + interpolation interval | 5 sec minimum |
Increase the
currentSpeedDuration
query parameter to smooth the speed
values in the API.You can calculate on your side using the */current API.
Gap distance between two participants:
fromStart
(participant 1) - fromStart
(participant 2)Gap duration between two participants:
- option 1:
gapAverage
(participant 2) -gapAverage
(participant 1) => value with flatten peaks - option 2:
eta
(participant 2) -eta
(participant 1) - option 3:
gap
(participant 2) -gap
(participant 1)
Identify the leader: the smallest value of
toFinish
Last modified 2mo ago