# \*/unified

{% hint style="danger" %}
**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.
{% endhint %}

### 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](https://racemap.com/player/racemap-or-loop-prediction-10k-street-run_2026-02-02/)

#### Optional query parameters

Set various query parameters according to your need when calling the API endpoint, e.g. to smoothen gap values.

{% tabs %}
{% tab title="resultTime" %}

* The `resultTime` parameter defines a timestamp from which you want to have the results.
* ISO 8601 UTC String for API <mark style="background-color:red;">**?resultTime**</mark>**=2026-01-29T09:23:00.000Z**
* Sample <https://racemap.com/api/data/v1/66bf4318d1c783279d183dd3/unified?resultTime=2026-01-29T09:23:00.000Z>
  {% endtab %}

{% tab title="divisions" %}

* Divisions define the [tags](/api-import-and-export-data/import-basics/metadata-api.md#format-of-import-data) 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: <mark style="background-color:red;">**?divisions**</mark>**=sex,nationality**
* Sample <https://racemap.com/api/data/v1/6980acc569cb395d4f6a3431/unified?divisions=sex,nationality>
  {% endtab %}

{% tab title="avgSpeedWindow" %}

* Duration in seconds used to derive speed values in the API. If `avgSpeedWindow` is set to 120 seconds, the distance covered during the last 2 minutes is used to calculate the current <kbd>speed</kbd>.
* Default: 300 seconds
* Maximum value: 1800 seconds
* String for API <mark style="background-color:red;">**?**</mark>**avgSpeedWindow=120**
* Sample <https://racemap.com/api/data/v1/66bf4318d1c783279d183dd3/current?avgSpeedWindow=120>
  {% endtab %}
  {% endtabs %}

You can call the same API endpoint with different query parameters at the same time. \
You can also combine queries with <mark style="background-color:red;">**&**</mark> in one call eg. <https://racemap.com/api/data/v1/6980acc569cb395d4f6a3431/unified?divisions=sex&avgSpeedWindow=600>

### Response

#### Event object

<table><thead><tr><th width="209.73329671223956">Field</th><th width="439.5999755859375">Description [unit]</th><th>Sample</th></tr></thead><tbody><tr><td><code>id</code></td><td>Unique ID of event, generated in RACEMAP</td><td><code>6980acc569cb395d4f6a3431</code></td></tr><tr><td><code>name</code>*</td><td>Name of event</td><td><code>"10k street run"</code></td></tr><tr><td><code>eventType</code>*</td><td>Type of sport</td><td><code>"running"</code></td></tr><tr><td><code>location</code>*</td><td>Location of the event</td><td><code>"🇩🇪 Dresden"</code></td></tr><tr><td><code>resultTime</code></td><td>Time the data belongs to. Usually "now" if not provided or equal to the value of the <code>resultTime</code> query parameter. </td><td><code>"2022-03-09T10:00:0.000Z"</code></td></tr><tr><td><code>startTime</code>*</td><td>Start time in UTC</td><td><code>"2022-03-09T07:00:03.201Z"</code></td></tr><tr><td><code>endTime</code>*</td><td>End time in UTC</td><td><code>"2022-03-09T14:59:38.201Z"</code></td></tr><tr><td><code>shadowTrackUrl</code></td><td>Link to download the shadow track as geo json </td><td></td></tr><tr><td><code>progress</code></td><td>How much of the event has been passed [%]</td><td><code>53.97</code></td></tr><tr><td><code>divisions</code></td><td>List of all ranking buckets thast have been processed.</td><td><pre><code>...
"divisions": {
  "sex": ["f", "m"]
}
...
</code></pre></td></tr><tr><td><code>readers</code></td><td>Array of all timing hardware locations in this event</td><td></td></tr><tr><td><code>timekeepings</code></td><td>Array of split points</td><td></td></tr><tr><td><code>starters</code></td><td>Array for participant objects</td><td></td></tr></tbody></table>

\*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.

<table><thead><tr><th width="210.39996337890625">Field</th><th width="440.3332112630208">Description</th><th>Sample</th></tr></thead><tbody><tr><td><code>index</code></td><td>Index of the reader on the course, sequence according offset on the <a href="/pages/c4cBCt9aXT8vj2RRgUgs#shadowtrack">shadowtrack</a></td><td><code>1</code> or <code>31</code> </td></tr><tr><td><code>offset</code></td><td>Distance [m] on the <a href="https://docs.racemap.com/create-live-tracking/tab-map#shadowtrack">shadowtrack</a></td><td><code>49222.81</code></td></tr><tr><td><code>readerId</code></td><td>Unique ID of the reader, provided by timing system</td><td><code>"T-12056"</code></td></tr><tr><td><code>readerName</code></td><td>Name of the reader, available only if provided by timing system</td><td><code>"Backup 5K"</code> or <code>"10km"</code>   </td></tr><tr><td><code>readsCount</code></td><td>All reads read by this reader within event time</td><td><code>2125</code></td></tr><tr><td><code>readAt</code></td><td>Time of the latest read</td><td><code>"2022-03-09T07:00:03.201Z"</code></td></tr><tr><td><code>progress</code></td><td>How much of the event has been passed when the latest read was read [%]</td><td><code>53.97</code></td></tr><tr><td><code>lng</code></td><td>Longitude of the reader</td><td><code>13.727678288</code></td></tr><tr><td><code>lat</code></td><td>Latitude</td><td><code>50.976534023</code></td></tr></tbody></table>

#### Timekeepings object

Represents those [split points](/tab-map.md#splits) in the event's map settings with an activated "timekeeping" property.&#x20;

<table><thead><tr><th width="210.4000244140625">Field</th><th width="439.5334065755208">Description</th><th>Sample</th></tr></thead><tbody><tr><td><code>id</code></td><td>Unique ID of the split point, generated in RACEMAP</td><td><code>6450e60747adaed475b48</code> </td></tr><tr><td><code>name</code></td><td>Name of the split</td><td><code>"Split 5"</code> or <code>"Water Station"</code>  </td></tr><tr><td><code>offset</code></td><td>Distance [m] on the <a href="https://docs.racemap.com/create-live-tracking/tab-map#shadowtrack">shadowtrack</a></td><td><code>49222.81</code></td></tr><tr><td><code>position</code></td><td>Array with longitude, latitude, hight [m]</td><td><code>13.881129999, 51.075250000, 250</code></td></tr></tbody></table>

#### Participant object

<table><thead><tr><th width="209.73329671223956">Field</th><th width="440.4000244140625">Description [unit]</th><th>Sample</th></tr></thead><tbody><tr><td><code>id</code></td><td>Unique ID of participant, generated in RACEMAP</td><td><code>"61a2122f181c0a6c4bb5376e"</code></td></tr><tr><td><code>name</code>*</td><td>Name</td><td><code>"K. Treppe"</code> or <code>"Leupold"</code>  </td></tr><tr><td><code>startNumber</code>*</td><td>Bib number</td><td><code>"2"</code> or <code>"052"</code>  </td></tr><tr><td><code>markerColor</code>*</td><td>Color of dot in tracking map, hex code</td><td><code>"#ffffff"</code></td></tr><tr><td><code>tags</code>*</td><td>Object with optional attributes to filter participants eg. age group or nation, format <code>"tag": "value"</code></td><td><code>"age": "40-49", "sex": "mal",</code> </td></tr><tr><td><code>importId</code></td><td>User-defined ID with imported participant data, <a href="/pages/-LTq5TdE6GKt2S6dgesz">Generic API</a> (<code>importId</code>) or <a href="/pages/-LTh-oAm96bieBZVeffZ">RACE|RESULT API</a> (<code>Id</code>)</td><td><code>"UniqueImportId_2"</code> or <code>"null"</code><br>if no importId exists</td></tr><tr><td><code>ranks</code></td><td>ranks of the participant, processed by RACEMAP</td><td><code>"12"</code> or <code>"283"</code></td></tr><tr><td><code>startTimeMeta</code></td><td>Start time in UTC</td><td><code>"2020-04-25T06:00:00Z"</code></td></tr><tr><td><code>finishTimeMeta</code></td><td>Finish time in UTC</td><td><code>"2020-04-25T12:10:13Z"</code></td></tr><tr><td><code>startTimeDerived</code></td><td>Start time in UTC, processed in RACEMAP</td><td><code>"2020-04-25T06:00:05Z"</code></td></tr><tr><td><code>finishTimeDerived</code></td><td>Finish time in UTC, processed in RACEMAP</td><td><code>"2020-04-25T12:10:12Z"</code></td></tr><tr><td><code>current</code></td><td>Array with latest information about the participant </td><td></td></tr><tr><td><code>reads</code></td><td>Array with the accepted reads of the participant</td><td></td></tr><tr><td><code>results</code></td><td></td><td></td></tr></tbody></table>

\*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.

<table><thead><tr><th width="210.4000244140625">Field</th><th width="440.1333821614583">Description [unit]</th><th>Sample</th></tr></thead><tbody><tr><td><code>timing</code></td><td>If the ranking is of type <kbd>absolute</kbd> or <kbd>elapsed</kbd></td><td><code>"elapsed"</code></td></tr><tr><td><code>position</code></td><td>The position of this participant within the ranking category</td><td><code>127</code></td></tr><tr><td><code>total</code></td><td>Total number of participants in the ranking category</td><td><code>251</code></td></tr><tr><td><code>divisions</code></td><td>Tags defining the ranking category.</td><td><p></p><p><code>sex: "male"</code></p><p>or</p><p><code>nation: "GER"</code></p></td></tr></tbody></table>

#### Current object

<table data-full-width="false"><thead><tr><th width="208.2000732421875">Field</th><th width="500.199951171875">Description [unit]</th><th>Sample</th><th data-hidden>line</th><th data-hidden></th></tr></thead><tbody><tr><td></td><td><strong><code>lat</code>/<code>lng</code>:</strong> <br><strong>Coordinate of the latest recorded geolocation.</strong></td><td></td><td></td><td></td></tr><tr><td><code>time</code></td><td>UTC timestamp when the latest geolocation was recorded.</td><td><code>"2022-01-24T16:33:47.012Z"</code></td><td>14</td><td></td></tr><tr><td><code>lng</code></td><td>Longitude of the latest recorded geolocation.</td><td><code>13.727678288</code></td><td>15</td><td></td></tr><tr><td><code>lat</code></td><td>Latitude of the latest recorded geolocation.</td><td><code>50.976534023</code></td><td>16</td><td></td></tr><tr><td><code>speed</code></td><td><p>Average speed [m/s]. <br>distance: straight line between two coordinates <br>time: <code>avgSpeedWindow</code></p><div data-gb-custom-block data-tag="hint" data-style="info" class="hint hint-info"><p>Curves are cut between the two geolocations. </p></div></td><td><code>4.9574</code></td><td></td><td></td></tr><tr><td><code>distanceToShadowTrack</code></td><td>Shortest distance [m] between <code>lat</code>/<code>lng</code> and the shadowtrack. </td><td><code>175.9</code></td><td>22</td><td></td></tr><tr><td></td><td><strong><code>lngSt</code>/<code>latSt</code>:</strong> <br><a href="/pages/c4cBCt9aXT8vj2RRgUgs#what-is-mapping"><strong>Mapping</strong></a> <strong>of the latest recorded geolocation (<code>lat</code>/<code>lng</code>) on the shadowtrack.</strong></td><td></td><td></td><td></td></tr><tr><td><code>lngSt</code> *</td><td>Longitude of the latest recorded geolocation mapped on the shadowtrack.</td><td><code>13.805551232</code> or <code>null</code> </td><td></td><td></td></tr><tr><td><code>latSt</code> *</td><td>Latitude of the latest recorded geolocation mapped on the shadowtrack.</td><td><code>50.93151590</code> or <code>null</code></td><td></td><td></td></tr><tr><td><code>speedSt</code> *</td><td>Average speed [m/s] <br>distance: segment of the shadowtrack <br>time: <code>avgSpeedWindow</code></td><td><code>5.2727</code> or <code>null</code></td><td>21</td><td></td></tr><tr><td><code>elvSt</code> *</td><td>Altitude [m] above zero of <code>lngSt</code>/<code>latSt</code>.</td><td><code>85.2</code> or <code>null</code> <br>if device is not on shadowtrack</td><td>17</td><td></td></tr><tr><td><code>fromStart</code> *</td><td>Distance [m] from the start point of the shadowtrack along the track to <code>latSt</code>/<code>lngSt</code>. </td><td><code>9962.6826</code> or <code>null</code></td><td>18</td><td></td></tr><tr><td><code>toFinish</code> *</td><td>Distance [m] from <code>latSt</code>/<code>lngSt</code> along the shadowtrack to the end point of the track.</td><td><code>89097.3173</code> or <code>null</code></td><td>19</td><td></td></tr><tr><td><code>eta</code> *</td><td>Estimated time of arrival [s], duration to move from <code>latSt</code>/<code>lngSt</code> to the end point of the shadowtrack, extrapolation with <code>speed</code>.</td><td><code>16897.77</code> or <code>null</code></td><td>20</td><td></td></tr><tr><td><code>gapCalcTime</code> *</td><td><p>UTC timestamp for which <code>gapDistance</code>, <code>gap</code>, <code>gapChase</code> and <code>gapAverage</code> is obtained. Value is older (or equal) than <code>resultTime</code>. </p><div data-gb-custom-block data-tag="hint" data-style="info" class="hint hint-info"><p>Q: What is the latest UTC timestamp (at the specified <code>resultTime</code>) for which the API knows recorded geolocations?</p></div></td><td><code>"2022-01-24T16:32:30.012Z"</code> or  <code>null</code></td><td></td><td></td></tr><tr><td><code>gapDistance</code> *</td><td><p>Distance [m] between <code>latSt</code>/<code>lngSt</code> and the <code>toFinish</code> value of the leader.</p><div data-gb-custom-block data-tag="hint" data-style="info" class="hint hint-info"><p>Q: What is the current distance between chaser and leader?</p></div></td><td><code>null</code> or <code>3364.91</code> or <code>-554.03</code> if reference is behind device</td><td></td><td></td></tr><tr><td><code>gap</code> *</td><td><p>Duration [s] to move from <code>latSt</code>/<code>lngSt</code> along the shadowtrack to the <code>toFinish</code> value of the leader, calculated with the <code>speed</code> value of the leader. </p><p>If <code>speed of leader &#x3C; 1 km/h</code> than calculation with the default speed value of the event. </p></td><td><code>null</code> or <code>1205.68</code> or <code>-581.20</code>  if reference is behind device</td><td>23</td><td></td></tr><tr><td><code>gapChase</code> *</td><td><p>Duration [s] to move from <code>latSt</code>/<code>lngSt</code> along the shadowtrack to the <code>toFinish</code> value of the leader, calculated with the <code>speed</code> value of the chaser. </p><p>If <code>speed of chaser &#x3C; 1 km/h</code> than calculation with the default speed value of the event.</p></td><td><code>null</code> or <code>968.81</code> or <code>-73.02</code> if reference is behind device</td><td></td><td></td></tr><tr><td><code>gapAverage</code> *</td><td><p>Duration [s] to move from <code>latSt</code>/<code>lngSt</code> to the <code>toFinish</code> value of the leader, calculated with the timestamp of when the leader was at <code>latSt</code>/<code>lngSt</code>. </p><div data-gb-custom-block data-tag="hint" data-style="info" class="hint hint-info"><p>Q: How long did it take the leader to cover the distance <code>gapDistance</code>?</p></div></td><td><code>null</code> or <code>2360.36</code> or <code>-112.6</code> if reference is behind device</td><td></td><td></td></tr><tr><td></td><td> <strong><code>lngStEx</code>/<code>latStEx</code>:</strong> <br><a href="/pages/c4cBCt9aXT8vj2RRgUgs#what-is-mapping"><strong>Mapping</strong></a> <strong>of the latest recorded geolocation (<code>lat</code>/<code>lng</code>) on the shadowtrack (<code>lngSt</code>/<code>latSt</code>), further extrapolation on the track to the point in time of <code>resultTime</code> with the <code>speed</code> value.</strong></td><td></td><td></td><td></td></tr><tr><td><code>lngStEx</code> *</td><td>Longitude of the latest recorded geolocation mapped on the shadowtrack and extrapolated to <code>resultTime</code>.</td><td><code>5.2727</code> or <code>13.805551232</code> or <code>null</code> </td><td></td><td></td></tr><tr><td><code>latStEx</code> *</td><td>Latitude of the latest recorded geolocation mapped on the shadowtrack and extrapolated to <code>resultTime</code>.</td><td><code>50.93151590</code> or <code>null</code></td><td></td><td></td></tr><tr><td><code>fromStartEx</code> *</td><td>Distance [m] from the start point of shadowtrack along the track to <code>lngStEx</code>/<code>latStEx</code>.</td><td><code>9963.6826</code> or <code>null</code></td><td></td><td></td></tr><tr><td><code>toFinishEx</code> *</td><td>Distance [m] from <code>lngStEx</code>/<code>latStEx</code> along the shadowtrack to the end point of the track. </td><td><code>890967.3173</code> or <code>null</code></td><td></td><td></td></tr><tr><td><code>gapDistanceEx</code> *</td><td>Distance [m] from <code>lngStEx</code>/<code>latStEx</code> along the shadowtrack to reach the <code>toFinishEx</code> value of the leader.</td><td><code>null</code> or <code>3374.91</code> or <code>-564.03</code> if reference is behind device</td><td></td><td></td></tr><tr><td><code>gapEx</code> *</td><td><p>Duration [s] to move from <code>lngStEx</code>/<code>latStEx</code> along the shadowtrack to the <code>toFinishEx</code> value of the leader, calculated with the <code>speed</code> value of the leader. </p><p>If <code>speed of leader &#x3C; 1 km/h</code> than the default speed value of the event is used. </p><div data-gb-custom-block data-tag="hint" data-style="info" class="hint hint-info"><p>Q: How long does it take the leader to move backward with his current speed until he reaches the chaser's location?</p></div></td><td><code>null</code> or <code>1305.68</code> or <code>-591.20</code>  if reference is behind device</td><td></td><td></td></tr><tr><td><code>gapChaseEx</code> *</td><td><p>Duration [s] to move from <code>lngStEx</code>/<code>latStEx</code> along the shadowtrack to the <code>toFinishEx</code> value of the leader, calculated with the <code>speed</code> value of the chaser. </p><p>If <code>speed of device &#x3C; 1 km/h</code> than the default speed value of the event is used.</p><div data-gb-custom-block data-tag="hint" data-style="info" class="hint hint-info"><p>Q: How long does it take for the chaser with his current speed to reach the leader's location?</p></div></td><td><code>null</code> or <code>978.81</code> or <code>-93.02</code> if reference is behind device</td><td></td><td></td></tr><tr><td><code>gapAverageEx</code> *</td><td><p>Duration [s] to move from <code>lngStEx</code>/<code>latStEx</code> along the shadowtrack to the <code>toFinishEx</code> value of the leader, calculated with the timestamp of when the leader was at the same offset on the track. </p><div data-gb-custom-block data-tag="hint" data-style="info" class="hint hint-info"><p>Q: How long did it take the leader to cover the distance <code>gapDistanceEx</code>? </p></div></td><td><code>null</code> or <code>2560.36</code> or <code>-132.6</code> if reference is behind device</td><td></td><td></td></tr></tbody></table>

<table><thead><tr><th width="209.73335774739581">Field</th><th width="439.5999755859375">Description [unit]</th><th>Sample</th></tr></thead><tbody><tr><td><code>time</code></td><td>Timestamp in UTC of geolocation</td><td><code>"2022-01-24T16:33:47.012Z"</code></td></tr><tr><td><code>lng</code></td><td>Longitude of the participant</td><td><code>13.73032</code></td></tr><tr><td><code>lat</code></td><td>Latitude</td><td><code>51.00622</code></td></tr><tr><td><code>elv</code></td><td>Altitude above zero [m]</td><td><code>593</code></td></tr><tr><td><code>speed</code></td><td>Average speed [m/s]</td><td><code>5.2727</code></td></tr><tr><td><code>fromStart</code></td><td>Distance from first geolocation of shadowtrack along shadowtrack [m]</td><td><code>9962.6826</code></td></tr><tr><td><code>toFinish</code></td><td>Distance to last geolocation of shadowtrack along shadowtrack [m]</td><td><code>89097.3173</code></td></tr><tr><td><code>eta</code></td><td>Estimated time of arrival [s], time from now to reach last geolocation of shadowtrack, prediction with <code>speed</code></td><td><code>16897.77</code></td></tr></tbody></table>

#### Reads object

Does not provide all received detections of the participant. Provides only those reads, that have been validated by the prediction - accepted reads.

<table><thead><tr><th width="209.73323567708331">Field</th><th width="439.5999755859375">Description [unit]</th><th>Sample</th></tr></thead><tbody><tr><td><code>index</code></td><td>Index of the reader on the course, sequence according offset on the <a href="/pages/c4cBCt9aXT8vj2RRgUgs#shadowtrack">shadowtrack</a></td><td> <code>3</code> or <code>31</code></td></tr><tr><td><code>offset</code></td><td>Distance [m] on the <a href="https://docs.racemap.com/create-live-tracking/tab-map#shadowtrack">shadowtrack</a></td><td><code>49222.81</code></td></tr><tr><td><code>readerId</code></td><td>Unique ID of the reader, provided by timing system</td><td><code>"T-12056"</code></td></tr><tr><td><code>time</code></td><td>Timestamp in UTC of detection through timing system </td><td><code>"2022-03-09T14:59:38.201Z"</code></td></tr></tbody></table>

#### 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. &#x20;

<table><thead><tr><th width="209.73335774739581">Field</th><th width="439.5999755859375">Description [unit]</th><th>Sample</th></tr></thead><tbody><tr><td><code>id</code></td><td>Unique ID of the split point, generated in RACEMAP</td><td> <code>6450e60747adaed475b48</code></td></tr><tr><td><code>time</code></td><td>Timestamp in UTC of prediction: extrapolation or interpolation OR detection from timing system</td><td><code>"2022-03-09T14:59:38.201Z"</code></td></tr></tbody></table>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.racemap.com/api/unified.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.