*/current, location data
API with real-time geolocation data, for TV graphics, speed monitor, gap time calculation, ...
Last updated
API with real-time geolocation data, for TV graphics, speed monitor, gap time calculation, ...
Last updated
URL https://racemap.com/api/data/v1/:eventId/current
Method GET
Live sample Corresponding map
Set various query parameters according to your need when calling the API endpoint, e.g. to smoothen gap values.
The Id of a chosen reference participant for calculation gapAverage, gap, gapChase and gapDistance.
String for API ?deviceId=66bf4318d1c783279d183e3d
Sample
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.
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
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
device
Object for device information
null if device is not used in tracker management
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 and gapDistance are calculated for the leader by default.
Leader: device with the smallest toFinish 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 with deviceId or startNumber, then calculation with reference values instead of leader.
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. Calculated from two interpolated raw coordinates.
Note: Curves are cut off between the two 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
lngSt *
Current longitude of participant pinned on the shadowtrack
13.805551232
latSt *
Latitude
50.931515901
The device object provides additional information for GPS trackers, that are used in tracker management.
externalId
Unique id of tracking device, can be IMEI or transponder id or App id depending on the type of device.
"4106050246" or "860599002489748" or "RRPing_ZDKAR32" or "d40ad78e-b929-4224-967e-62ca93effc68"
battery
Charge level [%] of device.
3, 52, 99
online
Connection status with RACEMAP server, determined by checking if there is a socket connection to the device and evaluating the time since the last message was received.
true or false
lastLocationGpsFix
Showing whether the device had a GPS fix when recording the latest coordinate.
true or false
lastLocationAt
Timestamp in UTC when the latest coordinate was recorded. Note: If interpolation=true lastLocationAt can differ from time.
"2022-01-24T16:33:47.012Z"
deviceId
Unique id of the tracking device in RACEMAP.
"5b6ac1561c6a700020a00010"
The GPS tracker does not send the information when it loses the GPS fix. If the device loses the fix, no coordinates are recorded. Therefore, evaluating online status along with lastLocationAt provides a more reliable observation than relying solely on the lastLocationGpsFix parameter.
If online is true but there is no current lastLocationAt:
Device may have lost its GPS fix and is unable to record coordinates.
Could suggest potential tampering or manipulation, also.
If online is false:
Device may have lost its network connection.
Device may have been turned off, also.
The below parameters and settings smoothen the values in the API.
Call the gapAverage value instead of gap value
Interpolation=true
Query parameter currentSpeedDuration
Use gapAverage instead of gap if you need smoothly changing gap values e.g. for TV production.
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
User-defined ID with imported participant data, (importId) or (Id)
gapAverage values in the API