*/current, location data

API with processed real-time geolocation data, for TV graphics, speed monitor, gap time calculation, ...

Request
URL https://racemap.com/api/data/v1/:eventId/current 
Method GET
Live sample https://racemap.com/api/data/v1/6336f41309be310001a5894b/current
Corresponding map https://racemap.com/player/100KmDuathlon2018_API-liveSample​
Optional query parameters
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 calculation gapAverage, gap, gapChase and gapDistance.
String for API ?deviceId=6336f41309be310001a58977
Sample https://racemap.com/api/data/v1/6336f41309be310001a5894b/current?deviceId=6336f41309be310001a58977​
The startNumber of a chosen reference device for calculation gapAverage, gap, gapChase and gapDistance.
String for API ?startNumber=053
Sample: https://racemap.com/api/data/v1/6336f41309be310001a5894b/current?startNumber=053​
true or false
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.
Sample https://racemap.com/api/data/v1/6336f41309be310001a5894b/current?interpolation=false​
Duration in seconds to average the speed values in the API. If currentSpeedDuration is set to 120, then the average speed 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
Sample https://racemap.com/api/data/v1/6336f41309be310001a5894b/current?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
Sample https://racemap.com/api/data/v1/6336f41309be310001a5894b/current?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&currentSpeedDuration=600&deviceId=6336f41309be310001a58977​
Response
Event object
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 
​
Participant object
Field
Description [unit]
Sample
id
Unique Racemap ID of participant
"61a2122f181c0a0ff7b53765"
name
Name
"CLV Megware"
startNumber
Bib number
"001"
importId
User-defined ID with imported participant data, Generic API (importId) or RACE|RESULT API (Id)
"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
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.
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
Sample response
{
  "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
    }
  ]
}
​
Smoothen values in the API
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. 
the average speed of the reference device smoothens the gapAverage values in the API
Comparison
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.
Subsequent calculations 
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

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`	User-defined ID with imported participant data, Generic API (`importId`) or RACE\|RESULT API (`Id`)	`"UniqueImportId_1"` or `"null"` if no importId exists
`current`	Object for real-time location data	`null` if no locations within `startTime` and `endTime`

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

Comparison	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

Data APIs for live geodata

*/distance and locations

Last modified 2mo ago