*/unified
API that unifies a lot of features from our other API's.
Preliminary: This API is currently in preview and not production-ready. We may make changes before it is finalized. You’re welcome to test it for free during this period.
Request
URL https://racemap.com/api/data/v1/:eventId/unified
Method GET
Live sample https://racemap.com/api/data/v1/6980acc569cb395d4f6a3431/unified Corresponding map https://racemap.com/player/10k-street-run-live-sample
Optional query parameters
Set various query parameters according to your need when calling the API endpoint, e.g. to smoothen gap values.
The
resultTimeparameter defines a timestamp from which you want to have the results.ISO 8601 UTC String for API ?resultTime=2026-01-29T09:23:00.000Z
Divisions define the tags used to build participant buckets to which rankings are applied. When two divisions are specified, their combinations are also considered—for example, all female participants from a given country.
Append participant tags as division like this: ?divisions=sex,nationality
Duration in seconds used to derive speed values in the API. If
avgSpeedWindowis set to 120 seconds, the distance covered during the last 2 minutes is used to calculate the current speed.Default: 300 seconds
Maximum value: 1800 seconds
String for API ?avgSpeedWindow=120
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/6980acc569cb395d4f6a3431/unified?divisions=sex&avgSpeedWindow=600
Response
Event object
id
Unique ID of event, generated in RACEMAP
6980acc569cb395d4f6a3431
name*
Name of event
"10k street run"
eventType*
Type of sport
"running"
location*
Location of the event
"🇩🇪 Dresden"
resultTime
Time the data belongs to. Usually "now" if not provided or equal to the value of the resultTime query parameter.
"2022-03-09T10:00:0.000Z"
startTime*
Start time in UTC
"2022-03-09T07:00:03.201Z"
endTime*
End time in UTC
"2022-03-09T14:59:38.201Z"
shadowTrackUrl
Link to download the shadow track as geo json
progress
How much of the event has been passed [%]
53.97
divisions
List of all ranking buckets thast have been processed.
readers
Array of all timing hardware locations in this event
timekeepings
Array of split points
starters
Array for participant objects
*User defined in RACEMAP event's settings.
Readers object
Represents the timing hardware at the race course. The reader information is extracted from all received reads within the event time.
readerId
Unique ID of the reader, provided by timing system
"T-12056"
readerName
Name of the reader, available only if provided by timing system
"Backup 5K" or "10km"
readsCount
All reads read by this reader within event time
2125
readAt
Time of the latest read
"2022-03-09T07:00:03.201Z"
progress
How much of the event has been passed when the latest read was read [%]
53.97
lng
Longitude of the reader
13.727678288
lat
Latitude
50.976534023
Timekeepings object
Represents those split points in the event's map settings with an activated "timekeeping" property.
id
Unique ID of the split point, generated in RACEMAP
6450e60747adaed475b48
name
Name of the split
"Split 5" or "Water Station"
position
Array with longitude, latitude, hight [m]
13.881129999, 51.075250000, 250
Participant object
id
Unique ID of participant, generated in RACEMAP
"61a2122f181c0a6c4bb5376e"
name*
Name
"K. Treppe" or "Leupold"
startNumber*
Bib number
"2" or "052"
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-49", "sex": "mal",
importId
User-defined ID with imported participant data, Generic API (importId) or RACE|RESULT API (Id)
"UniqueImportId_2" or "null"
if no importId exists
ranks
ranks of the participant, processed by RACEMAP
"12" or "283"
startTimeMeta
Start time in UTC
"2020-04-25T06:00:00Z"
finishTimeMeta
Finish time in UTC
"2020-04-25T12:10:13Z"
startTimeDerived
Start time in UTC, processed in RACEMAP
"2020-04-25T06:00:05Z"
finishTimeDerived
Finish time in UTC, processed in RACEMAP
"2020-04-25T12:10:12Z"
current
Array with latest information about the participant
reads
Array with the accepted reads of the participant
results
*The parameter is imported or synchronized with RACEMAP from an external source.
Ranks object
Each participant can have multiple rankings. For example, a participant may place 12th overall while ranking 1st in their age group.
Overall rankings are always calculated and are divided into absolute and elapsed types. Special ranking categories—such as sex or age group—are calculated on demand. For details, please refer to the optional divisions query parameter.
Elapsed: Ranks participants by who covered the greatest distance in the shortest amount of time. This is also referred to as net time.
Absolute: Ranks participants by the total distance covered at the current moment.
timing
If the ranking is of type absolute or elapsed
"elapsed"
position
The position of this participant within the ranking category
127
total
Total number of participants in the ranking category
251
divisions
Tags defining the ranking category.
sex: "male"
or
nation: "GER"
Current object
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 *
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 point in time 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
time
Timestamp in UTC of geolocation
"2022-01-24T16:33:47.012Z"
lng
Longitude of the participant
13.73032
lat
Latitude
51.00622
elv
Altitude above zero [m]
593
speed
Average speed [m/s]
5.2727
fromStart
Distance from first geolocation of shadowtrack along shadowtrack [m]
9962.6826
toFinish
Distance to last geolocation of shadowtrack along shadowtrack [m]
89097.3173
eta
Estimated time of arrival [s], time from now to reach last geolocation of shadowtrack, prediction with speed
16897.77
Reads object
Does not provide all received detections of the participant. Provides only those reads, that have been validated by the prediction - accepted reads.
readerId
Unique ID of the reader, provided by timing system
"T-12056"
time
Timestamp in UTC of detection through timing system
"2022-03-09T14:59:38.201Z"
Results object
Represents either virtual detections from prediction - extrapolation or interpolation. If the offsets of read and timekeeping are close to each other then it represents the detection from timing system.
id
Unique ID of the split point, generated in RACEMAP
6450e60747adaed475b48
time
Timestamp in UTC of prediction: extrapolation or interpolation OR detection from timing system
"2022-03-09T14:59:38.201Z"
Last updated