Ctrlk
UpdatesGPS trackersFree trialSchedule video call
For the complete documentation index, see llms.txt. This page is also available as Markdown.

*/current, location data

API with real-time geolocation data, for TV graphics, speed monitor, gap time calculation, or any other applications and dashboards.

Request

URL https://racemap.com/api/data/v1/:eventId/current Method GET

Live sample https://racemap.com/api/data/v1/66bf4318d1c783279d183dd3/current Corresponding map https://racemap.com/player/100KmDuathlon2018_API-live-sample

Optional query parameters

Specify the query parameters when calling the API endpoint, e. g. to smoothen gap values.

The participantId of a specified reference participant for the calculation of gapAverage, gap, gapChase, gapDistance, gapAverageEx, gapEx, gapChaseEx and gapDistanceEx.

The startNumber of a specified reference device for the calculation of gapAverage, gap, gapChase, gapDistance, gapAverageEx, gapEx, gapChaseEx and gapDistanceEx.

Duration [seconds] for the calculation of the average speed and speedRaw values.

  • avgSpeedWindow defines how far back in time the API looks from the latest known coordinate at the specified resultTime. The other coordinate at the other side of the window is interpolated between recorded coordinates.

  • If avgSpeedWindow is set to 120, the API calculates speed values based on the distance covered during the last 2 minutes.

  • Default: 300

  • Maximum: 1800

  • String for API ?avgSpeedWindow=120

  • Sample https://racemap.com/api/data/v1/66bf4318d1c783279d183dd3/current?avgSpeedWindow=120

  • alias: currentSpeedDuration

UTC timestamp that defines the reference time for the API response.

Response

Event object

Field
Description
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"

resultTime

UTC timestamp for which you retrieve API data.

"2022-01-24T20:00:10.000Z"

shadowTrackUrl

URL to download the shadowtrack as a geojson file

"https://racemap.com/api/events/66bf4318d1c783279d183dd3/geo/shadow.json"

starters

Array for participant objects

Participant object

Field
Description
Sample

id

Unique RACEMAP ID of the participant

"61a2122f181c0a0ff7b53765"

name*

Name

"CLV Megware"

startNumber*

Bib number

"001"

markerColor*

Color of dot in tracking map, hex code

"#ffffff"

tags*

Object with optional attributes to filter participants eg. age group or nation, format "tag": "value"

"age": "40", "sex": "male"

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 and gap measurements and extrapolations

Inner values are null if no locations within startTime and endTime are known

device

Object for device information

null if device is not used in tracker management

*The parameter is imported or synchronized with RACEMAP from an external source.

Current object

  • current-object provides the latest data for the specified resultTime parameter.

  • (*) These parameters are calculated only for events with a shadowtrack and a mapping of the geolocation on the shadowtrack. The default max mapping distance is 100 m and can be changed in the Advanced Settings of the event. If the geolocation can not be mapped the corresponding (*) parameters are null.

  • gapDistance, gap, gapChase, gapAverage, gapDistanceEx, gapEx, gapChaseEx, and gapAverageEx are calculated for the leader by default. Leader: The device with the smallest toFinish value at resultTime. Attention: Each time a leader reaches the finish, the next device with the smallest toFinish value becomes the new leader. In this moment, the speed value of the next leader may impact fluctuating gap values. Reference: Query with participantId or startNumber for calculation against the reference participant instead of the leader.

Field
Description [unit]
Sample

lat/lng: Coordinate of the latest recorded geolocation.

time

UTC timestamp when the latest geolocation was recorded.

"2022-01-24T16:33:47.012Z"

lng

Longitude of the latest recorded geolocation.

13.727678288

lat

Latitude of the latest recorded geolocation.

50.976534023

speed

Average speed [m/s]. distance: sum of straight lines between coordinates time: avgSpeedWindow

Curves are cut between the two geolocations.

4.9574

distanceToShadowTrack

Shortest distance [m] between lat/lng and the shadowtrack.

175.9

lngSt/latSt: Mapping of the latest recorded geolocation (lat/lng) on the shadowtrack.

lngSt *

Longitude of the latest recorded geolocation mapped on the shadowtrack.

13.805551232 or null

latSt *

Latitude of the latest recorded geolocation mapped on the shadowtrack.

50.93151590 or null

speedSt *

Average speed [m/s] distance: segments covered on the shadowtrack time: avgSpeedWindow

5.2727 or null

elvSt *

Altitude [m] above zero of lngSt/latSt.

85.2 or null if device is not on shadowtrack

fromStart *

Distance [m] from the start point of the shadowtrack along the track to latSt/lngSt.

9962.6826 or null

toFinish *

Distance [m] from latSt/lngSt along the shadowtrack to the end point of the track.

89097.3173 or null

eta *

Estimated time of arrival [s], duration to move from latSt/lngSt to the end point of the shadowtrack, extrapolation with speedSt.

16897.77 or null

gapCalcTime *

UTC timestamp for which gapDistance, gap, gapChase and gapAverage is obtained. Value is older (or equal) than resultTime.

Q: What is the latest UTC timestamp (at the specified resultTime) for which the API knows recorded geolocations?

"2022-01-24T16:32:30.012Z" or null

gapDistance *

Distance [m] between latSt/lngSt and the toFinish value of the leader at gapCalcTime.

Q: What is the current distance between chaser and leader?

null or 3364.91 or -554.03 if reference is behind device

gap *

Duration [s] to move from latSt/lngSt along the shadowtrack to the toFinish value of the leader, calculated with the speedSt value of the leader at gapCalcTime.

null or 1205.68 or -581.20 if reference is behind device

gapChase *

Duration [s] to move from latSt/lngSt along the shadowtrack to the toFinish value of the leader, calculated with the speedSt value of the chaser at gapCalcTime.

null or 968.81 or -73.02 if reference is behind device

gapAverage *

Duration [s] to move from latSt/lngSt to the toFinish value of the leader, calculated with the timestamp of when the leader was at latSt/lngSt.

Q: How long did it took the leader to cover the distance gapDistance?

null or 2360.36 or -112.6 if reference is behind device

lngStEx/latStEx: Mapping of the latest recorded geolocation (lat/lng) on the shadowtrack (lngSt/latSt), further extrapolation on the track to the timestamp of resultTime with the speedSt value.

lngStEx *

Longitude of the latest recorded geolocation mapped on the shadowtrack and extrapolated to resultTime.

5.2727 or 13.805551232 or null

latStEx *

Latitude of the latest recorded geolocation mapped on the shadowtrack and extrapolated to resultTime.

50.93151590 or null

fromStartEx *

Distance [m] from the start point of shadowtrack along the track to lngStEx/latStEx.

9963.6826 or null

toFinishEx *

Distance [m] from lngStEx/latStEx along the shadowtrack to the end point of the track.

890967.3173 or null

gapDistanceEx *

Distance [m] from lngStEx/latStEx along the shadowtrack to reach the toFinishEx value of the leader.

null or 3374.91 or -564.03 if reference is behind device

gapEx *

Duration [s] to move from lngStEx/latStEx along the shadowtrack to the toFinishEx value of the leader, calculated with the speedSt value of the leader at resultTime.

Q: How long does it take the leader to move backward with his current speed until he reaches the chaser's location?

null or 1305.68 or -591.20 if reference is behind device

gapChaseEx *

Duration [s] to move from lngStEx/latStEx along the shadowtrack to the toFinishEx value of the leader, calculated with the speedSt value of the chaser at resultTime.

Q: How long does it take for the chaser with his current speed to reach the leader's location?

null or 978.81 or -93.02 if reference is behind device

gapAverageEx *

Duration [s] to move from lngStEx/latStEx along the shadowtrack to the toFinishEx value of the leader, calculated with the timestamp of when the leader was at the same offset on the track.

Q: How long did it took the leader to cover the distance gapDistanceEx?

null or 2560.36 or -132.6 if reference is behind device

Device object

The device object provides additional information for GPS trackers used in the tracker management.

Field
Description [unit]
Sample

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

charging

Shows whether the device is currently being charged. Only reliable if online is true.

true or false

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

isMoving

Shows wether a device is moving or not. Only valid if a device is online.

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"

isMoving is available only for Queclink GL3xx GPS trackers. The value is derived from accelerometer data.

charging is reported by Queclink GL3xx, Concox M20 and Mictrack GPS trackers. Other devices always report false.

Most devices send a message only when charging starts or stops, so the value keeps the last state the device reported. It is therefore of good quality only while online is true. If online is false, read charging as the last known state, not the current one.

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.

Sample

JSON response example

Speed calculations

Speeds can vary significantly in dense datasets, mainly because of GPS position inaccuracies. To reduce these fluctuations, you can use the avgSpeedWindow parameter to smooth the speed curve. The figure below illustrates the effect of avgSpeedWindow on both dense and sparse datasets.

Increase the avgSpeedWindow query parameter to smooth the speed values in the API more.

The green and orange rectangles show the gapAverageWindows used for speedSt calculation.

How gaps are calculated

The values of the three gap parameters gap, gapChase, and gapAverage provide a duration in seconds. You can interpretate is as time, it takes to get there?

  • gap and gapEx: calculated with speedSt of the leader

  • gapChase and gapChaseEx: calculated with speedSt of the chaser

  • gapAverage and gapAverageEx: calculated with speedSt of the leader

gap and gapChase are based on local speed conditions at the participants’ positions, whereas gapAverage can incorporate the impact of elevation and intermediate. I. e. the below example diagram shows a short stop of the leader at around 68.8 km.

Recorded geolocations for two GPS devices: Locations mapped on the shadowtrack (offset axis) over the timeline (x axis). The leader (orange) is performing ahead of the chaser (blue). The diagram shows the gaps calculated for the current API output. The colored rectangles highlight the gapAverageWindows used for speedSt calculation.

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

Last updated

Was this helpful?