# Getting started

Real-time geodata: Build applications for sports events such as maps, leaderboards, virtual races, and safety dashboards. Location data from many participants for your races' needs.

<figure><img src="/files/BsCHrMlejGIgmzz8PRkN" alt=""><figcaption><p>Easy creation of your own sports live tracking</p></figcaption></figure>

Participants and spectators don't need a RACEMAP account to join live tracking or to watch the race visualization. Only the host of the tracking service needs an account on our platform.

Create your free RACEMAP account to build live tracking for your sports events.

* Free trial for each event.
* Register in RACEMAP. We send an email to verify your email address.\
  [racemap.com/auth/register](https://racemap.com/auth/register)
* Login and create event live tracking.\
  [racemap.com/admin/events/new](https://racemap.com/admin/events/new)

{% hint style="success" %}
Get in touch with any questions. We explain, check, and adjust your settings.\
[racemap.com/#contact](https://racemap.com/#contact)

Subscribe to our updates and never miss a new feature.\
<https://updates.racemap.com/>

<img src="/files/SDJCEext3MOV1WzTTWRp" alt="" data-size="original">
{% endhint %}


# Quick start guide

Create an event, upload a race track, and show your location on the tracking map (in less than 5 minutes).

Your first login directs you to the event setup page: <https://racemap.com/admin/events/new>. Subsequent logins take you to the event list providing a tile for each of your events: <https://racemap.com/admin/events>.

{% embed url="<https://youtu.be/LhvflkpXygs>" %}

{% tabs %}
{% tab title="Event setup page" %}
To navigate to the events list click the RACEMAP logo in the top left corner.

<figure><img src="/files/jOxxycDFLh6FYymC19dE" alt=""><figcaption><p>Event setup page: Click RACEMAP logo to navigate to your events list</p></figcaption></figure>
{% endtab %}

{% tab title="Event list" %}
To navigate to the setup page of a specific event click the event tile.

<figure><img src="/files/rJDaQmEWhP4wR1mPnYmC" alt=""><figcaption><p>Event list: Click an event tile to navigate to the setup page</p></figcaption></figure>
{% endtab %}
{% endtabs %}

#### **Setup an event**

Start at the event setup page <https://racemap.com/admin/events/new>

* Provide basic event information: name, location, select type of sport, and event start- & end time.
* Upload event logo as a square \*.jpg or \*.png file. You can use our "Sample event logo.png".
* Upload a track as a \*gpx, \*.kml or \*.geojson file. You can use our "Sample Track.gpx".

{% file src="/files/aS7hnXJIB86azjCBr9zq" %}
Download the sample logo to use for your first event
{% endfile %}

{% file src="/files/6J8mOXCDGh8nQUaf9Otw" %}
Download the sample track to use for your first event
{% endfile %}

#### **Show and watch your location on your map**

Download RACEMAP App:

* [Google Play | Android](https://play.google.com/store/apps/details?id=racemap.de)
* [App Store | iOS](https://apps.apple.com/de/app/racemap/id640797527)

On the event setup page of your event, you find a QR code & a link. Scan the QR code or open the link on your phone to connect your RACEMAP App for live tracking at your event.

Read all about QR code & key link in our documentation.

{% content-ref url="/pages/-LXLDfyEEiuGO8RHSmWq" %}
[Keys and passcode](/apps/tracking/keys)
{% endcontent-ref %}

<figure><img src="/files/INgK46EuArfUCV0h6eTm" alt=""><figcaption><p>Find QR code and link on setup page of your event</p></figcaption></figure>

RACEMAP App guides you through the process.

{% tabs %}
{% tab title="Sign up" %}

<figure><img src="/files/ChxtXSukDG0aRiD3Yfin" alt=""><figcaption><p>"SIGN UP" with your name &#x26; race number</p></figcaption></figure>
{% endtab %}

{% tab title="Confirm" %}

<figure><img src="/files/7teB5yyNKut6RqDNag11" alt=""><figcaption><p>Confirm with "CONTINUE"</p></figcaption></figure>
{% endtab %}

{% tab title="Start live tracking" %}

<figure><img src="/files/9Kq7rIT7BLaxGrBqQnkG" alt=""><figcaption><p>Click "START LIVE TRACKING" to send your location</p></figcaption></figure>

* Search for your event's name.
* The event to which you are signed up is shown with a checkmark.
* Click on your event to open it and see your current location.
  {% endtab %}

{% tab title="Watch your dot" %}

<figure><img src="/files/z0he0tr6Aju7gmnfGLkd" alt=""><figcaption><p>See your current location on the map.</p></figcaption></figure>
{% endtab %}
{% endtabs %}

The map is centered around the uploaded track by default. Your location might differ from this track. Just pan the map a bit to see your current location.

Computer: Click "Preview" in the setup page to open the map in a browser tab.

<figure><img src="/files/J3ayq2wtbQlJPPhQhXuF" alt=""><figcaption></figcaption></figure>

Use an existing event as a template for a new one. Reusing settings while creating a clean copy, instead of starting from scratch.

**Two ways to create a copy from an existing event:**

<figure><img src="/files/NGwjyPVpny19nu2ciOu2" alt=""><figcaption></figcaption></figure>

* **Manual:** Open the template event in Advanced settings and click "Duplicate Tracking Map".
* **Direct link:** Navigate to `https://racemap.com/admin/events/`**`<event_id>`**`/actions/duplicate` — replace **`<event_id>`** with the ID of the event you want to copy.

Before the duplicate is created, you set the

* name and
* start and end times for the new event.

Choose independently whether to carry over:

* Devices / participants
* Track, POIs and splits information

<figure><img src="/files/m6DRqI08yXxMW0JkvdLc" alt=""><figcaption></figcaption></figure>


# Provide live tracking

Adapt real-time activity tracking to all kinds of sports events. Seamless GPS tracking for participants, spectators, and organizers. Optimized for mobile application.

### Explore live tracking features

Choose a topic to configure maps, scoring, embeds, or event operations.

<table data-view="cards"><thead><tr><th>Title</th><th data-card-target data-type="content-ref">Target</th><th data-hidden data-card-cover data-type="image">Cover image</th></tr></thead><tbody><tr><td>Event visualization</td><td><a href="/pages/-LXUVd-Pmy5sMONVdo3C">/pages/-LXUVd-Pmy5sMONVdo3C</a></td><td><a href="/files/9EAHYKSab0GxodMCYf3s">/files/9EAHYKSab0GxodMCYf3s</a></td></tr><tr><td>Group and stages</td><td><a href="/pages/-La0LBZ5LA9jbdZcJIXZ">/pages/-La0LBZ5LA9jbdZcJIXZ</a></td><td><a href="/files/rrHhAQ62jUFl2QGfXSvZ">/files/rrHhAQ62jUFl2QGfXSvZ</a></td></tr><tr><td>Safemap</td><td><a href="/pages/WFltfnWKsYMmIRNlNEaX">/pages/WFltfnWKsYMmIRNlNEaX</a></td><td><a href="/files/iFbyLTVkTUfax3i0bx3f">/files/iFbyLTVkTUfax3i0bx3f</a></td></tr><tr><td>Leaderboard</td><td><a href="/pages/-LYXfT2qbHHP6XDl9-g6">/pages/-LYXfT2qbHHP6XDl9-g6</a></td><td><a href="/files/3sJVTQlMEkYxhrqvculx">/files/3sJVTQlMEkYxhrqvculx</a></td></tr><tr><td>Embed interactive content</td><td><a href="/pages/-LSykVQ1qP1iotIaOCzf">/pages/-LSykVQ1qP1iotIaOCzf</a></td><td><a href="/files/yYgj4EBbGinz3cZ8sTy0">/files/yYgj4EBbGinz3cZ8sTy0</a></td></tr><tr><td>URL parameters</td><td><a href="/pages/rBoVsfgfgJFKOFBJ6wfa">/pages/rBoVsfgfgJFKOFBJ6wfa</a></td><td><a href="/files/xyqbu4O4qzOFpHgvPI1H">/files/xyqbu4O4qzOFpHgvPI1H</a></td></tr><tr><td>Elevation chart</td><td><a href="/pages/rShWWrRK0aXAnHO4Xnbg">/pages/rShWWrRK0aXAnHO4Xnbg</a></td><td><a href="/files/7RlcHdr4zcbi1ukJnr55">/files/7RlcHdr4zcbi1ukJnr55</a></td></tr><tr><td>Shadowtrack and mapping</td><td><a href="/pages/c4cBCt9aXT8vj2RRgUgs">/pages/c4cBCt9aXT8vj2RRgUgs</a></td><td><a href="/files/KC3FBlGA8DCn4Vy0Qm7z">/files/KC3FBlGA8DCn4Vy0Qm7z</a></td></tr><tr><td>Activity upload</td><td><a href="/pages/-M4xF32x9PizOpA8KNfE">/pages/-M4xF32x9PizOpA8KNfE</a></td><td><a href="/files/Y4TiA9e5l9EaMpERkWA4">/files/Y4TiA9e5l9EaMpERkWA4</a></td></tr></tbody></table>

{% hint style="warning" %}
**Recognizing unexpected or missing data in your map or leaderboard?** In rare cases after a platform update, your event's cached data may need a manual refresh. [Learn how to refresh your event data →](/live-tracking/refresh-event-data)
{% endhint %}


# Event visualization

Interactive map showing exciting information, live. Perfectly adapt the tracking map to your sports event and project.

The visualization of races and activities is optimized for mobile usage.

{% tabs %}
{% tab title="Filter tags" %}
![](/files/P6pohDqWni6VSlsyBXhb)
{% endtab %}

{% tab title="Leaderboard" %}
![](/files/yriTWlHhgLaZ7LEBnhxA)
{% endtab %}
{% endtabs %}

{% hint style="success" %}
Check the visualization of the 100km-Duathlon around Dresden:

**live sample** <https://racemap.com/player/100KmDuathlon2018_Repeat>

**past sample** (replay) [https://racemap.com/player/100KmDuathlon2018](https://racemap.com/player/100KmDuathlon2018#selected=61a20ea7e368e5ef4159283b,61a20ea7e368e52f49592680)
{% endhint %}

**Upscaling to the largest events:** The visualization is optimized for mobile devices broadcasting the largest sports events in real-time. Like predictive live tracking at München Marathon with 3,000+ participants in one interactive map <https://racemap.com/player/MuenchenMarathon21-marathon>

Or feed your own applications with real-time geodata using our APIs for live location data.

{% content-ref url="/pages/-LhnxBUqIeaJoZDskAT\_" %}
[Data APIs for live geodata](/api)
{% endcontent-ref %}

### Customizations

Interactive event map with different tracks & contests, start- & finish zone, and refresh points.

{% hint style="success" %}
Recap of Dresden Marathon, GPS tracking with Racemap App: [https://racemap.com/player/DresdenMarathon19](https://racemap.com/player/DresdenMarathon19#selected=5db025e74ec190621b33cedd,5db025ba0d916e820c5743d0\&events=0,1,2)
{% endhint %}

![](/files/-MKnXAuIultSVSm81RZc)

![flags showing race number (left) and the name (right)](/files/-Mk6FhRiT8vM0FARnM82)

* Color of tracks and of markers,
* Points of interest with names, [emojis](https://emojipedia.org/chequered-flag/) or choose a pictogram,
* Content in flags (bib respectively name)
* Multiple contests and stages.

**Points of interest (POI):** Are displayed and selectable in the map, in the sidebar, and in the elevation chart.

<table><thead><tr><th width="162">Parameter</th><th width="150">Map</th><th width="188.1123595505618">Sidebar</th><th>Elevation chart</th></tr></thead><tbody><tr><td>Pictogram</td><td>✔️</td><td>✔️</td><td>✔️</td></tr><tr><td>Color</td><td>✔️</td><td>✔️</td><td>✔️</td></tr><tr><td>Short name</td><td>✔️</td><td>✔️ five letters only</td><td>✔️ five letters only</td></tr><tr><td>Long name</td><td>️➖</td><td>✔️</td><td>➖</td></tr></tbody></table>

{% hint style="info" %}
If you configure a POI to show a pictogram, then color and short name are not shown for this POI.
{% endhint %}

![Design points of interest - select a pictogram or a color, short name (incl. emojis) and long name](/files/jUagjmnEM41DR9W1xoLU)

![Group: eight different race courses in one visualization](/files/NzGlBiXGYtqvShcXwy9U)

{% content-ref url="/pages/-La0LBZ5LA9jbdZcJIXZ" %}
[Group and stages](/live-tracking/multi-event-map)
{% endcontent-ref %}

**Viewport**: set the initial view of your tracking map spectators see when loading the map.

* Mapbox style e.g. terrain, satellite, hybrid, and dark, or choose custom map tiles
* Longitude and latitude of the center of the map,
* Zoom, direction, and pitch.

{% content-ref url="/pages/-MgCdPm\_YYZDZ\_N8Buff" %}
[External map layer](/tab-map/external-map-layer)
{% endcontent-ref %}

### Live, (net)replay & progress on track <a href="#live-replay-progress" id="live-replay-progress"></a>

Live and replay are shown in the same tracking map with one URL, providing a comprehensive visualization of the activities from many athletes. Full flexibility to stream different kinds of activities:

* geodata from everywhere (decentralized) and
* geodata from any time.

#### Instant replay

Instant replay during the running event: Skip back to watch early scenes of the race and go back to live stream. Exciting and useful information is easily accessible for the speaker, event staff, and spectators. Replay the recorded race in fast motion during and after the event.

![click and adjust the replay factor, slide back to early scenes of the competition](/files/HQ77TxpNqQtNsthyJ6j1)

#### Net replay

Net replay visualizes contests with differently starting athletes, such as wave start or virtual race. Synchronize the recorded activities to replay all athletes together. Net replay simulates that all participants are together at the same time.

![Participants from a two weeks event are synchronized to the start location](/files/-MLitguJ4ZsHTGfQs9cN)

#### **Progress on track**

Progress on track: Activities from everywhere are pinned to a specific track. That way the markers move on this track, virtually. Spectators understand easily who is heading and participants protect their personal data as their real locations are not visible.

![Activities from everywhere (left) displayed on one specific track (right)](/files/UCb5wjkKJ1ZbufvW0OTa)

{% hint style="success" %}
Two maps from the same geodata with decentral locations:

* Activity map showing the raw geodata <https://racemap.com/player/dam-tot-damloop-pin-track-10em_2020>
* Progress map on a virtual racetrack <https://racemap.com/player/dam-tot-damloop-home-edition-10em_2020>
  {% endhint %}

### Options pinning the dots to the shadowtrack

![Race recap: grey flag (001) moving on the track, white flag (006) lost the racecourse and comes back to the track 200 m behind 001](/files/bBWehdAZa5wowWIfcv8d)

There are three options pinning flags to the track. Each option affects how dots are moving in the interactive map. Watch the above scene with differently pinned flags to the track.

* **Magnetic (NEW)**: Within a 50 m distance from the track the flags are pinned to the track. Geodata with 50+ m distance is shown as raw coordinates. The grey flag moves smoothly through the curve (pinned to the track) and the white flag is shown beside the track (raw data).
* **None**: The visualization shows the coordinates as raw data. Disadvantage: Due to +/- 25 m accuracy of GPS devices, the locations don't precisely match the track and the grey flag cuts the curve.
* **Always**: The visualization always shows all coordinates on the track. For that reason, the grey flag moves smoothly through the curve. But the white flag is pinned to the track, also. It is not possible to see that the white flag lost track.

### Navigation of **participants and points of interest**

{% tabs %}
{% tab title="Search & select" %}
![search and select in tracking map](/files/5WeVtNEqO62CEYFssgYP)
{% endtab %}

{% tab title="Hover" %}
![hover participantsnts & POIs in the list, elevation provile and in the map](/files/-MfcLKO672JiOCqwI_9I)
{% endtab %}

{% tab title="Filter" %}
![filter participants in the visualization](/files/wJs2LM1vQyI8xVHjwgFT)
{% endtab %}
{% endtabs %}

* Filter and search participants and points of interest.
* An arrow moves on the track while hovering over the elevation profile.
* Selected participants are highlighted as a flag and the visualization centers automatically.
* Select respectively hover athletes and points of interest in the list, in the map, and in the elevation profile.

The **tail** feature shows the recorded activity of a selected participant. The length of the tail corresponds to the set duration. Purple tails for selected participants: [https://racemap.com/player/dam-tot-damloop-home-edition-10em\_2020](https://racemap.com/player/dam-tot-damloop-home-edition-10em_2020#selected=5f6b407642e62339d5c3de58,5f6b407942e6231b58c3e18b,5f6b407942e623c94bc3e0ce,5f6b407a42e6236575c3e25c)

![](/files/-MUNeIrBf78IjzMzxm3D)

Spectators can display the race numbers of all participants in settings (can be set as default in event builder, also).

!["show all flags"-option in player settings](/files/-MbpGPMXKXzkZduhHLnZ)

### Info tab, elevation, flow chart, statistics & leaderboard

{% tabs %}
{% tab title="Info" %}
![useful information about the event](/files/zAo8GEWMAcHIDAd1X0Yj)
{% endtab %}

{% tab title="Elevation" %}
![interactive elevation chart with points of interest, up to 1,000 dots](/files/dPLfc8yKl4Z7uQjQ3OLk)

![or use the elevation chart as 1D progress line](/files/4O6ElRcyrQxvLrupzKMT)

{% hint style="info" %}
This feature requires a configured exactly one shadowtrack
{% endhint %}
{% endtab %}

{% tab title="Race flow" %}
![overtaken in a diagram](/files/NuKtK8yglrudoGUyS0eL)
{% endtab %}

{% tab title="Statistics" %}
![distance (gap) and duration of selected participants](/files/u3G4B5mPClleyWwZoucS)

real-time statistics for each participant:

* distance to go and duration to finish (prediction),
* accumulated ascent & decent,
* distance from start,
* speed - (If there is a shadowtrack speed value based on mapping on the [shadowtrack](/live-tracking/shadowtrack) or average speed value of the ten latest received locations.),
* gap.

{% hint style="info" %}
This feature requires exactly one configured shadowtrack
{% endhint %}
{% endtab %}

{% tab title="Leaderboard" %}
![If the leaderboard is activated the visualization provides real-time scoring and results.](/files/E0aoCkdsh0L9BnbhJ4pI)

{% content-ref url="/pages/-LYXfT2qbHHP6XDl9-g6" %}
[Leaderboard](/live-tracking/gps-timing)
{% endcontent-ref %}
{% endtab %}
{% endtabs %}

### Own location, distance marker & sponsor logo

**Own location** shows the location of your device in the tracking map, which is helpful for spectators and event staff at the race ground. Own location is visible on your device only and is not sent to our server.

![](/files/-MTog5jSAFwv3-P-oPWo)

![Dynamic markers display the distance on the shadowtrack depending on zoom.](/files/-MWdeRJQTZ2-7QgQ0EKx)

If the **sponsor logo** is activated you can show a square logo and refer to the sponsor's website.

![](/files/-LW1h2eKV3ut5-vtaeSY)

The slider shows either the duration of the event or the time of the day in two moveable scales. The foreground represents the total duration of the event from start to end to quickly slide through the total event. The scale above shows a section of the total event duration. Zoom this scale to show 5min or 2hr depending on how accurate you want to place the time in the visualization.

![two scales slider optimized for mobile usage](/files/3Flsdv7kNecOT2xYaI7Q)

![](/files/2zrFcR0ag4QpecTMwarC)

![](/files/xRxFPaoAmMKR9ngUldwF)

![upcoming events show a countdown until start time of event](/files/vDPyvLg25cHeuAkIklUz)


# Group and stages

Group and stages unite multiple single events in one interactive map.

![Multiple tracks in one visualization](/files/NzGlBiXGYtqvShcXwy9U)

| Description   | Group                                                                 | Stages                                                                                  |
| ------------- | --------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
| use case      | combine several contests                                              | unite all stages of one event                                                           |
| participation | athlete joins one contest                                             | athlete joins all stages one by another                                                 |
| participants  | each contest with different participants                              | all stages with identical participants                                                  |
| keys          | one key working for one contest                                       | one key working for all stages                                                          |
| sequence      | contests may overlap, single events active at the same time, normally | stages active one by another, not at the same time, normally                            |
| sample event  | Solo Run Jena                                                         | DYNAFIT TRAIL RUN3 - 7 stages                                                           |
| visualization | <https://racemap.com/player/SoloRunJena21#events=0,1,2,3,4,5,6,7>     | <https://racemap.com/player/dynafit-transalpine-run-powered-by-volkswagen-r_2021-08-07> |

The group- or stages map displays the information of the selected event(s), only:

* marker of participants,
* race course(s),
* points of interest and
* duration.

{% tabs %}
{% tab title="Desktop" %}
![select multiple contests or stages in the map, directly](/files/-MkfPllAc0c70QeVJ_F8)
{% endtab %}

{% tab title="Racemap App" %}
![select a contest or a stage one by another](/files/-MkfRm33-BM4MXfWAVt8)
{% endtab %}
{% endtabs %}

URLs and auto-selection of specific single events

* A group- or a stages event has a specific URL ("group URL"):\
  <https://racemap.com/player/tortour-ultra-cycling_2021-06-22>
* Every single event in the group (or in stages) has a specific URL, also:\
  <https://racemap.com/player/tortour-ultracycling-challenge_2021-08-20>
* Through the group URL, specific single events can be preselected:\
  <https://racemap.com/player/tortour-ultra-cycling_2021-06-22#events=1>\
  <https://racemap.com/player/tortour-ultra-cycling_2021-06-22#events=0,1>

On desktop applications, the group URL selects specific single events, automatically:

{% tabs %}
{% tab title="during the event" %}
The group URL selects all running (live) single events. Past or upcoming events are not selected.
{% endtab %}

{% tab title="after the event" %}
The group URL selects the 1st single event in group settings.

![](/files/-MkgqqoOhgulTpDmHkC_)
{% endtab %}
{% endtabs %}


# Safemap

Safemap consolidates critical information for long-distance events in a single dashboard. Operations teams supervise participants in real-time, identify risk situations & coordinate response actions.

{% hint style="success" %}
Explore the live demo (24/7) in the browser:\
<https://racemap.com/safemap/demo>
{% endhint %}

Create your Safemap in your RACEMAP account here:\
<https://racemap.com/admin/safemaps/new>

{% tabs %}
{% tab title="Create Safemap" %}
{% embed url="<https://youtu.be/MOFVxXIO-Ps?si=t01P2lQQZPUZvaM8>" %}
Video demonstrates how to create the safety dashboard and run Safemap in a command center
{% endembed %}
{% endtab %}

{% tab title="Optimized Settings" %}
{% embed url="<https://youtu.be/lsJSE_zBk74?si=zdtJpihyI33uA-i2>" %}
Video shows the options to improve Safemap set-up and reduce noise from unintentional notifications
{% endembed %}
{% endtab %}

{% tab title="Command Centre Workflow" %}
{% embed url="<https://youtu.be/JEJh6gcoqiU?si=KWag63F20psc9Y06>" %}
Video shows Safemap as part of the safety management at endurance cycling races of Race Across Series
{% endembed %}
{% endtab %}
{% endtabs %}

## Key capabilities of Safemap

<figure><img src="/files/criviykdecFRTE8GMV5v" alt=""><figcaption><p><strong>Intuitive elements in Safemap:</strong> <a href="#participants-navigation">Participants navigation</a>, <a href="#map">map</a>, <a href="#alerts-and-notifications-1">alerts &#x26; notifications</a> stream, <a href="#chart-and-info-panel">chart &#x26; info panel</a></p></figcaption></figure>

<table><thead><tr><th width="199.666748046875" valign="top">Feature</th><th valign="top">What it does</th><th valign="top">Why it matters</th></tr></thead><tbody><tr><td valign="top"><a href="#participants-navigation"><strong>Participants navigation</strong></a></td><td valign="top">searches, selects &#x26; filters relevant participants across Safemap</td><td valign="top">Quick access to participant-specific data and fast workflow</td></tr><tr><td valign="top"><a href="#map"><strong>Map</strong></a></td><td valign="top">Shows participants' latest locations, highlights alerts &#x26; notifications</td><td valign="top">Full situational awareness for operators team at a glance</td></tr><tr><td valign="top"><a href="#alerts-and-notifications"><strong>Alerts</strong></a></td><td valign="top">SOS &#x26; crash</td><td valign="top">Comprehensive risk overview</td></tr><tr><td valign="top"><a href="#alerts-and-notifications"><strong>Notifications</strong></a></td><td valign="top">Lost track, no movement, low battery &#x26; power-off</td><td valign="top">Awareness of potentially critical situations without manual monitoring</td></tr><tr><td valign="top"><strong>Collaboration team</strong></td><td valign="top">Browser-based <a href="/pages/Dd9jkqg6mYRH0qtIE1X0">access for distributed or rotating teams</a></td><td valign="top">Enables traceable actions, multiple operators working simultaneously</td></tr><tr><td valign="top"><strong>Alert workflow</strong></td><td valign="top">Assignment ⇒ Resolution of alerts &#x26; notifications</td><td valign="top">Ensures accountability &#x26; structured incident response</td></tr><tr><td valign="top"><strong>Protected zone</strong></td><td valign="top">Configurable areas, suppress alerts e.g. at aid station</td><td valign="top">Reduces noise and focuses attention on real risks</td></tr><tr><td valign="top"><a href="#chart-and-info-panel"><strong>Chart</strong></a></td><td valign="top">Timeline visualization of all received information for one selected participant</td><td valign="top">Helps analyze performance and behavior</td></tr><tr><td valign="top"><a href="#chart-and-info-panel"><strong>Info panel</strong></a></td><td valign="top">Current information for one selected participant</td><td valign="top">Shows summary of latest information at a glance</td></tr></tbody></table>

#### Use case

{% hint style="warning" %}
Safemap is not a public [event visualization application](/live-tracking/map). Safemap is a decision-support system for safety management, helping monitoring teams to act quickly, confidently, and responsibly.
{% endhint %}

Typical event types: ultra-trail, long-distance running, endurance cycling, triathlon, motocross, rally, and equestrian sports. Safemap is built for operators who manage endurance races where:

* The **course is long-distance and remote**.
* **Automated supervision** is required, often **across multiple days**.
* There is an elevated **risk level**, making **participant safety** mission-critical.

#### Characteristics

* **Reliable data:** Each participant needs to carry a GPS tracker.
* **Comprehensive data:** The dashboard continuously collects, displays & stores objective geodata & additional reports without getting tired.
* **Browser-based application:** Safemap runs in the browser, providing an intuitive interface — no installation or coding required.
* **Operators logging:** Teams use Safemap through their individual RACEMAP accounts, taken actions are logged in the dashboard.

#### Recommendations on GPS trackers

The reliability of Safemap depends on the geodata & additional reports received from the connected GPS trackers. The below instructions ensure the best possible and most accurate monitoring & dependable safety operations:

{% hint style="warning" %}

* **Use GL3xx series trackers:** We recommend using [Queclink GL3xx GPS devices](/gps-devices/config/remote). These tracker models are fully integrated with RACEMAP and can be enabled for additional reports - SOS, crash detection, power-off, (no) movement state, low battery & charging.
* **Set correct configuration:** Configure the GL3xx devices through the [Tracker Management](/tracker-management) to enable sending additional reports. Safemap can process SOS, crash, ect., only when we receive additional reports.
* **Manage devices remotely:** GPS trackers must be added to [Tracker Management](/tracker-management) to process parameters such as connection state and battery level, and for remote adjustment of settings.

The use of [RACEMAP tracking app](/apps) for Safemap is discouraged. Apps depend on user behavior - installation, charging, and activation of live tracking - which introduces uncertainties not suitable for Safemap's monitoring purpose.
{% endhint %}

## **Interactive elements in Safemap**

### **Participants navigation**

Use the filter to quickly display only the participants or devices that meet specific criteria, helping you focus on relevant or actionable information. Sorting lets you order the list—by name, bib number, device name, battery, last location, etc.—to surface the most important participants first.

<figure><img src="/files/sXAeg7V1PSgX2DMZczpH" alt="" width="563"><figcaption><p>Participant navigation with comprehend filter- &#x26; search options</p></figcaption></figure>

<table><thead><tr><th width="349.8629726832467" valign="top">Parameter</th><th valign="top">Description</th></tr></thead><tbody><tr><td valign="top">Race number and name</td><td valign="top">Import from <a href="/pages/-M3ehZR5FRb3OtNJtvds">participant list</a></td></tr><tr><td valign="top">Device name</td><td valign="top">Import from <a href="/pages/-LT3ehO2UEcTbOBZOJF0">Tracker Management</a></td></tr><tr><td valign="top">Status <img src="/files/McnDBQVCrU95Jk9WefP6" alt="" data-size="line">:<br><mark style="background-color:green;">On track</mark> or<br><mark style="background-color:red;">Lost track</mark></td><td valign="top">Coordinate's distance from the <a href="/pages/c4cBCt9aXT8vj2RRgUgs">shadowtrack</a><br><mark style="background-color:green;">&#x3C; <code>threshold distance</code></mark> or<br><mark style="background-color:red;">> <code>threshold distance</code></mark></td></tr><tr><td valign="top">Status <img src="/files/STurRWYZnVONKTn9gv9B" alt="" data-size="line">:<br><mark style="background-color:green;">Movement</mark> or<br><mark style="background-color:red;">No movement</mark></td><td valign="top">According movement status reported from device or based on geo data: Average speed for <code>threshold duration</code><br><mark style="background-color:green;">> 1 km/h</mark> or<br><mark style="background-color:red;">&#x3C; 1 km/h</mark> or <mark style="background-color:red;">no location received</mark></td></tr><tr><td valign="top">Indicator:<br>Open notification</td><td valign="top"><img src="/files/EUy7YqrZalINj7j1CirN" alt="" data-size="original"></td></tr><tr><td valign="top">Indicator:<br>Open alert</td><td valign="top"><img src="/files/CVCsJ3FFx9YYdBbnf7bA" alt="" data-size="original"></td></tr><tr><td valign="top">Status <img src="/files/UUNbjZdJDOa3OExfuk0T" alt="" data-size="original">:<br>Online or<br>Offline</td><td valign="top">Shows if server has an open socket with GPS tracker</td></tr><tr><td valign="top">Autonomy:<br>Battery level [%] and<br>Charging indicator</td><td valign="top"><img src="/files/quHuXHkrWgI1Zr82sLs7" alt="" data-size="original"></td></tr><tr><td valign="top">Progress:<br>Distance [km] and progress bar</td><td valign="top"><img src="/files/iSXLLe16aQKfPxQwyKW6" alt="" data-size="original"></td></tr><tr><td valign="top">Last location: Duration since receiving the last coordinate, hover for details</td><td valign="top"><br><img src="/files/TQvrgX8kB5fecRLVKE73" alt="" data-size="original"></td></tr><tr><td valign="top">Status:<br>DNF, DSQ, DNS, FIN</td><td valign="top">Import from <a href="/pages/-M3ehZR5FRb3OtNJtvds">participant list</a>, to filter participants accordingly</td></tr></tbody></table>

### Map

The map displays location-based information and provides a visual overview of participants' latest positions with their alerts and notifications.

{% hint style="info" %}
**No replay:** The map always shows the latest information; playback or speed replay is not provided.
{% endhint %}

<figure><img src="/files/YqMLVpXCptgBNEMWpLUM" alt=""><figcaption><p>The map shows protected zones (<mark style="background-color:red;">red square</mark>), shadowtrack (<mark style="background-color:blue;">blue line</mark>), raw coordinates of selected participant (<mark style="background-color:red;">red tail</mark>), selected participant flag, and open alerts &#x26; notifications</p></figcaption></figure>

Map includes the following elements:

* [**Shadowtrack**](/live-tracking/shadowtrack)**:** Visualizes the race course as a blue line.
* **Participant dot:** Shows the latest received coordinate of each participant.
* **Participant flag:** Highlights the selected participant with a flag displaying the bib number. The associated raw coordinate tail shows all received raw positions from that device without post-processing.
* **Active alerts & notifications:** Displays the locations of the open alerts & notifications for the selected participant.
* **Protected zones:** Indicates defined areas where certain notifications (e.g., no movement) are intentionally suppressed to avoid unnecessary attention at places like aid or rest stations.

### **Alerts and notifications**

Safemap processes alerts and notifications to support structured safety operations. The alert workflow supports [**collaboration across teams and shifts**](/live-tracking/share-access) through browser-based access. Multiple operators—whether in a central control room or distributed across locations—can work simultaneously during multi-day events. User accounts ensure clear role allocation & traceability.

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

<figure><img src="/files/1B7XvsRFyp5MxmaCHHdc" alt="" width="563"><figcaption></figcaption></figure>
{% endtab %}

{% tab title="Notifications" %}

<figure><img src="/files/IJlmVtxVq3beAdVgPCeO" alt="" width="563"><figcaption></figcaption></figure>
{% endtab %}

{% tab title="Pushes in map" %}

<figure><img src="/files/X1ZIVtlTFdDBfLtpG4nC" alt="" width="563"><figcaption><p>New alert/ notification is pushed, start point for audit trail and further supervision for possible risks</p></figcaption></figure>
{% endtab %}
{% endtabs %}

<table><thead><tr><th width="200.1396248712333">Alert</th><th width="540.0570990393579">Description</th></tr></thead><tbody><tr><td>Crash*</td><td>GPS tracker, auto-detection</td></tr><tr><td>SOS*</td><td>SOS button on GPS tracker pressed</td></tr></tbody></table>

<table><thead><tr><th width="200.45666702812608">Notification</th><th width="255.39053409795167">Description</th><th>Auto-resolve</th></tr></thead><tbody><tr><td>Lost track</td><td>Coordinate's distance from the <a href="/pages/c4cBCt9aXT8vj2RRgUgs#shadowtrack">shadowtrack</a><br>> <code>threshold distance</code></td><td>Optional; if coordinate's distance from the shadowtrack<br><code>&#x3C; threshold distance</code></td></tr><tr><td>No movement [GEN]</td><td>Coordinates' average speed for <code>threshold duration</code><br>&#x3C; 1 km/h</td><td>Optional; if coordinates' average speed for <code>threshold duration</code><br>> 1 km/h</td></tr><tr><td>No movement*</td><td>Movement status from device indicates no movement.</td><td>Optional, movement status from device indicates no movement.</td></tr><tr><td>Battery*</td><td>Battery level &#x3C; 20 %</td><td>-</td></tr><tr><td>Power off*</td><td>Either power button uses manually or device shuts down due to low battery</td><td></td></tr></tbody></table>

\*Trackers send specific information only when the corresponding [device reports](#recommendations-on-gps-trackers) are enabled.

#### What is an alert?

An alert/notification includes the following parameters:

* Type of the alert,
* Affected participant/device,
* Location, where the alert was recorded,
* Timestamp, when the alert was recorded,
* Timestamp, when Safemap received the alert (may differ due to network delays),
* Alert state: <mark style="background-color:red;">**Open**</mark> (New) ⇒ <mark style="background-color:$info;">**In progress**</mark> ⇒ (<mark style="background-color:yellow;">**Standby**</mark> ⇒) <mark style="background-color:green;">**Resolved**</mark>.

#### Alert workflow

Safemap enforces an alert workflow to ensure accountability:

* New alerts appear as <mark style="background-color:red;">**Open**</mark>.
* When an alert is assigned to an operator, its state changes <mark style="background-color:red;">**Open**</mark> => <mark style="background-color:$info;">**In progress**</mark>.
* The responsible operator can set an alert as <mark style="background-color:yellow;">**Standby**</mark>.
* When risk analysis is finished, the alert can finally set as <mark style="background-color:green;">**Resolved**</mark>.
* Every change of the alert state is logged with timestamp, creating a complete audit trail for incident handling and reporting.
* You can add recipients' email address to automatically receive alert emails (SOS & crash).
* The audio signal for new alerts can be muted for the alerts- & notifications streams separately.

  <figure><img src="/files/kGvcEkiLVJu3vWIqO1GW" alt=""><figcaption><p>Muted alerts &#x26; notifications</p></figcaption></figure>

#### Protected zone

Safemap supports protected zones to reduce notification noise and keep the monitoring team focused on relevant safety issues. A protected zone is a defined area—configured by name, location, and size—in which selected alert types are automatically suppressed.

Protected zones are useful at locations where stops are expected, such as rest stations, refreshment areas, or transition zones. For example, "No movement" notifications can be muted within these areas to prevent unnecessary attention.

Create protected zones in the Safemap settings by using splits or points of interest. Safemap applies the suppression rules automatically for any device inside the zone.

<figure><img src="/files/5ISh3Ghy3JoKC7pZp06z" alt="" width="563"><figcaption><p>Configuration of protected zones in the Safemap settings</p></figcaption></figure>

### Chart and info panel

The chart & info panel provide detailed insights into a selected participant or device, combining a timeline of historical data and live status information. Supports analysis of participant behavior, performance, and potential safety issues.

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

<figure><img src="/files/QFFtuIrU7ggVVJJaTahi" alt=""><figcaption><p><mark style="background-color:blue;">Distance</mark> to the shadowtrack &#x26; <mark style="background-color:green;">speed</mark> over time</p></figcaption></figure>
{% endtab %}

{% tab title="Info panel" %}

<figure><img src="/files/TXbRjcfB43qUs1khzlhj" alt=""><figcaption></figcaption></figure>
{% endtab %}
{% endtabs %}

**Chart:** Visualizes the timeline of all received data for the selected participant.

* Speed
* Distance from the shadowtrack (deviation from the planned course)
* Alerts/notifications, positioned at the timestamp they were recorded

**Info panel:** Provides a summary of the latest information at a glance, such as last position, connection status, battery level, and active alerts or notifications.

<figure><img src="/files/ukwvwtg2eW9k5A2ZJ4lz" alt=""><figcaption><p>Clear context: Same notifications in the chart and in the map</p></figcaption></figure>


# Leaderboard

Effortless live rank & real-time scoring. Results from geofences & participants' GPS data. No complex timing hardware for splits. For intermediate timing points, decentral races & permanent timing.

![Interactive leaderboard from real-time geolocations; switch contests & stages, optimized for mobile usage](/files/JOLkDtyCizEt7l6vmvzn)

**Samples:**

* Live sample, 100km-Duathlon around Dresden, one team starts every minute\
  <https://edge.racemap.com/timing/100KmDuathlon2018_Repeat>
* Past sample, SoloRunJena, six-month permanent race, participants join the challenge over an extended period <https://edge.racemap.com/timing/lobdeburg_2021>
* Past sample, Damloop Home Edition with 2,000+ participants, 24-hour virtual race, participants contribute activities from everywhere <https://edge.racemap.com/timing/dam-tot-damloop-home-edition-10em_2020>

### Features and advantages of GPS timing

**Scales to the largest events** with 5,000+ participants.

**Effortless results**: With virtual splits or checkpoints and with geo data of participants, no need for complex timing hardware and RFID tags.

**Flexible splits**: Adjust settings (add a new checkpoint, move start split, etc.) of a live event or even of a past event, and refresh results with new parameters within seconds.

**Live scoring:** Data is processed in real-time, and results are available right away.

**Proof of activities**: Athletes contribute their activities using any device.

* [Racemap Tracking App](https://racemap.com/apps)
* [GPS live trackers](https://docs.racemap.com/hardware-for-live-tracking)
* [Upload recorded activities](https://docs.racemap.com/how-to-use-live-tracking/activity-upload) from fitness trackers and wearables after the activity

{% hint style="success" %}
Join the decentral, permanent race "Easy QR Code Run" (passcode 6G615L).

* Leaderboard: <https://racemap.com/timing/qrcode-test>
* Tracking map: <https://racemap.com/player/qrcode-test>

You can either contribute your recorded activity [racemap.com/upload?key=6G615L](https://racemap.com/upload?key=6G615L) or you can connect Racemap App for live tracking of this event:

* Press the link <https://racemap.app/redeem_key?key=6G615L> or
* Scan the QR code (the QR code is equal to the above link)\ <img src="/files/HrjvV95YDNCn7DtCOAyx" alt="" data-size="original">
  {% endhint %}

#### Data APIs with timestamps

Query Racemap Data APIs to retrieve geofence passings for use in your applications, such as processing timestamps within your timing software. This integration allows for seamless transfer of event-related data.

{% tabs %}
{% tab title="\*/times API " %}
Raw data: All detections at geofences.

{% content-ref url="/pages/-MZHS89A2\_1gjjvVpUfO" %}
[\*/times, reads and raw data](/api/times)
{% endcontent-ref %}
{% endtab %}

{% tab title="\*/ranks API" %}
Results: Data from a specific leaderboard.

{% content-ref url="/pages/-MZHQpwp749Eg0tOuYuX" %}
[\*/ranks, ranking and results](/api/ranks)
{% endcontent-ref %}
{% endtab %}
{% endtabs %}

#### Integrate 3rd party result lists

Embed 3rd party results such as RACE|RESULT instead of showing a Racemap leaderboard.\
Sample: [https://racemap.com/player/sample-integrated-results](https://racemap.com/player/sample-integrated-results#color=C41011)

![](/files/1aL1pYvH1U3QFEnvzmOU)

### Information in the leaderboard

#### Columns in the result list

* (Live)rank,
* Race number,
* Name and
* Finish- and split results.
* Filter tags such as Status: DNF, DNS, DSQ or Class: Men, Mixed, Woman, Orga\
  Disable specific tags to hide associated devices—for example, exclude Orga from the leaderboard.<br>

  <figure><img src="/files/UDmkbAc9INnAF7VzAwBz" alt=""><figcaption></figcaption></figure>

#### Customize the leaderboard and select elements

* <img src="/files/-M8eDL5Mjc41wa0L70cU" alt="" data-size="line"> Progress with current distance,
* <img src="/files/-MUDnAQe60g4vXqO3cUU" alt="" data-size="line"> Link to tracking map with the selected participant,
* <img src="/files/-MM-vTsmoeRUl28YxIbR" alt="" data-size="line"> Live status shows if a participant is currently active.
* <img src="/files/3apkkgOFNTw0oAyo6aRI" alt="" data-size="line"> or <img src="/files/MXaXd1Xa1OEEZ3WD56z3" alt="" data-size="line"> Select split name, distance, and icon (or nothing) for the column's head.
* Active duration: The time within the start- and end time of an event when the device transmits coordinates and exceeds a speed of 1 km/h.
* Rest duration: The time during an event when the device sends location data and moves at a speed less than 1 km/h.
* Team challenge where participants collectively aim to achieve a set distance across all contributed activities, e.g. <https://racemap.com/timing/virtual-race>\ <img src="/files/-MYzYpOalK7LhYtgpa4w" alt="" data-size="original">

#### Settings

Open the settings in the leaderboard with the <img src="/files/AOxzqo7CcHOdM8rizTbX" alt="" data-size="line">-button.

![](/files/GK4DFtboJlqZKXFp04Ke)

* Start times: Opens an extra column with the timestamp when the start geofence was crossed. Showing the start time is useful for permanent timing events.
* Delta times: The duration measured from the previous split, as opposed to the time difference from the event's start.
* Online participant: If our system receives live data from a specific participant. For running events only.
* Upload activity: For participants to import recorded activities afterward.

#### Filter categories

Open filter options in the leaderboard with the <img src="/files/DlUtRfrYhvcIOTxjAZbI" alt="" data-size="line">-button. The categories are defined with `tags` in the participant data.

{% content-ref url="/pages/-M3ehZR5FRb3OtNJtvds" %}
[Import participant data](/api-import-and-export-data)
{% endcontent-ref %}

![Filter participants and show the ranks per each category](/files/PkPs1kuB1qjIhHLHQpu6)

### Flexible application

#### Comparison of activities

Assessing and contrasting activities is not bound by time or location restrictions. The leaderboard dynamically compares location data based on the event settings, considering geofences and participant location data to provide flexible results.

{% tabs %}
{% tab title="Anytime" %}
Two scenarios:

* Regular event: Participants start nearly simultaneously.
* Virtual race or permanent timing: Participants start at various times.
  {% endtab %}

{% tab title="Everywhere" %}
Two scenarios:

* Regular event: Participants follow a defined race course, moving from the start point to the finish line.
* Virtual race: Participants provide activities from any location, without the constraints of a specific race course.
  {% endtab %}
  {% endtabs %}

#### Leaderboard geodata processing

* Net results: Time difference from the timestamp at the start geofence
* Auto-update of the leaderboard every ten seconds
* Results of one second accuracy

<table><thead><tr><th width="157.33333333333331">Feature</th><th>Participants move on given track</th><th>Without race track (virtual race)</th></tr></thead><tbody><tr><td>Mapping of geolocations</td><td>Projection of device locations on the shadowtrack within <em>Max Mapping Distance</em>, according to <em>Min-</em> and <em>Max Speed Filter</em> (advanced event settings)</td><td>-</td></tr><tr><td>Detection of start split</td><td><strong>A:</strong> LAST coordinate at the start split during the event<br><strong>B:</strong> MISSING coordinates at start: speed from 1st ten coordinates following the start, extrapolation back for determination of the timestamp of start passing<br><strong>C:</strong> MISSING coordinates at start: provide start timestamp<br>c1 <code>First Time</code> in <a href="/pages/-M3ehZR5FRb3OtNJtvds">participant list</a> of event<br>c2 <code>startTime</code> in <a href="/pages/-MBKork_GNvfGpnpwShV">CSV import</a><br>c3 <code>times.start</code> in <a href="/pages/-LTq5TdE6GKt2S6dgesz">generic import</a></td><td>FIRST coordinate during the event</td></tr><tr><td>Detection of intermediate splits</td><td>Linear interpolation between the two closest mapped geolocations</td><td>Device covers the distance of corresponding split</td></tr><tr><td>Detection of finish split</td><td><strong>A:</strong> FIRST geolocation at the coordinate of finish split<br><strong>B:</strong> MISSING coordinates at finish: provide finish timestamp<br>b1 <code>Last Time</code> in <a href="/pages/-M3ehZR5FRb3OtNJtvds">participant list</a> of event<br>b2 <code>endTime</code> in <a href="/pages/-MBKork_GNvfGpnpwShV">CSV import</a><br>b3 <code>times.end</code> in <a href="/pages/-LTq5TdE6GKt2S6dgesz">generic import</a></td><td>Device covers distance of finish</td></tr><tr><td>Target</td><td>Distance = length of shadowtrack (needed duration is calculated)</td><td>Distance (duration is calculated) OR duration (achieved distance is calculated)</td></tr><tr><td>Speed filters</td><td>-</td><td>Segments that do not fit <em>Min-</em> and <em>Max Speed Filter</em> are not considered</td></tr><tr><td>Segmentation</td><td>No segmentation: participants provide activities from the start to the finish geofence following the shadowtrack</td><td><strong>A:</strong> Participants contribute multiple activities to accumulate the total activity (Monday workout + Wednesday training etc.)<br><strong>B:</strong> With keys: sum up activities (Racemap App + upload) to an aggregated activity<br><strong>C:</strong> If the aggregated activity > target, detection of finish from the fastest segment corresponding to the set target<br><strong>D:</strong> Breaks without geolocations (duration &#x26; distance between two locations) are ignored eg. stop recording activity or rest between two activities</td></tr></tbody></table>

### Accuracy

Comparison of the leaderboard solution and a professional timing solution at the [100km-Duathlon](http://100km-duathlon.de/), extensive [description of this project in our blog](https://racemap.com/blog/transponder-timing-powers-gps-tracking).

* R[esults of GPS timing](https://racemap.com/timing/100km-duathlon_2018-05-05) corresponding to data of GPS Live Trackers
* P[rofessional scoring](https://my.raceresult.com/96221/?lang=de#1_438FA5) corresponding to active transponders

The comparison shows:

* The leaderboard provides results from geolocations and virtual splits with low effort, no timekeeping system is needed.
* The same scoring with leaderboard and with professional timing solution.
* Accuracy depending on tracking interval of GPS device, deviation < 1 min.

### Best practice

#### Leaderboard for an event with a given route

**Prevent unintentional start- and finish reads:** If participants wait before starting their race and the GPS device already sends locations close to the start geofence, then the "start" detection can be triggered too early. To prevent unintentional reads of start and finish just move the location of the start split 100 m following the shadowtrack (100 m behind real start area). Finish split: 100 m upfront the real finish area.

**Combining RFID timing data with intermediate geofences:** To enhance long-distance event timing as for ultra trails or rallies, you can combine precise start and finish detections with extensive flexible splits. Integrate start- and finish times from the timing system into a comprehensive leaderboard, including intermediate splits at geofences. Learn how to import start and finish reads from your timekeeping system:

* [Using Racemap import](https://docs.racemap.com/api-import-and-export-data/import-basics/metadata-api)
* [With CSV upload](https://docs.racemap.com/api-import-and-export-data/import-data-from-csv)
* [Using RACE|RESULT simple API](https://docs.racemap.com/api-import-and-export-data/import-basics/metadata-import-via-rr)

#### Leaderboard for a virtual race without a given race course

Comparison of activities for an event without a given racetrack like a virtual race or an activity challenge:

* Leaderboard <https://racemap.com/timing/virtual-race>
* Activity map from raw geodata <https://racemap.com/player/virtual-race>
* Map showing the progress virtually on a track (from the same location data): <https://racemap.com/player/virtual-race-pin-on-track>

Participants contribute their exercises at any time and from everywhere. Provide a leaderboard comparing the individual workouts of every participant and a tracking map showing the current location or progress.


# Embed interactive content

Embed the event visualization, tracking map, live ranks and leaderboard directly on your pages with an iFrame.

## Unique URL

Each event has a unique URL for the tracking map and leaderboard. You can access these applications also by replacing `<slug>` with the corresponding `eventId`. This approach allows for automatically generated, stable URLs that remain functional even if the `<slug>` changes.

* Tracking map\
  `https://racemap.com/player/<slug>`

  <https://racemap.com/player/100KmDuathlon2018>\
  <https://racemap.com/player/61a2055b10cacc0001302283>
* Leaderboard\
  `https://racemap.com/timing/<slug>`

  <https://racemap.com/timing/100KmDuathlon2018>\
  <https://racemap.com/timing/61a2055b10cacc0001302283>

RACEMAP provides two dynamically generated pages for key-based access, also.

* Activity upload\
  `https://racemap.com/upload?key=<key>`\
  <https://racemap.com/upload?key=6G615L>
* Key link to enroll key (or passcode)\
  `https://racemap.com/app/redeem_key?key=<key>`\
  <https://racemap.com/app/redeem_key?key=6G615L>

## iFrame integration

Easily embed live tracking, leaderboards and live rankings on any webpage using an iFrame. This allows you to display interactive content directly on your site, keeping visitors engaged without redirecting them to external pages. By embedding these applications, you provide a seamless user experience while maintaining full control over your website’s navigation and branding.

{% code title="Embedded tracking map" overflow="wrap" lineNumbers="true" %}

```html
<iframe src="https://racemap.com/player/100KmDuathlon2018" style="width: 100%; height: 800px"></iframe>
```

{% endcode %}

{% code title="Tracking map embedded with options" overflow="wrap" lineNumbers="true" %}

```html
<iframe src="https://racemap.com/player/100KmDuathlon2018" style="width: 100%; height: 800px; border: solid 2px rgb(90, 90, 90); border-radius : 10px; box-shadow: 0 0 25px rgb(112, 139, 161)" allow="geolocation 'src'" loading="lazy" allowfullscreen webkitallowfullscreen mozallowfullscreen></iframe>
```

{% endcode %}

{% hint style="success" %}
Samples with the above html-code:

* Embedded tracking map: <https://racemap.com/embed-samples#iframe>
* Tracking map embedded with options: <https://racemap.com/embed-samples#shadow>
  {% endhint %}

<table><thead><tr><th width="417">Attribute</th><th width="294">Description</th><th data-hidden>Parameter</th></tr></thead><tbody><tr><td><code>style="width: 100%"</code></td><td>width ratio of the embedded content</td><td><code>style</code></td></tr><tr><td><code>style="height: 800px"</code></td><td>height of the embedded content</td><td><code>style</code></td></tr><tr><td><code>style="border: solid 2px rgb(90, 90, 90)"</code><br><br><code>style="border: none"</code></td><td>strength and color of border line</td><td><code>style</code></td></tr><tr><td><code>style="border-radius: 10px"</code></td><td>rounded edges</td><td><code>style</code></td></tr><tr><td><code>style="box-shadow: 0 0 10px rgb(112, 139, 161)"</code></td><td>strength and color of shadow</td><td><code>style</code></td></tr><tr><td><code>allow="geolocation 'src'"</code></td><td>resource allowed to use geolocation interface to enable the "show own location"-feature of tracking map</td><td><code>allow</code></td></tr><tr><td><code>loading="lazy"</code></td><td>resource loaded only on need</td><td><code>loading</code></td></tr><tr><td><code>allowfullscreen webkitallowfullscreen mozallowfullscreen</code></td><td>to open the embedded tracking map fullscreen</td><td></td></tr></tbody></table>

#### **Leaderboard**

<https://racemap.com/timing/virtual-race>\
sample: <https://racemap.com/embed-samples#leaderboard>

{% code overflow="wrap" lineNumbers="true" %}

```xml
<iframe src="https://racemap.com/timing/virtual-race" style="width: 100%; height: 800px; border: none; box-shadow: 0 0 10px rgb(112, 139, 161)" loading="lazy" allowfullscreen webkitallowfullscreen mozallowfullscreen></iframe>
```

{% endcode %}

#### **Activity upload**

<https://racemap.com/upload?key=6G615L>\
sample: <https://racemap.com/embed-samples#upload>

{% code overflow="wrap" lineNumbers="true" %}

```html
<iframe src="https://racemap.com/upload?key=6G615L" style="width: 100%; height: 1150px; border: none; box-shadow: 0 0 10px rgb(112, 139, 161)" allowfullscreen webkitallowfullscreen mozallowfullscreen></iframe>
```

{% endcode %}

#### **Key link**

<https://racemap.com/app/redeem_key?key=6G615L>\
sample: <https://racemap.com/embed-samples#key-link>

{% code overflow="wrap" lineNumbers="true" %}

```html
<iframe src="https://racemap.com/app/redeem_key?key=6G615L" style="width: 100%; height: 1100px; border: none; box-shadow: 0 0 10px rgb(112, 139, 161)" loading="lazy" allowfullscreen webkitallowfullscreen mozallowfullscreen></iframe>
```

{% endcode %}


# URL parameters

Use dynamic URL parameters to address and control specific features of the tracking map.

Use URL parameters to automatically compose various URLs of the same tracking map fitting different use cases.

* URL parameters overwrite the default settings of the tracking map.
* (\*) URL parameters are removed from the URL after the map is loaded, while the other parameters remain in the URL.
* Combine different parameters with `&` `flagContent=NAME&showAllFlags=true&mapStyle=DARK&flagContent=TWO_LETTER_NAMES`\
  [https://racemap.com/player/100KmDuathlon2018#flagContent=NAME<mark style="color:red;">&</mark>showAllFlags=true<mark style="color:red;">&</mark>mapStyle=DARK<mark style="color:red;">&</mark>flagContent=TWO\_LETTER\_NAMES](https://racemap.com/player/100KmDuathlon2018#flagContent=NAME\&showAllFlags=true\&mapStyle=DARK\&flagContent=TWO_LETTER_NAMES)

#### Custom color

Select a custom color as the premiere color of the tracking map as a hex code.\
parameter: `color=<your_color>`

* black: <https://racemap.com/player/100KmDuathlon2018#color=000000>
* green: <https://racemap.com/player/100KmDuathlon2018#color=66cd00>
* red: <https://racemap.com/player/100KmDuathlon2018#color=cc0000>

sample: <https://racemap.com/embed-samples#color>

#### Select participants, POIs, and tracks

The tracking map automatically centers around selected elements.

1\. parameter: `selected=<participantId>,<trackId>,<poiId>`

URL to follow the teams "Flaming Sideburns" and "Wolfsrudel Mädels" at 100km-Duathlon: <https://racemap.com/player/100KmDuathlon2018#selected=632c5f966d78779bc8e66ac6,632c5f976d78777a56e66d38>

sample: <https://racemap.com/embed-samples#select>

2\. parameter: `selectedStartNumber=<startNumber>`

URL to follow the teams "Flaming Sideburns" and "Wolfsrudel Mädels" with the bib number 001 and 053 at 100km-Duathlon: <https://racemap.com/player/100KmDuathlon2018#selectedStartNumber=001,053>

#### Set filters

Set the tracking map with filters. Use the `none` argument to hide participants with DNS, DSQ, and DNF status.

parameter: `filter=<tag-1>:<value-12>,<tag3:value-1>`

URL with filter tags age "20" and nationality "GER":\
<https://racemap.com/player/MuenchenMarathon21-marathon#filter=age:20,nationality:GER>

sample: <https://racemap.com/embed-samples#filter>

#### Time of event \*

The tracking map loads at a specific time of the event. The time is required in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format.

parameter: `time=yyyy-mm-ddThh:mm:ssZ`

URL starts the replay at 9:45:35 UTC time, at Mai 5th 2018:\
[https://racemap.com/player/100KmDuathlon2018#time=2018-05-05T09:46:35Z](https://racemap.com/player/100KmDuathlon2018#time=2018-05-05T09:46:35Z\&selected=632c5f976d787758a9e66d40)

sample: <https://racemap.com/embed-samples#time>

#### Map style \*

* Satellite:\
  `mapStyle=SATELLITE`\
  <https://racemap.com/player/100KmDuathlon2018#mapStyle=SATELLITE>
* Terrain:\
  `mapStyle=TERRAIN`\
  <https://racemap.com/player/100KmDuathlon2018#mapStyle=TERRAIN>
* Hybrid:\
  `mapStyle=HYBRID`\
  <https://racemap.com/player/100KmDuathlon2018#mapStyle=HYBRID>
* Roadmap:\
  `mapStyle=ROADMAP`\
  <https://racemap.com/player/100KmDuathlon2018#mapStyle=ROADMAP>
* Dark:\
  `mapStyle=DARK`\
  <https://racemap.com/player/100KmDuathlon2018#mapStyle=DARK>

#### Show or hide navigation bar \*

* Open list:\
  `listOpen=true`\
  <https://racemap.com/player/100KmDuathlon2018#listOpen=true>
* Close list:\
  `listOpen=false`\
  <https://racemap.com/player/100KmDuathlon2018#listOpen=false>

#### Show flags or dots of all participants \*

* Show all flags:\
  `showAllFlags=true`\
  <https://racemap.com/player/100KmDuathlon2018#showAllFlags=true>
* Show all dots:\
  `showAllFlags=false`\
  <https://racemap.com/player/100KmDuathlon2018#showAllFlags=false>

#### Set flag content \*

The set flag content parameter applies only on the shown flags. It does not show all flags automatically.

* Race number:\
  `flagContent=STARTNUMBER`\
  <https://racemap.com/player/100KmDuathlon2018#flagContent=STARTNUMBER&showAllFlags=true>
* Name of participant:\
  `flagContent=NAME`\
  <https://racemap.com/player/100KmDuathlon2018#flagContent=NAME&showAllFlags=true>
* Race number and name of participant:\
  `flagContent=STARTNUMBER_AND_NAME`\
  <https://racemap.com/player/100KmDuathlon2018#flagContent=STARTNUMBER_AND_NAME&showAllFlags=true>
* Race number and the two first letters of the first and the last name eg. 012KoTr:\
  `flagContent=TWO_LETTER_NAMES`\
  <https://racemap.com/player/100KmDuathlon2018#flagContent=TWO_LETTER_NAMES&showAllFlags=true>
* Race number and the first letter of the first and the last name eg. 012KT:\
  `flagContent=ONE_LETTER_NAMES`\
  <https://racemap.com/player/100KmDuathlon2018#flagContent=ONE_LETTER_NAMES&showAllFlags=true>

#### Select flag content \*

The select flag content parameter applies only on the selected `<participantId>`. It does not show all flags automatically.

* Race number:\
  `selectedFlagContent=STARTNUMBER`\
  <https://racemap.com/player/100KmDuathlon2018#selected=632c5f966d787712f2e66ada&selectedFlagContent=STARTNUMBER>
* Name of participant:\
  `selectedFlagContent=NAME`\
  <https://racemap.com/player/100KmDuathlon2018#selected=632c5f966d787712f2e66ada&selectedFlagContent=NAME>
* Name of participant:\
  `selectedFlagContent=STARTNUMBER_AND_NAME`\
  <https://racemap.com/player/100KmDuathlon2018#selected=632c5f966d787712f2e66ada&selectedFlagContent=STARTNUMBER_AND_NAME>
* Race number and 1st letter of participant's name:\
  `selectedFlagContent=ONE_LETTER_NAMES`\
  <https://racemap.com/player/100KmDuathlon2018#selected=632c5f966d787712f2e66ada&selectedFlagContent=ONE_LETTER_NAMES>
* Race number and 1st & 2nd letter of participant's name:\
  `selectedFlagContent=TWO_LETTER_NAMES`\
  <https://racemap.com/player/100KmDuathlon2018#selected=632c5f966d787712f2e66ada&selectedFlagContent=TWO_LETTER_NAMES>

#### Hide non-selected participants \*

Hide all participants' dots or flags that are not selected:

`hideNonSelected=true` <https://racemap.com/player/100KmDuathlon2018#selected=632c5f966d787712f2e66ada&selectedFlagContent=TWO_LETTER_NAMES&hideNonSelected=true>

#### Increase marker size \*

Presenter mode: Show dots, flags, and POIs with large marker dimensions eg. when showing the tracking map on a LED screen or for the production of TV overlays.

`largeMode=true`\
<https://racemap.com/player/100KmDuathlon2018#largeMode=true>

#### Show or hide tabs section \*

Info tabs can be elevation chart, event info, race statistics, etc.

* Open info tabs:\
  `infoTabs.OpenByDefault=true`\
  <https://racemap.com/player/100KmDuathlon2018#infoTabs.openByDefault=true>
* Close info tabs:\
  `infoTabs.OpenByDefault=false`\
  <https://racemap.com/player/100KmDuathlon2018#infoTabs.openByDefault=false>

#### Set default tab \*

Set the default tab in the info section.

* Event info:\
  `infoTabs.defaultTab=INFO`\
  <https://racemap.com/player/100KmDuathlon2018#infoTabs.defaultTab=INFO>
* Elevation chart:\
  `infoTabs.defaultTab=ELEVATION`\
  <https://racemap.com/player/100KmDuathlon2018#infoTabs.defaultTab=ELEVATION>
* Leaderboard:\
  `infoTabs.defaultTab=TIMING`\
  <https://racemap.com/player/100KmDuathlon2018#infoTabs.defaultTab=TIMING>
* Race statistics:\
  `infoTabs.defaultTab=STATS`\
  <https://racemap.com/player/100KmDuathlon2018#infoTabs.defaultTab=STATS>
* Race flow:\
  `infoTabs.defaultTab=FLOW`\
  <https://racemap.com/player/100KmDuathlon2018#infoTabs.defaultTab=FLOW>

#### Disable tabs \*

Disable specific info tabs in the info section, comma separated.

* `infoTabs.DisabledTabs=INFO,ELEVATION,TIMING,FLOW,STATS`\
  <https://racemap.com/player/100KmDuathlon2018#infoTabs.disabledTabs=INFO,ELEVATION,TIMING,FLOW,STATS>

#### Set zoom level \*

Set the default zoom level of the tracking map, according to the mapbox zoom scale (<https://docs.mapbox.com/help/glossary/zoom-level/>).

* `zoom=9`\
  <https://racemap.com/player/100KmDuathlon2018#zoom=9>


# Organize participants with tags

Attach flexible category/value tags to participants to filter, group, and segment them across the tracking map, leaderboard, and Safemap.

A tag attaches a `category: value` label to a participant, for example `club: Team A`, `wave: 2`, `nationality: GER`, or `status: DNF`. A participant can carry several tags at once, one value per category.

* Filter the tracking map and leaderboard by category and value.
* Group participants in the player sidebar, e.g. by wave or club.
* Show tag values as columns in the leaderboard.
* Suppress Safemap alerts for participants matching a tag, e.g. `Status: DNF`.

### Filter the tracking map

Spectators filter the starter list by tag category and value, narrowing down to the participants they care about.

{% hint style="info" %}
Participants without a value in a category are grouped under an implicit "none" option when filtering.
{% endhint %}

The current filter selection can also be set directly via URL, useful for pre-filtered links or embeds.

parameter: `filter=<tag-1>:<value-1>,<tag-2>:<value-2>`

URL with filter tags age "20" and nationality "GER": <https://racemap.com/player/MuenchenMarathon21-marathon#filter=age:20,nationality:GER>

{% content-ref url="/pages/rBoVsfgfgJFKOFBJ6wfa" %}
[URL parameters](/live-tracking/url-parameters)
{% endcontent-ref %}

### Group participants in the sidebar

Group the player's participant list by a tag category, e.g. by wave or club, so spectators find related participants at a glance instead of scrolling a flat list.

{% content-ref url="/pages/-LXUVd-Pmy5sMONVdo3C" %}
[Event visualization](/live-tracking/map)
{% endcontent-ref %}

### Filter categories in the leaderboard

Tag values also drive filter categories and columns in the leaderboard. Disable specific tag values to hide them from the leaderboard, e.g. exclude an "Orga" class.

{% content-ref url="/pages/-LYXfT2qbHHP6XDl9-g6" %}
[Leaderboard](/live-tracking/gps-timing)
{% endcontent-ref %}

### Suppress alerts in Safemap

In Safemap, protected zones suppress alerts by location. Tags work alongside that: filter participants by tag in the participant navigation, for example to focus on a `Amateur` group or exclude an `Status: DNF` tag from monitoring.

{% content-ref url="/pages/WFltfnWKsYMmIRNlNEaX" %}
[Safemap](/live-tracking/safemap)
{% endcontent-ref %}

## Configure how tags appear

For each tag category, configure in the event's Visualisation settings:

* **Visible as filter** — show or hide the category as a filter option for spectators.
* **Group starters by** — use this category to group the participant list in the sidebar.
* **Default filter values** — pre-select values when the tracking map loads.
* **Order** — the display order of categories relative to each other.

## The `status` tag category

One tag category is special: `status` (also recognized when named `state`). Use it to mark a participant's race status — the suggested values are `DNF`, `DNS`, `DSQ`, and `FIN`.

* Safemap shows a colored badge for each value and, by default, only lists participants **without** a status in the Starters and Alerts lists — adjust the "Participant Status" filter to see DNF/DNS/DSQ/FIN participants too.
* The leaderboard excludes `DNF`, `DNS`, and `DSQ` from ranking — they show a dash instead of a rank, and `DSQ` rows are dimmed. `FIN` does not affect ranking.
* When editing the `status` column in the participant list, `DNF`, `DNS`, `DSQ`, and `FIN` are suggested automatically.

{% hint style="info" %}
Use exactly these uppercase values so Safemap and the leaderboard recognize them. Any other value in the `status` category is treated like a normal tag.
{% endhint %}

## How to add tags

There are three ways to get tags onto participants: manually, via CSV import, or via automatic sync.

### Manually

Manage tags directly in the participant list of your event, under Participants.

* Edit a tag value inline, cell by cell, for a single participant.
* Add a new tag category as a column.
* Set a tag value on several selected participants at once.
* Remove a tag category from selected participants.
* View the distribution of tag categories and values across all participants.

### CSV import

Add a `tags.<category>` column for each tag category to your participant CSV file, e.g. `tags.club;tags.wave`. Each cell holds the value for that participant.

{% content-ref url="/pages/-MBKork\_GNvfGpnpwShV" %}
[Import with CSV file](/api-import-and-export-data/import-data-from-csv)
{% endcontent-ref %}

### Automatic sync

Connect a generic hosted data source or a RACE RESULT list to keep participants and their tags synchronized automatically. The source provides `tags.<category>` fields (or a `tags` object) per participant; the sync picks them up on every run.

You can also restrict the sync to a single tag category and only import participants with matching values.

{% content-ref url="/pages/-LTq5TdE6GKt2S6dgesz" %}
[Generic import](/api-import-and-export-data/import-basics/metadata-api)
{% endcontent-ref %}

{% content-ref url="/pages/-LTh-oAm96bieBZVeffZ" %}
[RACE RESULT import](/api-import-and-export-data/import-basics/metadata-import-via-rr)
{% endcontent-ref %}

## Related pages

{% content-ref url="/pages/-MBKork\_GNvfGpnpwShV" %}
[Import with CSV file](/api-import-and-export-data/import-data-from-csv)
{% endcontent-ref %}

{% content-ref url="/pages/-LTq5TdE6GKt2S6dgesz" %}
[Generic import](/api-import-and-export-data/import-basics/metadata-api)
{% endcontent-ref %}

{% content-ref url="/pages/-LXUVd-Pmy5sMONVdo3C" %}
[Event visualization](/live-tracking/map)
{% endcontent-ref %}

{% content-ref url="/pages/-LYXfT2qbHHP6XDl9-g6" %}
[Leaderboard](/live-tracking/gps-timing)
{% endcontent-ref %}

{% content-ref url="/pages/rBoVsfgfgJFKOFBJ6wfa" %}
[URL parameters](/live-tracking/url-parameters)
{% endcontent-ref %}

{% content-ref url="/pages/-M\_zgpFYgo28IJBo4zVF" %}
[\*/starters, athlete data](/api/participants)
{% endcontent-ref %}


# Elevation chart

Query and display the race elevation chart as a standalone component. Customize the interactive profile and control its appearance and behavior via URL parameters.

The interactive elevation chart for sports live tracking shows the real-time progress of all participants along the course. It visualizes the elevation profile, athlete positions, and highlights Points of Interest. It is similar to the elevation profile used in the [event visualization](/live-tracking/map#elevation), but can be customized through URL parameters to control its behavior and appearance.

The component can be [embedded into web pages](/live-tracking/iframe) or integrated into third-party applications such as custom dashboards or video production workflows, providing a clear overview of the race and the current participant positions.

#### Endpoint

To access the elevation chart for a specific event, use the component’s dedicated URL. The URL follows the same structure as the player URL. For example, to view the 100km Duathlon, use the following link:

{% hint style="info" %}
<https://racemap.com/elevation-chart/100KmDuathlon2018/>

You can also use the `eventId` of your event:

<https://racemap.com/elevation-chart/61a2055b10cacc0001302283/>
{% endhint %}

#### Mandatory prerequisites

* The event has to have exactly one configured [shadowtrack](/live-tracking/shadowtrack)
* The shadowtrack covers the whole distance including all loops of the race

Also: How to setup a [shadowtrack](https://docs.racemap.com/tab-map) or how the [elevation profile](https://docs.racemap.com/live-tracking/map) is used in the player

#### URL parameters

Customize the behavior and style of the elevation chart with URL parameters. Change the color, hide axes & grid, or filter the participants.

{% hint style="info" %}
[https://racemap.com/elevation-chart/100KmDuathlon2018/<mark style="color:$danger;">**#**</mark>selected=632c5f966d78779bc8e66ac6<mark style="color:$danger;">**&**</mark>color=aabbaa<mark style="color:$danger;">**&**</mark>elevation.showProgress=true](https://racemap.com/elevation-chart/100KmDuathlon2018/#selected=632c5f966d78779bc8e66ac6\&color=aabbaa\&elevation.showProgress=true)
{% endhint %}

<table><thead><tr><th>Name</th><th width="213.5">Key</th><th width="220.666748046875">Type</th><th>Default</th></tr></thead><tbody><tr><td>Color</td><td><code>color</code></td><td><a href="https://racemap.com/elevation-chart/100KmDuathlon2018/#color=aabcd4">hex color (without #)</a></td><td>36739a</td></tr><tr><td>Select participants</td><td><code>selected</code></td><td><a href="https://racemap.com/elevation-chart/100KmDuathlon2018/#selected=632c5f966d78774197e66cd9">id</a></td><td>-</td></tr><tr><td>Select participants</td><td><code>selectedStartNumber</code></td><td><a href="https://racemap.com/elevation-chart/100KmDuathlon2018/#selectedStartNumber=043">bib</a></td><td>-</td></tr><tr><td>Progress</td><td><code>elevation.showProgress</code></td><td><a href="https://racemap.com/elevation-chart/100KmDuathlon2018/#selected=632c5f966d78774197e66cd9&#x26;elevation.showProgress=true">boolean</a></td><td>false</td></tr><tr><td>Grid</td><td><code>elevation.showGrid</code></td><td><a href="https://racemap.com/elevation-chart/100KmDuathlon2018/#elevation.showGrid=false">boolean</a></td><td>true</td></tr><tr><td>Axis</td><td><code>elevation.showAxis</code></td><td><a href="https://racemap.com/elevation-chart/100KmDuathlon2018/#elevation.showAxis=false">boolean</a></td><td>true</td></tr><tr><td>POIs</td><td><code>elevation.showPOI</code></td><td><a href="https://racemap.com/elevation-chart/100KmDuathlon2018/#elevation.showPOI=false">boolean</a></td><td>true</td></tr><tr><td>Time</td><td><code>time</code></td><td><a href="https://racemap.com/elevation-chart/100KmDuathlon2018/#time=2018-05-05T09:46:35Z">ISO datetime</a></td><td>-</td></tr><tr><td>Filter</td><td><code>filter</code></td><td><a href="https://racemap.com/elevation-chart/100KmDuathlon2018/#filter=Status:DSQ">tag class:tag value</a></td><td>-</td></tr></tbody></table>


# Shadowtrack and mapping

The mapping feature calculates the relation of the device's coordinates to the shadowtrack.

#### Shadowtrack

The shadowtrack enables calculations and features for the [visualization of the race](/live-tracking/map), such as elevation chart, statistics, distance marker, and split points - [predictive tracking](/prediction), and add-ons such as the [leaderboard](/live-tracking/gps-timing) and [Safemap](/live-tracking/safemap).

Only one track can be set as the shadowtrack of an event. This track represents the route on which participants move from the start to the finish. The length of this track has to be the same length as the contest.

* The length of the shadowtrack for a marathon is 42.195 km.
* If participants have to run three laps, then the shadowtrack must consider three laps, too.
* The shadowtrack for a triathlon includes swimming, cycling, and running in one continuous line.
* Required by [elevation chart](/live-tracking/profile) endpoint

#### What is mapping?

Mapping continuously projects a device's coordinates onto the shadow track, calculating metrics such as distance traveled, distance remaining, and inter-participant gaps, which power features such as:

* [Player](/live-tracking/map)
* [Elevation chart](https://docs.racemap.com/how-to-use-live-tracking/basic-features-of-racemap-tracking-map#info-tab-elevation-flow-chart-statistics-and-leaderboard)
* [Leaderboard](/live-tracking/gps-timing)
* [Safemap](/live-tracking/safemap)
* [Ranks API](/api/ranks)
* [Current API](/api/current)

{% hint style="success" %}

* Mapping does not affect [predictive tracking](/prediction).
* A device may appear at the right geographic location on the map while still being mapped to the wrong point on the shadowtrack - for example, causing incorrect `fromStart` or `toFinish` values in current API.
* To verify correct mapping, check the elevation profile: if the dots are shown at the right positions along the profile, the devices are mapped correctly.
* Sample: When **"Max mapping distance"** parameter is set with a very large value (e.g. 10,000 m), the algorithm selects the first point on the shadowtrack within the allowed mapping distance. This point will have a low **fromStart** value, and the mapped position is placed too early on the route, causing the marker in the elevation profile to appear at a shorter distance than the participant's actual location.
  {% endhint %}

#### How does mapping work?

* GPS devices send their coordinates to the tracking map. Mapping automatically calculates their most likely position on the shadowtrack.
* Mapping can begin at any point on the shadowtrack. The device's first coordinate during the event must not necessarily be mapped to the start point of the track, as it is mapped to its closest position on the track.
* Mapping takes into account the device's latest coordinate and its previous position on the track.
* Mapping considers laps and assumes that a device moves onward (and never backward) on the track.
* In the "advanced" settings, you can set the parameters to filter the device's coordinates for the mapping.

<figure><img src="/files/H8KllapDzX9oTYMyrqii" alt=""><figcaption></figcaption></figure>

* **Max mapping distance (in meters):** Maximum distance of devices coordinates from the shadowtrack. Coordinates with a greater distance from the shadowtrack are not considered for the mapping.
* **Max speed for speedfilter:** Maximum speed to consider the devices coordinates for the mapping on the shadowtrack. Coordinates that would need a greater speed are not considered for the mapping.
* **Min speed for speedfilter:** Minimum speed to consider the devices coordinates for the mapping on the shadowtrack. Coordinates that would need a lower speed are not considered for the mapping.

#### Best practise

If the shadowtrack's start and finish points are very close, the device's first coordinates during the event can be mapped to the finish instead of the start. This misassignment distorts the elevation chart, leaderboard, and other derived data. To avoid this wrong start mapping, keep the shadowtrack's start and finish points at least 200 m apart and ensure the device's first coordinates are located close to the start.


# Managing Access

Control who can access your events, trackers, and account — from per-event editor permissions to multi-account structures

### Add editors to specific events

Working for multiple events in parallel involves a team. To collaborate across multiple RACEMAP accounts, you can grant your teammates access to edit the event.

Follow these steps to share access:

1. Each teammate has a RACEMAP account.
2. Create the event from your account.
3. Navigate to **Advanced > Manage Access** in the event settings.
4. Under the **Add** **Editors** section, type your teammate’s username and select it from the list.

This setup lets you efficiently manage events across teams, while keeping access secure and organized.

<figure><img src="/files/M6WbgjaFvJE4WSjefaCI" alt=""><figcaption><p>Select a teammate to collaborate on your events.</p></figcaption></figure>

### Child accounts

Organizations that operate RACEMAP through multiple accounts can consolidate them under one main account using the child account structure.

* One **main account** oversees all associated child accounts
* Child accounts operate independently — they set up and run events on their own
* The main account has full read/edit access to all events and settings across every child account
* Child accounts **cannot access** each other's events
* Child accounts **do not see pricing** — billing is handled entirely at the main account level
* The main account receives **one consolidated invoice** that sums up usage across all child accounts

This setup is designed for companies managing teams, franchises, or white-label operations — where central billing and oversight matter, but day-to-day event management stays distributed.

To link accounts, the main account sends a request to <info@racemap.com> naming the account to be added as child.

{% hint style="info" %}
**Tracker Management:** Share access to your GPS trackers for other RACEMAP accounts e.g. when you rent the trackers. [User access to devices](/tracker-management/user-role)
{% endhint %}


# Activity upload

Upload GPX, KML and TCX files to submit individually recorded activities from any fitness tracker.

{% hint style="success" %}
upload activity: [racemap.com/upload](https://racemap.com/upload)
{% endhint %}

Athletes using a sports tracker or wearables such as Garmin, Polar, Suunto can submit activities to an event and import their individually recorded geolocation data. Supported formats are GPX, KML and TCX. The activity is visible in the replay of the tracking map and in the leaderboard, afterward.

* Participants redeem the passcode or a key to addressing their activity to a specific event.
  * **Key** to upload multiple activities and accumulate a total activity.
  * **Passcode** to upload one activity and generate a new entry.

{% content-ref url="/pages/-LXLDfyEEiuGO8RHSmWq" %}
[Keys and passcode](/apps/tracking/keys)
{% endcontent-ref %}

* Format of upload URL with passcode or with key `https://racemap.com/upload?key=XXXXXX`. With the passcode 6G615L the corresponding link is [racemap.com/upload?key=6G615L](https://racemap.com/upload?key=6G615L).
* Timestamps of imported activity must be within start- & end time of the event. Data outside of the time frame is excluded.
* Speed filter: If the speed is too high - like 60 km/h for a running event - these geolocations are ignored in the leaderboard. If a participant forgets to stop recording the activity while going by car, this segment is ignored, automatically.

{% hint style="info" %}
[More about processing geolocation data](https://docs.racemap.com/how-to-use-live-tracking/gps-timing#processing-geolocation-data-in-leaderboard)
{% endhint %}

{% hint style="success" %}
**Test event for uploading activities:** "Easy QR Code Run" with passcode 6G615L

* passcode 6G615L in the upload link [racemap.com/upload?key=6G615L](https://racemap.com/upload?key=6G615L)
* tracking map: [racemap.com/player/qrcode-test](https://racemap.com/player/qrcode-test)
* leaderboard: [racemap.com/timing/qrcode-test](https://racemap.com/timing/qrcode-test)
  {% endhint %}

{% hint style="info" %}
Add individual parameters `startNumber` and `name` for each participant in the address `http://racemap.com/upload/?key=KEY&startNumber=STARTNUMBER&name=NAME`. That way participants don't have to type their name and bib number when uploading activities. Sample <http://racemap.com/upload/?key=6G615L&startNumber=1&name=Peter>.
{% endhint %}


# Refreshing event data

Racemap pre-calculates and caches a lot of event data — participant positions, rankings, split times — so that maps and APIs can serve thousands of viewers at once without delay.

In rare cases, after a platform update that changes *how* data is calculated (for example, which participants appear on the map, or how rankings are sorted), your event's cached data may not refresh automatically. This can make it look like something is broken — participants missing from the map, wrong order on the leaderboard, unexpected API responses — even though your event settings are perfectly correct.

{% hint style="info" %}
This is uncommon but can happen after a Racemap platform update. The good news: it is always fixable in seconds, without contacting support.
{% endhint %}

### How to tell if this is the issue

Look at the **"saved X ago"** timestamp displayed below the event name in the top-left corner of the event editor. If the timestamp is many hours or days old and something in your map or leaderboard looks off, a stale cache is a likely cause — especially if the issue appeared after a recent Racemap update.

### The fix: trigger a re-save

Any change to your event settings causes Racemap to fully recalculate and refresh the cached data. The safest approach is a tiny, reversible change to the end time:

1. Open your event in [Racemap](https://racemap.com)
2. Go to **Essentials → Basic**
3. Add one second to the end time (e.g. `14:00:00` → `14:00:01`)
4. Click **Save**
5. Reload your tracking map or leaderboard

The data should now reflect the latest platform logic. You can then set the end time back to its original value if needed — that save will also keep the data fresh.

{% hint style="info" %}
If the issue persists after a re-save, please contact support. Include your **event ID** (visible in the browser URL) and describe what you expected to see versus what you are seeing — that helps us pinpoint the cause quickly.
{% endhint %}

### Synonyms and search terms

This page covers problems also described as: stale event data, outdated cache, participants not showing, missing athletes, leaderboard not updating, wrong ranking, map not showing all runners, old data in API, event not recalculated after update.


# Data APIs for live geodata

Real-time APIs: location, distance, gap, arrival, results, geofence detections for any application eg. alerts (speed, rest time, ...), TV graphic, live ranks, results, newsletter, push notification

* Location data in the APIs is calculated with each query up to every 1 sec.
* The APIs simultaneously provide real-time geo data from multiple devices.
* Data is processed from different hardware: [GPS trackers](/gps-devices), our [tracking apps](/apps), uploaded activities, and locations from [predictive tracking](/prediction).
* APIs provide the latest data from each device. That means if a GPS tracker loses connection, the information from its last update is kept in the API.

{% hint style="info" %}
For each API there is a sample of a live event and a past event. Use the samples for effortless testing of your applications with data from the APIs.

**Live sample**: Real geodata from 50 GPS trackers on a 100 km track. The sample automatically restarts playing live.

**Past sample:** Real geodata from 20 GPS units (GPS trackers, uploaded activities, and tracking apps) on a 100 km track.
{% endhint %}

{% hint style="info" %}
Data APIs are only available while the event's API module is activated. Two hours after the event's end time, the next API request will trigger [auto-pausation](/glossary#auto-pausation), and the following requests are rejected until you manually re-enable access.

Read about [API auto-pausation](/api/auto-pausation) for details and how to re-enable access.
{% endhint %}

### Live replay loop

Speed up the development progress for your own applications and dashboards with constantly available real-time data from our APIs.

Live replay loop simulates live location data that aligns with your specific use case. To accelerate your development process, we provide recorded coordinates from past events, replayed and repeated in a 24/7 live data stream. If you want to work with your own loop event, contact <support@racemap.com>.

* **Live data:** Replay recorded data from past events as a continuous live-like stream, eliminating the need to constantly source live data.
* **Continuous availability:** The loop event restarts automatically after completion, ensuring the original event data is always available in real-time.
* **Define your scenario:** Focus on specific race situations - such as drafting during overtaking, participant shortcuts, or speeding violations - and precisely replay them repeatedly to fine-tune and train your data processing and analysis.
* **Flexible configuration:** Once established, you can access the settings of your loop event in your event library and adjust key parameters, such as:
  * **Start and end times** – replay only selected timeframes (e.g., 3 min of an overtaking maneuver).
  * **Race track** – upload the shadowtrack from another event.
  * **IMEI numbers** – add and remove GPS trackers in the loop event.


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

{% tabs %}
{% tab title="participantId" %}
The <kbd>`participantId`</kbd> of a specified reference participant for the calculation of `gapAverage`, `gap`, `gapChase,` `gapDistance`, `gapAverageEx`, `gapEx`, `gapChaseEx` and `gapDistanceEx`.

* String for API <mark style="background-color:red;">**?**</mark>**participantId=66bf4318d1c783279d183e3d**
* Sample <https://racemap.com/api/data/v1/66bf4318d1c783279d183dd3/current?participantId=66bf4318d1c783279d183e3d>
* alias: `deviceId`, `starterId`, `refStarterId`
  {% endtab %}

{% tab title="startNumber" %}
The `startNumber` of a specified reference device for the calculation of `gapAverage`, `gap`, `gapChase,` `gapDistance`, `gapAverageEx`, `gapEx`, `gapChaseEx` and `gapDistanceEx`.

* String for API <mark style="background-color:red;">**?**</mark>**startNumber=053**
* Sample: [https://racemap.com/api/data/v1/66bf4318d1c783279d183dd3/current<mark style="background-color:red;">**?**</mark>**startNumber=053**](https://racemap.com/api/data/v1/66bf4318d1c783279d183dd3/current?startNumber=053)
  {% endtab %}

{% tab title="avgSpeedWindow" %}
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`](#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 <mark style="background-color:red;">**?**</mark>**avgSpeedWindow=120**
* Sample <https://racemap.com/api/data/v1/66bf4318d1c783279d183dd3/current?avgSpeedWindow=120>
* alias: `currentSpeedDuration`
  {% endtab %}

{% tab title="resultTime" %}
UTC timestamp that defines the reference time for the API response.

* If `resultTime` is not provided, the API uses the current request time as the default.
* The `resultTime` parameter lets you call API data for any past and future timestamp.
* Geodata with timestamps newer than `resultTime` are ignored in the response.
* String for API <mark style="background-color:red;">**?**</mark>**resultTime=2026-03-25T20:17:20.000Z**
* Sample <https://racemap.com/api/data/v1/66bf4318d1c783279d183dd3/current?resultTime=2026-03-25T20%3A17%3A20.000Z>
  {% endtab %}
  {% endtabs %}

{% hint style="info" %}

* Call the same API endpoint with different query parameters at the same time.
* Combine querry parameters with <mark style="background-color:red;">**&**</mark> in one call eg. [https://racemap.com/api/data/v1/66bf4318d1c783279d183dd3/current?avgSpeedWindow=600<mark style="background-color:$danger;">**&**</mark>participantId=66bf4318d1c783279d183e3d](https://racemap.com/api/data/v1/66bf4318d1c783279d183dd3/current?avgSpeedWindow=600\&participantId=66bf4318d1c783279d183e3d)
  {% endhint %}

### Response

#### Event object

<table><thead><tr><th width="190">Field</th><th width="499.59991455078125">Description</th><th>Sample</th><th data-hidden>line</th><th data-hidden></th></tr></thead><tbody><tr><td><code>name</code></td><td>Name of event</td><td><code>"100km Duathlon"</code></td><td>2</td><td></td></tr><tr><td><code>location</code></td><td>Location</td><td><code>"Dresden"</code></td><td>3</td><td></td></tr><tr><td><code>startTime</code></td><td>Start time in UTC</td><td><code>"2022-01-24T15:00:10.000Z"</code></td><td>4</td><td></td></tr><tr><td><code>endTime</code></td><td>End time in UTC</td><td><code>"2022-01-24T22:59:45.000Z"</code></td><td>5</td><td></td></tr><tr><td><code>resultTime</code></td><td>UTC timestamp for which you retrieve API data.</td><td><code>"2022-01-24T20:00:10.000Z"</code></td><td></td><td></td></tr><tr><td><code>shadowTrackUrl</code></td><td>URL to download the <a href="/pages/c4cBCt9aXT8vj2RRgUgs">shadowtrack</a> as a geojson file</td><td><code>"https://racemap.com/api/events/66bf4318d1c783279d183dd3/geo/shadow.json"</code></td><td></td><td></td></tr><tr><td><code>starters</code></td><td>Array for participant objects</td><td></td><td></td><td></td></tr></tbody></table>

#### Participant object

<table><thead><tr><th width="189.71594043022614">Field</th><th width="500.2164627541642">Description</th><th>Sample</th><th data-hidden>line</th></tr></thead><tbody><tr><td><code>id</code></td><td>Unique RACEMAP ID of the participant</td><td><code>"61a2122f181c0a0ff7b53765"</code></td><td>10</td></tr><tr><td><code>name</code>*</td><td>Name</td><td><code>"CLV Megware"</code></td><td>12</td></tr><tr><td><code>startNumber</code>*</td><td>Bib number</td><td><code>"001"</code></td><td>11</td></tr><tr><td><code>markerColor</code>*</td><td>Color of dot in tracking map, hex code</td><td><code>"#ffffff"</code></td><td></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", "sex": "male"</code></td><td></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_1"</code> or <code>null</code> if no importId exists</td><td></td></tr><tr><td><code>current</code></td><td>Object for real-time location data and gap measurements and extrapolations</td><td>Inner values are <code>null</code> if no locations within <code>startTime</code> and <code>endTime</code> are known</td><td></td></tr><tr><td><code>device</code></td><td>Object for device information</td><td><code>null</code> if device is not used in tracker management</td><td></td></tr></tbody></table>

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

#### Current object

* `current`-object provides the latest data for the specified [`resultTime`](#resulttime) parameter.
* (\*) These parameters are calculated only for events with a [shadowtrack](/live-tracking/shadowtrack#shadowtrack) and a [mapping of the geolocation](/live-tracking/shadowtrack#what-is-mapping) 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`](#participantid) or [`startNumber`](#startnumber) for calculation against the reference participant instead of the leader.

<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: sum of straight lines between 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: segments covered on 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>speedSt</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 at <code>gapCalcTime</code>.</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>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>speedSt</code> value of the leader at <code>gapCalcTime</code>.</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>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>speedSt</code> value of the chaser at <code>gapCalcTime</code>.</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 took 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 timestamp of <code>resultTime</code> with the <code>speedSt</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>speedSt</code> value of the leader at <code>resultTime</code>.</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>speedSt</code> value of the chaser at <code>resultTime</code>.</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 took 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>

#### Device object

The device object provides additional information for GPS trackers used in the [tracker management](/tracker-management).

<table><thead><tr><th width="229">Field</th><th width="260">Description [unit]</th><th>Sample</th></tr></thead><tbody><tr><td><code>externalId</code></td><td>Unique id of tracking device, can be IMEI or transponder id or App id depending on the type of device.</td><td><code>"4106050246"</code> or <code>"860599002489748"</code> or <code>"RRPing_ZDKAR32"</code> or <code>"d40ad78e-b929-4224-967e-62ca93effc68"</code></td></tr><tr><td><code>battery</code></td><td>Charge level [%] of device.</td><td><code>3</code>, <code>52</code>, <code>99</code></td></tr><tr><td><code>online</code></td><td>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.</td><td><code>true</code> or <code>false</code></td></tr><tr><td><code>isMoving</code></td><td>Shows wether a device is moving or not. Only valid if a device is online.</td><td><code>true</code> or <code>false</code></td></tr><tr><td><code>lastLocationGpsFix</code></td><td>Showing whether the device had a GPS fix when recording the latest coordinate.</td><td><code>true</code> or <code>false</code></td></tr><tr><td><code>lastLocationAt</code></td><td>Timestamp in UTC when the latest coordinate was recorded. Note: If <code>interpolation=true</code> <code>lastLocationAt</code> can differ from <code>time</code>.</td><td><code>"2022-01-24T16:33:47.012Z"</code></td></tr><tr><td><code>deviceId</code></td><td>Unique id of the tracking device in RACEMAP.</td><td><code>"5b6ac1561c6a700020a00010"</code></td></tr></tbody></table>

{% hint style="info" %}
`isMoving` is available only for Queclink GL3xx GPS trackers. The value is derived from accelerometer data.
{% endhint %}

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

{% code expandable="true" %}

```javascript
{
  "name": "Sample live API | 100km-Duathlon",
  "location": "🇩🇪 Dresden",
  "startTime": "2026-04-27T14:50:43Z",
  "endTime": "2026-04-27T18:50:07Z",
  "resultTime": "2026-04-27T15:16:37.863314808Z",
  "shadowTrackUrl": "https://racemap.com/api/events/66bf4318d1c783279d183dd3/geo/shadow.json",
  "starters": [
    {
      "id": "66bf4318d1c783279d183e33",
      "name": "Der Weg ist das Ziel e.V.",
      "startNumber": "049",
      "tags": {
        "Age": "30",
        "Class": "Women"
      },
      "markerColor": "#f714f4",
      "importId": null,
      "current": {
        "time": "2026-04-27T15:16:35.783Z",
        "lat": 51.01205,
        "lng": 13.72667,
        "elv": 172,
        "speed": 2.58,
        "lngSt": 13.726713,
        "latSt": 51.012091,
        "speedSt": 3.37,
        "distanceToShadowTrack": 5.45,
        "eta": 28081,
        "fromStart": 4520,
        "toFinish": 94540,
        "gapCalcTime": "2026-04-27T15:16:35.783Z",
        "gapDistance": 1310,
        "gap": 367,
        "gapChase": 389,
        "gapAverage": 487,
        "fromStartEx": 4527,
        "toFinishEx": 94533,
        "lngStEx": 13.917086,
        "latStEx": 50.961844,        
        "gapDistanceEx": 1310.42,
        "gapEx": 367,
        "gapChaseEx": 389,
        "gapAverageEx": 489
      },
      "device": {
        "externalId": "37727c2a-40a0-4752-9e50-7ba5bffecd9a",
        "battery": 20,
        "online": false,
        "lastLocationGpsFix": true,
        "lastLocationAt": "2024-01-05T13:45:19Z",
        "deviceId": "5b6ac1561c6a700020a00142",
        "isMoving": null
      }
    },
    {
      "id": "66bf4318d1c783279d183e2f",
      "name": "SG Turbine Gottleubatal",
      "startNumber": "046",
      "tags": {
        "Age": "35",
        "Class": "Mixed"
      },
      "markerColor": "#f7f7f7",
      "importId": null,
      "current": {
        "time": "2026-04-27T15:16:35.783Z",
        "lat": 51.00963,
        "lng": 13.72327,
        "elv": 192,
        "speed": 3.45,
        "lngSt": 13.723207,
        "latSt": 51.00963,
        "speedSt": 4.23,
        "distanceToShadowTrack": 4.42,
        "eta": 22419,
        "fromStart": 4150,
        "toFinish": 94910,
        "gapCalcTime": "2026-04-27T15:16:35.783Z",
        "gapDistance": 1680,
        "gap": 471,
        "gapChase": 396,
        "gapAverage": 533,
        "fromStartEx": 4158.81,
        "toFinishEx": 94901.19,
        "lngStEx": 13.917135,
        "latStEx": 50.968992,        
        "gapDistanceEx": 1678.61,
        "gapEx": 470,
        "gapChaseEx": 396,
        "gapAverageEx": 533
      },
      "device": null
    },
    {
      "id": "66bf4318d1c783279d183e51",
      "name": "Dude, where's the finish line?",
      "startNumber": "039",
      "tags": {
        "Age": "25",
        "Class": "Mixed",
        "Status": "DSQ"
      },
      "markerColor": "#f7f7f7",
      "importId": null,
      "current": {
        "time": "2026-04-27T15:16:27.013Z",
        "lat": 51.01788,
        "lng": 13.69662,
        "elv": 212,
        "speed": 2.96,
        "lngSt": 13.696588,
        "latSt": 51.017801,
        "speedSt": 3.27,
        "distanceToShadowTrack": 9.01,
        "eta": 29905,
        "fromStart": 1370,
        "toFinish": 97690,
        "gapCalcTime": "2026-04-27T15:16:27.013Z",
        "gapDistance": 4428.72,
        "gap": 1241,
        "gapChase": 1355,
        "gapAverage": 1347,
        "fromStartEx": 1405.44,
        "toFinishEx": 97654.56,
        "lngStEx": 13.906899,
        "latStEx": 50.948258,        
        "gapDistanceEx": 4431.98,
        "gapEx": 1242,
        "gapChaseEx": 1356,
        "gapAverageEx": 1340
      },
      "device": {
        "externalId": "999994106050526",
        "battery": 40,
        "online": false,
        "lastLocationGpsFix": true,
        "lastLocationAt": "2023-07-02T12:37:51Z",
        "deviceId": "5b3a7b3ebd61c4491dcfcef4",
        "isMoving": true
      }
    }
  ]
}
```

{% endcode %}

### 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.

<figure><img src="/files/Dl5f4380hREWLcEiF8ml" alt=""><figcaption><p>The green and orange rectangles show the <strong>gapAverageWindows</strong> used for <code>speedSt</code> calculation.</p></figcaption></figure>

### 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.

<div align="center"><figure><img src="/files/vKRntakOIJii1aFu3pce" alt=""><figcaption><p>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 <strong>gapAverageWindows</strong> used for <code>speedSt</code> calculation.</p></figcaption></figure></div>

### 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`


# \*/distance and locations

API with real-time geolocations, distances, and bearings to a reference device; for maximum stability and minimum delay the data is processed as little as possible

### Request

**URL** `https://racemap.com/api/data/v1/:eventId/distance`\
**Method** GET

**Live sample** <https://racemap.com/api/data/v1/66bf4318d1c783279d183dd3/distance>\
Corresponding map <https://racemap.com/player/100KmDuathlon2018_API-live-sample>

#### Optional query with `deviceId`

* The `deviceId` of a chosen reference device to calculate `gapDistance` and `bearing` to the other devices.
* If API is called without a `deviceId` then `gapDistance` and `bearing` is calculated for the first device in the list.
* Sample [https://racemap.com/api/data/v1/66bf4318d1c783279d183dd3/distance<mark style="background-color:red;">**?**</mark>**deviceId=66bf4318d1c783279d183e3d**](https://racemap.com/api/data/v1/66bf4318d1c783279d183dd3/distance?deviceId=66bf4318d1c783279d183e3d)

### Response

#### Event object

| Field       | Description \[unit]           | Sample                            |
| ----------- | ----------------------------- | --------------------------------- |
| `name`      | Name of event                 | `"Sample live \| 100km Duathlon"` |
| `location`  | Location                      | `"🇩🇪 Dresden"`                  |
| `startTime` | Start time in UTC             | `"2022-03-09T07:00:03.201Z"`      |
| `endTime`   | End time in UTC               | `"2022-03-09T14:59:38.201Z"`      |
| `starters`  | Array for participant objects |                                   |

#### Participant object

| Field         | Description \[unit]                                                                                                                                                                                                               | Sample                                                                                                |
| ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
| `id`          | Unique Racemap ID of participant                                                                                                                                                                                                  | `"61a2122f181c0a6c4bb5376e"`                                                                          |
| `importId`    | User-defined ID with imported participant data, [Generic API](/api-import-and-export-data/import-basics/metadata-api) (`importId`) or [RACE\|RESULT API](/api-import-and-export-data/import-basics/metadata-import-via-rr) (`Id`) | <p><code>"UniqueImportId\_2"</code> or <code>"null"</code><br>if no importId exists</p>               |
| `startNumber` | Bib number                                                                                                                                                                                                                        | `"2"`                                                                                                 |
| `name`        | Name                                                                                                                                                                                                                              | `"CLV Megware"`                                                                                       |
| `current`     | Object for real-time data                                                                                                                                                                                                         | <p><code>null</code></p><p>if no locations within <code>startTime</code> and <code>endTime</code></p> |

#### Current object

The `current`-object provides the latest data

| Field         | Description \[unit]                                                                                  | Sample                                          |
| ------------- | ---------------------------------------------------------------------------------------------------- | ----------------------------------------------- |
| `time`        | Timestamp in UTC when device recorded latest geolocation                                             | `"2022-03-09T13:23:15.000Z"`                    |
| `lat`         | Latitude                                                                                             | `51.04229`                                      |
| `lng`         | Longitude                                                                                            | `13.63867`                                      |
| `elv`         | Elevation                                                                                            | `63`                                            |
| `gapDistance` | Distance \[m] between latest locations of device and reference device                                | `679.80` or `0` for the reference device        |
| `bearing`     | Angle \[°] line between latest locations of device and reference device and line from south to north | `-76.372782293` or `0` for the reference device |

![](/files/QdhxJlgIhnIh4ArxawgQ)

#### Sample response

{% code expandable="true" %}

```javascript
{
  "name": "Sample repeat | 100km Duathlon ",
  "location": "🇩🇪 Dresden",
  "startTime": "2022-01-17T07:00:02.881Z",
  "endTime": "2022-01-17T15:00:02.881Z",
  "starters": [
    {
      "id": "61a2122f181c0a0ff7b53765",
      "importId": "UniqueImportId_1",
      "startNumber": "001",
      "name": "🔥 Flaming 🔥 Sideburns 🔥",
      "current": {
        "time": "2022-01-17T12:13:30.000Z",
        "lat": 51.10966,
        "lng": 13.71298,
        "gapDistance": 0,
        "bearing": 0
      }
    },
    {
      "id": "61a2122f181c0a6c4bb5376e",
      "importId": "UniqueImportId_2",
      "startNumber": "002",
      "name": "CLV Megware meets SG Adelsberg",
      "current": {
        "time": "2022-01-17T12:13:30.000Z",
        "lat": 51.11025,
        "lng": 13.7107,
        "gapDistance": 172.16007216012576,
        "bearing": 112.39911045990338
      }
    },
    {
      "id": "61a21230181c0a4ab0b53944",
      "importId": "UniqueImportId_54",
      "startNumber": "21",
      "name": "Kingscupkönige",
      "current": null
    }
  ]
}
```

{% endcode %}


# \*/times, reads and raw data

API with passings or detections (raw data timestamps) at virtual checkpoints respectively geofences, similar to a reader

{% hint style="info" %}
The \*/times API generates a [detection](/glossary#read) from a received location if it fulfills three conditions. The API can provide multiple detections for a split.

* The device id belongs to the event.

* The location is around the detection radius of a geofence.

* The timestamp of the location is between the event start- and end time.
  {% endhint %}

* **Effortless** [**detections**](/glossary#read) with virtual timekeeping points (geofence) and with geolocations of participants. No timing hardware, no transponders.

* [**Passings**](/glossary#read) **are recorded in a radius** around the geofence. Set the radius in the setting of the data API of your event.

* **Flexibly adjust settings in between:** add timekeeping points or change their locations of a running event or even of a past event, recalculate detections with new parameters.

### Request

**URL** `https://racemap.com/api/data/v1/:eventId/times`\
**Method** GET

**Live sample** <https://racemap.com/api/data/v1/61a21210e5d45d000199f7d9/times>\
**Past sample** <https://racemap.com/api/data/v1/60a3b443f096f800018add7c/times>

#### Optional query with `id` of a checkpoint

* The `id` of a virtual timekeeping point to get all [reads](/glossary#read) of this geofence in chronological order.
* Live sample split "Split 3"\
  [https://racemap.com/api/data/v1/61a21210e5d45d000199f7d9/times/**6450e60747adaed475b484b4**](https://racemap.com/api/data/v1/61a21210e5d45d000199f7d9/times/6450e60747adaed475b484b4)
* Past sample split "Finish"\
  [https://racemap.com/api/data/v1/60a3b443f096f800018add7c/times/**64513872c3ab09659eb09683**](https://racemap.com/api/data/v1/60a3b443f096f800018add7c/times/64513872c3ab09659eb09683)

### Response

#### Event object

| Field          | Description \[unit]           | Sample                            |
| -------------- | ----------------------------- | --------------------------------- |
| `name`         | Name of event                 | `"Sample live \| 100km Duathlon"` |
| `location`     | Location                      | `"🇩🇪 Dresden"`                  |
| `startTime`    | Start time in UTC             | `"2022-03-09T07:00:03.201Z"`      |
| `endTime`      | End time in UTC               | `"2022-03-09T14:59:38.201Z"`      |
| `timekeepings` | Array for checkpoint objects  |                                   |
| `starters`     | Array for participant objects |                                   |

#### Checkpoint object

<table><thead><tr><th width="232">Field</th><th width="232.33333333333331">Description</th><th>Sample</th></tr></thead><tbody><tr><td><code>name</code></td><td>Name of virtual timekeeping point</td><td><code>"Split 5"</code></td></tr><tr><td><code>offset</code></td><td>Distance [m] along 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>id</code></td><td>Unique Racemap ID of timekeeping point</td><td><code>"6450e60747adaed475b48"</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

| Field         | Description \[unit]                                                                                                                                                                                                               | Sample                                                                                                                                                            |
| ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`          | Unique Racemap ID of participant                                                                                                                                                                                                  | `"61a2122f181c0a6c4bb5376e"`                                                                                                                                      |
| `importId`    | User-defined ID with imported participant data, [Generic API](/api-import-and-export-data/import-basics/metadata-api) (`importId`) or [RACE\|RESULT API](/api-import-and-export-data/import-basics/metadata-import-via-rr) (`Id`) | <p><code>"UniqueImportId\_2"</code> or <code>"null"</code><br>if no importId exists</p>                                                                           |
| `startNumber` | Bib number                                                                                                                                                                                                                        | `"2"`                                                                                                                                                             |
| `name`        | Name                                                                                                                                                                                                                              | `"CLV Megware"`                                                                                                                                                   |
| `times`       | Object for checkpoint arrays                                                                                                                                                                                                      | <p><code>null</code><br>if no locations within <code>startTime</code> and <code>endTime</code><br><code>{}</code><br>if there are locations but no detections</p> |

#### Checkpoint array

<table><thead><tr><th>Description</th><th>Sample</th><th data-hidden></th></tr></thead><tbody><tr><td>Unique Racemap ID of timekeeping point, array for detection objects</td><td><code>6450e60747adaed475b484b4</code></td><td></td></tr></tbody></table>

#### Detection object

| Field             | Description \[unit]                               | Sample                       |
| ----------------- | ------------------------------------------------- | ---------------------------- |
| `time`            | Timestamp of detection in UTC                     | `"2022-03-09T10:08:00.000Z"` |
| `distanceToSplit` | Distance \[m] of detection from timekeeping point | `43.96`                      |

#### Sample response

{% code expandable="true" %}

```javascript
{
  "name": "Sample | 100km Duathlon",
  "location": "🇩🇪 Dresden",
  "startTime": "2020-04-25T06:00:00Z",
  "endTime": "2020-10-30T18:15:00Z",
  "timekeepings": [
    {
      "name": "Start",
      "offset": 0,
      "position": [13.704069467101244, 51.027617808548015, 159],
      "id": "64513872c3ab09659eb09674"
    },
    {
      "name": "Ruppendorf",
      "offset": 29510,
      "position": [13.599722542890463, 50.90910508578093, 377],
      "id": "64513873368d2f24f3a5feb9"
    },
    {
      "name": "🕖",
      "offset": 48130,
      "position": [13.633563734472718, 50.77911506210913, 570],
      "id": "64513873a2c6e28dbe010405"
    },
    {
      "name": "Bergwertung",
      "offset": 49950,
      "position": [13.623273503927214, 50.76995405256768, 743],
      "id": "64513874c3ab09659eb096b5"
    },
    {
      "name": "🕖",
      "offset": 67660,
      "position": [13.69125, 50.82612, 471],
      "id": "645138746451816d07b38788"
    },
    {
      "name": "Bergwertung",
      "offset": 68780,
      "position": [13.697525647974045, 50.83382486871975, 603],
      "id": "6451387410e583b28d7167e6"
    },
    {
      "name": "Finish",
      "offset": 100260,
      "position": [13.704038205094022, 51.02687962934201, 166],
      "id": "64513872c3ab09659eb09683"
    }
  ],
  "starters": [
    {
      "id": "60a3b6791474227ee54a5bdf",
      "importId": "UniqueImportId_1",
      "startNumber": "01",
      "name": "Konrad",
      "times": null
    },
    {
      "id": "60a3b679147422b72a4a5be0",
      "importId": "UniqueImportId_2",
      "startNumber": "02",
      "name": "Jörg",
      "times": {
        "64513872c3ab09659eb09674": [
          {
            "time": "2020-04-26T08:23:55Z",
            "distanceToSplit": 16.81
          },
          {
            "time": "2020-04-26T08:24:00Z",
            "distanceToSplit": 8.92
          }
        ],
        "64513873368d2f24f3a5feb9": [
          {
            "time": "2020-04-26T10:19:45Z",
            "distanceToSplit": 20.36
          },
          {
            "time": "2020-04-26T10:19:50Z",
            "distanceToSplit": 26.4
          }
        ],
        "64513873a2c6e28dbe010405": [
          {
            "time": "2020-04-26T11:30:40Z",
            "distanceToSplit": 14.17
          },
          {
            "time": "2020-04-26T11:30:45Z",
            "distanceToSplit": 15.18
          }
        ],
        "64513874c3ab09659eb096b5": [
          {
            "time": "2020-04-26T11:41:05Z",
            "distanceToSplit": 19.22
          },
          {
            "time": "2020-04-26T11:41:10Z",
            "distanceToSplit": 4.46
          }
        ],
        "645138746451816d07b38788": [
          {
            "time": "2020-04-26T13:00:30Z",
            "distanceToSplit": 16.19
          },
          {
            "time": "2020-04-26T13:00:35Z",
            "distanceToSplit": 8.29
          },
          {
            "time": "2020-04-26T13:00:40Z",
            "distanceToSplit": 17.85
          },
          {
            "time": "2020-04-26T13:00:45Z",
            "distanceToSplit": 27.8
          }
        ],
        "6451387410e583b28d7167e6": [
          {
            "time": "2020-04-26T13:08:40Z",
            "distanceToSplit": 26.12
          },
          {
            "time": "2020-04-26T13:08:45Z",
            "distanceToSplit": 12.82
          },
          {
            "time": "2020-04-26T13:08:50Z",
            "distanceToSplit": 4.25
          },
          {
            "time": "2020-04-26T13:08:55Z",
            "distanceToSplit": 15.45
          }
        ],
        "64513872c3ab09659eb09683": [
          {
            "time": "2020-04-26T14:50:30Z",
            "distanceToSplit": 28.16
          },
          {
            "time": "2020-04-26T14:50:35Z",
            "distanceToSplit": 2.91
          }
        ]
      }
    },
    {
      "id": "60a3b67914742230ef4a5be2",
      "importId": "UniqueImportId_3",
      "startNumber": "03",
      "name": "Leupold",
      "times": {
        "64513872c3ab09659eb09674": [
          {
            "time": "2020-05-01T07:49:45Z",
            "distanceToSplit": 13.06
          },
          {
            "time": "2020-05-01T07:49:50Z",
            "distanceToSplit": 10.56
          },
          {
            "time": "2020-05-01T13:06:25Z",
            "distanceToSplit": 19.77
          },
          {
            "time": "2020-05-01T13:06:30Z",
            "distanceToSplit": 17.84
          }
        ],
        "64513873368d2f24f3a5feb9": [
          {
            "time": "2020-05-01T09:26:45Z",
            "distanceToSplit": 1.69
          }
        ],
        "64513873a2c6e28dbe010405": [
          {
            "time": "2020-05-01T10:24:35Z",
            "distanceToSplit": 12.15
          },
          {
            "time": "2020-05-01T10:24:40Z",
            "distanceToSplit": 22.72
          }
        ],
        "64513874c3ab09659eb096b5": [
          {
            "time": "2020-05-01T10:34:50Z",
            "distanceToSplit": 27.7
          },
          {
            "time": "2020-05-01T10:34:55Z",
            "distanceToSplit": 1.95
          }
        ],
        "645138746451816d07b38788": [
          {
            "time": "2020-05-01T11:24:30Z",
            "distanceToSplit": 18.56
          },
          {
            "time": "2020-05-01T11:24:35Z",
            "distanceToSplit": 10.39
          },
          {
            "time": "2020-05-01T11:24:40Z",
            "distanceToSplit": 22.24
          }
        ],
        "6451387410e583b28d7167e6": [
          {
            "time": "2020-05-01T11:31:30Z",
            "distanceToSplit": 29.7
          },
          {
            "time": "2020-05-01T11:31:35Z",
            "distanceToSplit": 10.6
          },
          {
            "time": "2020-05-01T11:31:40Z",
            "distanceToSplit": 5.61
          },
          {
            "time": "2020-05-01T11:31:45Z",
            "distanceToSplit": 22.52
          }
        ],
        "64513872c3ab09659eb09683": [
          {
            "time": "2020-05-01T13:06:15Z",
            "distanceToSplit": 11.25
          },
          {
            "time": "2020-05-01T13:06:20Z",
            "distanceToSplit": 25.62
          }
        ]
      }
    }
  ]
}
```

{% endcode %}

#### Sample response with `id` of checkpoint

Checkpoint "Bergwertung"\
[https://racemap.com/api/data/v1/60a3b443f096f800018add7c/times/**6451387410e583b28d7167e6**](https://racemap.com/api/data/v1/60a3b443f096f800018add7c/times/6451387410e583b28d7167e6)

#### Times array with detection objects

<table><thead><tr><th width="221.33333333333331">Field</th><th>Description [unit]</th><th>Sample</th></tr></thead><tbody><tr><td><code>id</code></td><td>Unique Racemap ID of participant</td><td><code>"6450e60747adaed475b48"</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></td></tr><tr><td><code>startNumber</code></td><td>Bib number</td><td><code>"02"</code></td></tr><tr><td><code>name</code></td><td>Name</td><td><code>"Jörg"</code></td></tr><tr><td><code>time</code></td><td>Timestamp of detection in UTC</td><td><code>"2022-03-09T10:08:00.000Z"</code></td></tr><tr><td><code>distanceToSplit</code></td><td>Distance [m] of detection from timekeeping point</td><td><code>16.19</code></td></tr></tbody></table>

{% code expandable="true" %}

```javascript
{
  "name": "Sample | 100km Duathlon",
  "location": "🇩🇪 Dresden",
  "startTime": "2020-04-25T06:00:00Z",
  "endTime": "2020-10-30T18:15:00Z",
  "timekeepingId": "6451387410e583b28d7167e6",
  "timekeepingName": "Bergwertung",
  "times": [
    {},
    {
      "id": "60a3b679147422b72a4a5be0",
      "importId": "UniqueImportId_2",
      "startNumber": "02",
      "name": "Jörg",
      "time": "2020-04-26T13:08:45Z",
      "distanceToSplit": 12.82
    },
    {
      "id": "60a3b679147422b72a4a5be0",
      "importId": "UniqueImportId_2",
      "startNumber": "02",
      "name": "Jörg",
      "time": "2020-04-26T13:08:50Z",
      "distanceToSplit": 4.25
    },
    {
      "id": "60a3b679147422b72a4a5be0",
      "importId": "UniqueImportId_2",
      "startNumber": "02",
      "name": "Jörg",
      "time": "2020-04-26T13:08:55Z",
      "distanceToSplit": 15.45
    },
    {
      "id": "60a3b67914742230ef4a5be2",
      "importId": "UniqueImportId_3",
      "startNumber": "03",
      "name": "Leupold",
      "time": "2020-05-01T11:31:30Z",
      "distanceToSplit": 29.7
    },
    {
      "id": "60a3b67914742230ef4a5be2",
      "importId": "UniqueImportId_3",
      "startNumber": "03",
      "name": "Leupold",
      "time": "2020-05-01T11:31:35Z",
      "distanceToSplit": 10.6
    },
    {
      "id": "60a3b67914742230ef4a5be2",
      "importId": "UniqueImportId_3",
      "startNumber": "03",
      "name": "Leupold",
      "time": "2020-05-01T11:31:40Z",
      "distanceToSplit": 5.61
    },
    {
      "id": "60a3b67914742230ef4a5be2",
      "importId": "UniqueImportId_3",
      "startNumber": "03",
      "name": "Leupold",
      "time": "2020-05-01T11:31:45Z",
      "distanceToSplit": 22.52
    },
    {
      "id": "60a3b679147422101b4a5be3",
      "importId": "UniqueImportId_4",
      "startNumber": "04",
      "name": " KRad",
      "time": "2020-05-02T10:41:35Z",
      "distanceToSplit": 17.72
    },
    {
      "id": "60a3b679147422101b4a5be3",
      "importId": "UniqueImportId_4",
      "startNumber": "04",
      "name": " KRad",
      "time": "2020-05-02T10:41:40Z",
      "distanceToSplit": 7.18
    },
    {
      "id": "60a3b679147422101b4a5be3",
      "importId": "UniqueImportId_4",
      "startNumber": "04",
      "name": " KRad",
      "time": "2020-05-02T10:41:45Z",
      "distanceToSplit": 11.5
    },
    {
      "id": "60a3b679147422101b4a5be3",
      "importId": "UniqueImportId_4",
      "startNumber": "04",
      "name": " KRad",
      "time": "2020-05-02T10:41:50Z",
      "distanceToSplit": 29.53
    }
  ]
}
```

{% endcode %}

### Export to RACE|RESULT

RACE|RESULT event settings: Main Window, Simple API

* Type: Custom
* Details: rawdata/addmanual

Settings create an API key to push external data to RACE|RESULT. The duration of the key is limited. Sample: <https://api.raceresult.com/180472/G5XQYZKPIPU5J1RSCVIZ48QKVU5JIIJP>

![](/files/-MjnFlci2mpv6r7LuI8N)

Data from Racemap \*/times API need be transferred to RACE|RESULT API format, e.g. with a python script:

* syntax: <https://api.raceresult.com/`eventId`/`apiKey`?&`bib`=bibNumber&`time`=timeOfDetections&`TimingPoint`=splitName>
* timeOfDetections in seconds
* sample: <https://api.raceresult.com/180472/G5XQYZKPIPU5J1RSCVIZ48QKVU5JIIJP?&bib=1&time=36600&TimingPoint=Messstelle1>

Using this format virtual detections are imported in RACE|RESULT one by one.

![](/files/-MjnII-YafvX3HzOHM3l)


# \*/ranks, ranking and results

API with live ranking and results corresponding to splits and calculations in the leaderboard

Read all about the data processing in the leaderboard:

{% content-ref url="/pages/-LYXfT2qbHHP6XDl9-g6" %}
[Leaderboard](/live-tracking/gps-timing)
{% endcontent-ref %}

### Request

**URL** `https://racemap.com/api/data/v1/:eventId/ranks`\
**Method** GET

**Live sample** <https://racemap.com/api/data/v1/61a21210e5d45d000199f7d9/ranks>\
corresponding leaderboard <https://racemap.com/timing/100KmDuathlon2018_Repeat>

**Past sample** <https://racemap.com/api/data/v1/60a3b443f096f800018add7c/ranks>\
corresponding leaderboard <https://racemap.com/timing/sample-event-100km-duathlon_2020>

### Response

#### Event object

<table><thead><tr><th width="163.49682120021123">Field</th><th width="204.46455485213932">Description [unit]</th><th>Sample</th><th data-hidden>line</th></tr></thead><tbody><tr><td><code>name</code></td><td>Name of event</td><td><code>"Sample | 100km Duathlon"</code></td><td>2</td></tr><tr><td><code>location</code></td><td>Location</td><td><code>"🇩🇪 Dresden"</code></td><td>3</td></tr><tr><td><code>startTime</code></td><td>Start time in UTC</td><td><code>"2020-04-25T06:00:00.000Z"</code></td><td>4</td></tr><tr><td><code>endTime</code></td><td>End time in UTC</td><td><code>"2020-10-30T18:15:00.000Z"</code></td><td>5</td></tr><tr><td><code>timekeepings</code></td><td>Array for split objects</td><td></td><td>6</td></tr><tr><td><code>starters</code></td><td>Array for participant objects</td><td></td><td>7</td></tr></tbody></table>

#### Split object

<table><thead><tr><th width="150">Field</th><th width="316.3333333333333">Description [unit]</th><th>Sample</th><th data-hidden>line</th></tr></thead><tbody><tr><td><code>name</code></td><td>Name of split</td><td><code>"Finish"</code></td><td>10</td></tr><tr><td><code>offset</code></td><td>Distance [m] along the <a href="https://docs.racemap.com/create-live-tracking/tab-map#shadowtrack">shadowtrack</a>​</td><td><code>100262.4279943064</code></td><td>11</td></tr><tr><td><code>position</code></td><td>Array with longitude, latitude, altitude [m]</td><td><code>13.704038205094022, 51.02687962934201, 166</code></td><td>13 to 16</td></tr><tr><td><code>id</code></td><td>Unique Racemap ID of split</td><td><code>"64513872c3ab09659eb09683"</code></td><td>12</td></tr></tbody></table>

#### Participant object

<table><thead><tr><th width="203.42645717134292">Field</th><th width="332.2158611690556">Description [unit]</th><th width="150">Sample</th><th data-hidden>line</th><th data-hidden></th></tr></thead><tbody><tr><td><code>id</code></td><td>Unique Racemap ID of participant</td><td><code>"60a3b67914742230d14a5bf4"</code></td><td>82</td><td></td></tr><tr><td><code>name</code>*</td><td>Name</td><td><code>"Porstmann"</code></td><td>83</td><td></td></tr><tr><td><code>startNumber</code>*</td><td>Bib number</td><td><code>"18"</code></td><td>84</td><td></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", "club": "VfA end"</code></td><td></td><td></td></tr><tr><td><code>markerColor</code>*</td><td>Color of dot in tracking map, hex code</td><td><code>"#ffffff"</code></td><td></td><td></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_18"</code> or <code>"null"</code><br>if no importId exists</td><td></td><td></td></tr><tr><td><code>rank</code></td><td>Rank</td><td>1</td><td>87</td><td></td></tr><tr><td><code>state</code></td><td></td><td><code>DSQ</code>, <code>DNS</code>, <code>DNF</code> or <code>null</code></td><td>88</td><td></td></tr><tr><td><code>online</code></td><td>Indicator: coordinates received within last 60 s</td><td><code>true</code> or <code>false</code></td><td>138</td><td></td></tr><tr><td><code>progress</code></td><td>Current distance [m] or current duration [ms]</td><td><code>100310</code> or <code>null</code><br>if no locations within <code>startTime</code> and <code>endTime</code></td><td>89</td><td></td></tr><tr><td><code>currentDuration</code></td><td>Total duration [ms] to reach finish</td><td><code>14697500</code> or <code>null</code><br>if no locations within <code>startTime</code> and <code>endTime</code></td><td>86</td><td></td></tr><tr><td><code>activeDuration</code></td><td>Duration [ms], movement with speed > 1 km/h, within start- and end time of event</td><td><code>10965700</code> or <code>null</code><br>if no locations within <code>startTime</code> and <code>endTime</code></td><td></td><td></td></tr><tr><td><code>results</code></td><td>Array for objects with the result for each split</td><td><code>null</code><br>if split without result</td><td></td><td></td></tr></tbody></table>

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

#### Result object

<table><thead><tr><th width="211.33333333333331">Field</th><th width="271.70142180094786">Description [unit]</th><th>Sample</th><th data-hidden>line</th></tr></thead><tbody><tr><td><code>id</code></td><td>Unique Racemap ID of split</td><td><code>"64513872c3ab09659eb09683"</code></td><td>102</td></tr><tr><td><code>time</code></td><td>Time in UTC</td><td><code>"2020-04-25T12:10:13Z"</code></td><td>103</td></tr><tr><td><code>relativeProgress</code></td><td>Duration [ms] - set leaderboard target: distance - OR distance [m] - target: duration - from first split</td><td><code>22213000</code></td><td>104</td></tr><tr><td><code>relativeDeltaProgress</code></td><td>Duration [ms] (target: distance) OR distance [m] (duration) from split before</td><td><code>6974608</code></td><td>105</td></tr></tbody></table>

{% code expandable="true" %}

```javascript
{
  "name": "Sample | 100km Duathlon",
  "location": "🇩🇪 Dresden",
  "startTime": "2020-04-25T06:00:00Z",
  "endTime": "2020-10-30T18:15:00Z",
  "timekeepings": [
    {
      "name": "Start",
      "offset": 0,
      "position": [13.704069467101244, 51.027617808548015, 159],
      "id": "64513872c3ab09659eb09674"
    },
    {
      "name": "Ruppendorf",
      "offset": 29513.002967649845,
      "position": [13.599722542890463, 50.90910508578093, 377],
      "id": "64513873368d2f24f3a5feb9"
    },
    {
      "name": "🕖",
      "offset": 48125.51853411951,
      "position": [13.633563734472718, 50.77911506210913, 570],
      "id": "64513873a2c6e28dbe010405"
    },
    {
      "name": "Bergwertung",
      "offset": 49950.82522183896,
      "position": [13.623273503927214, 50.76995405256768, 743],
      "id": "64513874c3ab09659eb096b5"
    },
    {
      "name": "🕖",
      "offset": 67658.33026919093,
      "position": [13.69125, 50.82612, 471],
      "id": "645138746451816d07b38788"
    },
    {
      "name": "Bergwertung",
      "offset": 68781.263669599,
      "position": [13.697525647974045, 50.83382486871975, 603],
      "id": "6451387410e583b28d7167e6"
    },
    {
      "name": "Finish",
      "offset": 100262.4279943064,
      "position": [13.704038205094022, 51.02687962934201, 166],
      "id": "64513872c3ab09659eb09683"
    }
  ],
  "starters": [
    {
      "id": "60a3b67914742230ef4a5be2",
      "name": "Leupold",
      "startNumber": "03",
      "tags": {
        "sex": "mal",
        "club": "VfA end",
        "age": "40-49"
      },
      "markerColor": "#ffffff",
      "importId": "UniqueImportId_3",
      "rank": 7,
      "state": null,
      "online": false,
      "progress": 100262.4279943064,
      "currentDuration": 18030000,
      "activeDuration": 17410000,
      "results": [
        {
          "id": "64513872c3ab09659eb09674",
          "time": "2020-04-25T06:00:00Z",
          "relativeProgress": 0,
          "relativeDeltaProgress": 0
        },
        {
          "id": "64513873368d2f24f3a5feb9",
          "time": "2020-04-25T07:48:58.564Z",
          "relativeProgress": 6538564,
          "relativeDeltaProgress": 6538564
        },
        {
          "id": "64513873a2c6e28dbe010405",
          "time": "2020-04-25T08:57:42.140Z",
          "relativeProgress": 10662140,
          "relativeDeltaProgress": 4123576
        },
        {
          "id": "64513874c3ab09659eb096b5",
          "time": "2020-04-25T09:04:26.535Z",
          "relativeProgress": 11066535,
          "relativeDeltaProgress": 404395
        },
        {
          "id": "645138746451816d07b38788",
          "time": "2020-04-25T10:09:49.607Z",
          "relativeProgress": 14989607,
          "relativeDeltaProgress": 3923072
        },
        {
          "id": "6451387410e583b28d7167e6",
          "time": "2020-04-25T10:13:58.392Z",
          "relativeProgress": 15238392,
          "relativeDeltaProgress": 248785
        },
        {
          "id": "64513872c3ab09659eb09683",
          "time": "2020-04-25T12:10:13Z",
          "relativeProgress": 22213000,
          "relativeDeltaProgress": 6974608
        }
      ]
    },
    {
      "id": "60a3b67914742223014a5bea",
      "name": "Michi",
      "startNumber": "11",
      "tags": {
        "sex": "mal",
        "age": "30-39",
        "club": "Flaming Sideburns"
      },
      "markerColor": "#ffffff",
      "importId": "UniqueImportId_11",
      "rank": 11,
      "state": null,
      "online": false,
      "progress": 100262.4279943064,
      "currentDuration": 23430000,
      "activeDuration": 21700000,
      "results": [
        {
          "id": "64513872c3ab09659eb09674",
          "time": "2020-05-02T06:06:00Z",
          "relativeProgress": 0,
          "relativeDeltaProgress": 0
        },
        {
          "id": "64513873368d2f24f3a5feb9",
          "time": "2020-05-02T08:07:19Z",
          "relativeProgress": 7279000,
          "relativeDeltaProgress": 7279000
        },
        {
          "id": "64513873a2c6e28dbe010405",
          "time": "2020-05-02T09:14:27.931Z",
          "relativeProgress": 11307931,
          "relativeDeltaProgress": 4028931
        },
        {
          "id": "64513874c3ab09659eb096b5",
          "time": "2020-05-02T09:26:40.137Z",
          "relativeProgress": 12040137,
          "relativeDeltaProgress": 732206
        },
        {
          "id": "645138746451816d07b38788",
          "time": "2020-05-02T10:33:39.165Z",
          "relativeProgress": 16059165,
          "relativeDeltaProgress": 4019028
        },
        {
          "id": "6451387410e583b28d7167e6",
          "time": "2020-05-02T10:41:37.087Z",
          "relativeProgress": 16537087,
          "relativeDeltaProgress": 477922
        },
        {
          "id": "64513872c3ab09659eb09683",
          "time": "2020-05-02T12:33:50.567Z",
          "relativeProgress": 23270567,
          "relativeDeltaProgress": 6733480
        }
      ]
    },
    {
      "id": "60a3b679147422101b4a5be3",
      "name": " KRad",
      "startNumber": "04",
      "tags": {
        "sex": "mal",
        "club": "VfA end",
        "age": "30-39"
      },
      "markerColor": "#ffffff",
      "importId": "UniqueImportId_4",
      "rank": 16,
      "state": null,
      "online": false,
      "progress": 100262.4279943064,
      "currentDuration": 23310000,
      "activeDuration": 21225000,
      "results": [null, null, null, null, null, null, null]
    }
  ]
}
```

{% endcode %}


# \*/starters, athlete data

API with parameters from participants in Racemap event

### Request

**URL** `https://racemap.com/api/events/:eventId/starters`\
**Method** GET

**Sample**

* with [RACE|RESULT API](/api-import-and-export-data/import-basics/metadata-import-via-rr) to synchronize participants <https://racemap.com/api/events/61431c9fd2595a00010f9459/starters>
* without API to import participants <https://racemap.com/api/events/60a3b443f096f800018add7c/starters>

{% hint style="info" %}
This endpoint is **public**. Anyone can read the participant list without signing in, as long as the event's visibility is **Open**, **Listed**, or **Unlisted**. For **Draft** or **Archived** events the response is an empty list for anonymous callers.

Fields marked with `(*)` (e.g. `key`, `appId`, `trackId`) are personal data and are only included for signed-in Racemap accounts that may edit the event.
{% endhint %}

### Response

#### Participant object

<table><thead><tr><th width="225.7583408476105">Field</th><th width="277.9718253321284">Description [unit]</th><th>Sample</th><th data-hidden>line</th></tr></thead><tbody><tr><td><code>manualFinishDuration</code></td><td>Manually edited duration [ms] to reach the finish</td><td><code>22213000</code> or <code>null</code></td><td>3</td></tr><tr><td><code>key</code> *</td><td><code>key</code> assigned to participant</td><td><code>"K84N2S"</code></td><td>4</td></tr><tr><td><code>keyUsed</code></td><td>Indicator if key used in tracking app or to upload activity</td><td><code>true</code> or <code>false</code></td><td>5</td></tr><tr><td><code>markerColor</code></td><td>Color of dot in tracking map, hex code</td><td><code>"#ffffff"</code></td><td>6</td></tr><tr><td><code>startNumber</code></td><td>Bib number of participant</td><td><code>"02"</code></td><td>7</td></tr><tr><td><code>name</code></td><td>Name</td><td><code>"KRad"</code></td><td>8</td></tr><tr><td><code>deviceType</code></td><td>Type of used device, eg. type of GPS tracker or smartphone</td><td><code>"GT560"</code></td><td>10</td></tr><tr><td><code>deviceClass</code></td><td>Class of used device</td><td><code>Mobile</code>, <code>Upload</code>, <code>Tracker</code> or <code>Transponder</code></td><td>11</td></tr><tr><td><code>startTime</code></td><td>Timestamp of the first location in UTC</td><td><code>"2021-09-09T23:00:00.000Z"</code> or <code>null</code></td><td>12</td></tr><tr><td><code>endTime</code></td><td>Timestamp of last location in UTC</td><td><code>"2021-09-10T03:04:07.020Z"</code> or <code>null</code></td><td>13</td></tr><tr><td><code>eventId</code></td><td>Unique Racemap ID of event</td><td><code>"60a3b443f096f800018add7c"</code></td><td>14</td></tr><tr><td><code>appId</code> *</td><td>Unique Racemap ID of installed tracking app or IMEI of tracker or transponder ID</td><td><code>"4105637864"</code></td><td>9</td></tr><tr><td><code>updatedAt</code></td><td>Timestamp of latest update participant's parameters in UTC</td><td><code>"2021-12-17T11:22:07.598Z"</code></td><td>15</td></tr><tr><td><code>trackId</code> *</td><td>Unique Racemap ID of geolocations</td><td><code>"5ba900db9193f62fab70120f"</code></td><td>16</td></tr><tr><td><code>id</code></td><td>Unique Racemap ID of participant</td><td><code>"61bc72291190558210a76d97"</code></td><td>23</td></tr><tr><td><code>gpxUrl</code></td><td>URL to download the device's recorded track</td><td><code>"http://racemap.com/api/starters/61bc72291190558210a76d97/gpx"</code></td><td></td></tr><tr><td><code>listPosition</code></td><td>Position in API</td><td><code>2</code></td><td>24</td></tr><tr><td><code>times</code></td><td>Object with received timestamps from generic API in UTC</td><td></td><td></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", "club": "VfA end"</code></td><td></td></tr><tr><td><code>integrations</code></td><td>Object with addtional 3rd party information of participant</td><td></td><td></td></tr></tbody></table>

#### Integrations object

<table><thead><tr><th width="193.1078876281131">Field</th><th width="250.35876426050012">Description [unit]</th><th>Sample</th></tr></thead><tbody><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_3"</code> or <code>"2"</code> or <code>"null"</code><br>if no importId exists</td></tr><tr><td><code>genericImportKey</code></td><td>Unique Racemap ID, from import with <a href="/pages/-LTq5TdE6GKt2S6dgesz">Generic API</a>, not the same as <code>importId</code></td><td><code>"622a1e78f5b3110001c8dd75_Z7csQ5_UniqueImportID_2"</code></td></tr><tr><td><code>raceresultKey</code></td><td>Unique Racemap ID, from import with <a href="/pages/-LTh-oAm96bieBZVeffZ">RACE|RESULT API</a>, not the same as <code>importId</code></td><td>​<code>"2_180472_0"</code></td></tr></tbody></table>

{% tabs %}
{% tab title="without import" %}
{% code expandable="true" %}

```javascript
[
  {
    "manualFinishDuration": null,
    "key": "3Z2GPX",
    "keyUsed": true,
    "markerColor": "#ffffff",
    "startNumber": "01",
    "name": "Konrad",
    "appId": "453cc844-fd1e-4026-976d-ddf05c4dc757",
    "deviceType": "android|11|samsung SM-M315F|3.24.12",
    "deviceClass": "Mobile",
    "startTime": "2020-04-25T06:14:00.000Z",
    "endTime": "2020-09-25T19:45:00.000Z",
    "eventId": "60a3b443f096f800018add7c",
    "updatedAt": "2021-11-03T15:12:14.454Z",
    "trackId": "6040a02f46406c763600655b",
    "times": {},
    "tags": {
      "age": "30-39",
      "sex": "mal",
      "club": "VfA end"
    },
    "integrations": {
      "importId": "UniqueImportId_1"
    },
    "id": "60a3b6791474227ee54a5bdf",
    "gpxUrl": "http://racemap.com/api/starters/60a3b6791474227ee54a5bdf/gpx",
    "listPosition": 0,
    "deviceGpsFix": false
  },
  {
    "manualFinishDuration": null,
    "key": "K84N2S",
    "keyUsed": false,
    "markerColor": "#ffffff",
    "startNumber": "02",
    "name": "Jörg",
    "appId": "e6921eff-0fba-41b1-aea0-258c202d2e96",
    "deviceType": "",
    "deviceClass": "Upload",
    "startTime": "2020-04-25T06:14:00.000Z",
    "endTime": "2020-09-25T21:59:00.000Z",
    "eventId": "60a3b443f096f800018add7c",
    "updatedAt": "2021-11-03T15:09:35.285Z",
    "trackId": "5ea88f8e106f5f2d9919c859",
    "times": {},
    "tags": {
      "age": "40-49",
      "sex": "mal",
      "club": "VfA end"
    },
    "integrations": {
      "importId": "UniqueImportId_2"
    },
    "id": "60a3b679147422b72a4a5be0",
    "gpxUrl": "http://racemap.com/api/starters/60a3b679147422b72a4a5be0/gpx",
    "listPosition": 1,
    "deviceGpsFix": false
  }
]
```

{% endcode %}
{% endtab %}

{% tab title="RACE|RESULT import" %}
{% code expandable="true" %}

```javascript
[
  {
    "integrations": {
      "importId": "1",
      "raceresultKey": "1_180472_1",
      "messagingToken": null
    },
    "appId": "4105637844",
    "deviceType": null,
    "deviceClass": "Tracker",
    "manualFinishDuration": null,
    "keyUsed": false,
    "markerColor": "#f2f2f2",
    "startNumber": "1",
    "name": "Christoph Schroth",
    "eventId": "61431c9fd2595a00010f9459",
    "tags": {
      "age": "Elite M30",
      "sex": "m",
      "nationality": "GER",
      "status": "DNS",
      "contest": "Gravel",
      "Team": "Mixed",
      "Category": "Amateur"
    },
    "times": {
      "start": "2021-09-09T22:00:00.000Z"
    },
    "updatedAt": "2023-08-10T09:16:15.066Z",
    "trackId": "6143234182ad4c13bf2d0028",
    "endTime": null,
    "startTime": "2021-09-09T22:00:00.000Z",
    "key": "6WLWTR",
    "id": "631857aed4074c7d42cb4945",
    "gpxUrl": "http://racemap.com/api/starters/631857aed4074c7d42cb4945/gpx",
    "listPosition": 0,
    "deviceGpsFix": false,
    "deviceId": null
  },
  {
    "integrations": {
      "messagingToken": null,
      "importId": "5",
      "raceresultKey": "5_180472_1"
    },
    "appId": "860665002484665",
    "deviceType": null,
    "deviceClass": "Tracker",
    "manualFinishDuration": null,
    "keyUsed": false,
    "markerColor": "#04b404",
    "startNumber": "4",
    "name": "Karl Wolffgang",
    "eventId": "61431c9fd2595a00010f9459",
    "tags": {
      "age": "Elite M30",
      "sex": "m",
      "nationality": "GER",
      "contest": "MTB",
      "Team": "Men",
      "Category": "Amateur"
    },
    "times": {
      "start": "2021-09-09T22:00:00.000Z"
    },
    "updatedAt": "2022-09-10T05:02:02.295Z",
    "trackId": "61431f892237cfdd853da2d9",
    "endTime": null,
    "startTime": "2021-09-09T22:00:00.000Z",
    "id": "631857aeb520f243962f832d",
    "gpxUrl": "http://racemap.com/api/starters/631857aeb520f243962f832d/gpx",
    "listPosition": 4,
    "deviceGpsFix": false,
    "deviceId": null
  }
]
```

{% endcode %}
{% endtab %}
{% endtabs %}


# \*/geo, geo elements

API providing the geo elements from the tracking map

### Request

**URL** `https://racemap.com/api/events/:eventId/geo`\
**Method** GET

**Sample** <https://racemap.com/api/events/61a2055b10cacc0001302283/geo>\
Corresponding map <https://racemap.com/player/100KmDuathlon2018>

#### Options

{% tabs %}
{% tab title="splits" %}
API provides only the splits of one tracking map.\
Sample: [https://racemap.com/api/events/61a2055b10cacc0001302283/geo/**splits**](https://racemap.com/api/events/61a2055b10cacc0001302283/geo/splits)
{% endtab %}

{% tab title="shadow\.json" %}
API provides the shadow track and the splits of one tracking map.\
Sample: [https://racemap.com/api/events/61a2055b10cacc0001302283/geo/**shadow.json**](https://racemap.com/api/events/61a2055b10cacc0001302283/geo/shadow.json)
{% endtab %}
{% endtabs %}

### Response

(\*) parameters related to splits, only

(\*\*) parameters related to POIs and splits

#### Geo element object

<table><thead><tr><th width="225.7583408476105">Field</th><th width="277.9718253321284">Description [unit]</th><th>Sample</th><th data-hidden>line</th></tr></thead><tbody><tr><td><code>racemapType</code></td><td>Definition of geo element</td><td><code>"track"</code> or <code>"split"</code> or <code>"poi"</code></td><td>3</td></tr><tr><td><code>eventId</code></td><td>Unique id of tracking map</td><td><code>"61a2055b10cacc0001302283"</code></td><td>4</td></tr><tr><td><code>name</code></td><td>Name of geo element provided in map settings</td><td><code>"Track 0"</code> or <code>"Marathon"</code></td><td>5</td></tr><tr><td><code>shortName</code> **</td><td>Short name of POI or split</td><td><code>"VP01"</code> or <code>"Cam2"</code></td><td></td></tr><tr><td><code>color</code></td><td>Color of geo element, hex code</td><td><code>"#ffffff"</code> or <code>"#32c4f7"</code></td><td>6</td></tr><tr><td><code>hidden</code></td><td>Visibility in tracking map</td><td><code>true</code> or <code>false</code></td><td>7</td></tr><tr><td><code>icon</code> **</td><td>URL of image</td><td><code>"https://static-cdn.racemap.com/img/map-icons/finish-01_borderless.svg"</code></td><td></td></tr><tr><td><code>timekeeping</code> *</td><td>Split in leaderboard or geofence in */time API</td><td><code>true</code> or <code>false</code></td><td></td></tr><tr><td><code>readerIds</code> **</td><td>IDs of decoders, arrey of strings</td><td><code>[]</code> or <code>[ "U001", "U003" ]</code></td><td></td></tr><tr><td><code>newSport</code> *</td><td>Start of a new segment, definition of type of sport</td><td><code>"running"</code></td><td></td></tr><tr><td><code>lineStringId</code> *</td><td>Id of the track to which this split is associated.</td><td><code>"64514d7ec3ab09659eb29e71"</code></td><td></td></tr><tr><td><code>coordinateIndex</code></td><td>Number of the coordinate of the track to which the split is assigned.</td><td><code>253</code> or <code>12</code></td><td></td></tr><tr><td><code>creatorId</code></td><td>User id of the event host</td><td><code>"51782b0cd37706937400000d"</code></td><td>8</td></tr><tr><td><code>length</code></td><td>Length of the track in km</td><td><code>99.50403889646452</code></td><td>10</td></tr><tr><td><code>pointCount</code></td><td>Number of points of the track</td><td><code>1192</code></td><td>11</td></tr><tr><td><code>offset</code> *</td><td>Length [m] on which the split is set on the track</td><td><code>19029.765609128</code></td><td></td></tr><tr><td><code>resetSpeed</code> **</td><td>Velocity [km/h] used for prediction</td><td><code>null</code> or <code>1.5</code> or <code>60</code></td><td></td></tr><tr><td><code>minSpeed</code> **</td><td>Velocity [km/h] used for prediction</td><td><code>null</code> or <code>1.5</code> or <code>60</code></td><td></td></tr><tr><td><code>minSpeed</code> *</td><td>Velocity [km/h] used for prediction</td><td><code>null</code> or <code>1.5</code> or <code>60</code></td><td></td></tr><tr><td><code>oldId</code></td><td>An old reference to the geo element</td><td><code>"cf31ed00-d2a1-47c3-8306-fd55b09a1bb0"</code> or <code>"_wi57w51ay"</code></td><td>12</td></tr><tr><td><code>createdAt</code></td><td>Timestamp of when the element was added to the event in RACEMAP</td><td><code>"2021-09-10T03:04:07.020Z"</code> or <code>null</code></td><td>13</td></tr><tr><td><code>updaterId</code></td><td>Id of the user that updated the elment latest</td><td><code>"c001cafe15abad1deabada55"</code></td><td>14</td></tr><tr><td><code>updatedAt</code></td><td>Timestamp of latest update of the element</td><td><code>"2023-05-02T17:50:54.304Z"</code></td><td>9</td></tr><tr><td><code>id</code></td><td>Unique id of geo lement</td><td><code>"64514d7ec3ab09659eb29e71"</code></td><td></td></tr></tbody></table>

#### Geometry object

<table><thead><tr><th width="193.1078876281131">Field</th><th width="250.35876426050012">Description [unit]</th><th>Sample</th></tr></thead><tbody><tr><td><code>type</code></td><td>Definition of the geo element</td><td><code>"LineString"</code> or <code>"Point"</code></td></tr></tbody></table>

#### Coordinates array

| Description \[unit]                             | Sample                                  |
| ----------------------------------------------- | --------------------------------------- |
| Longitude, latitude, hight above sea level \[m] | `[ 13.704979999999978, 51.02677, 165 ]` |

{% code expandable="true" %}

```javascript
{
  "type": "FeatureCollection",
  "features": [
    {
      "properties": {
        "racemapType": "track",
        "eventId": "61a2055b10cacc0001302283",
        "name": "Track 0",
        "color": "#32c4f7",
        "hidden": false,
        "creatorId": "51782b0cd37706937400000d",
        "length": 99.50403889646452,
        "pointCount": 1192,
        "oldId": "cf31ed00-d2a1-47c3-8306-fd55b09a1bb0",
        "createdAt": "2023-05-02T17:50:54.228Z",
        "updaterId": "c001cafe15abad1deabada55",
        "updatedAt": "2023-05-02T17:50:54.304Z"
      },
      "type": "Feature",
      "geometry": {
        "type": "LineString",
        "coordinates": [
          [13.704979999999978, 51.02677, 165],
          [13.705195019584863, 51.026764818805184, 164],
          [13.705694405424758, 51.02675278541145, 163],
          [13.705086448148332, 51.02636026141142, 173],
          [13.705079999999953, 51.02636, 173]
        ]
      },
      "id": "64514d7ec3ab09659eb29e71"
    },
    {
      "properties": {
        "racemapType": "split",
        "hidden": true,
        "eventId": "61a2055b10cacc0001302283",
        "name": "START",
        "shortName": "",
        "color": "#36739a",
        "icon": null,
        "resetSpeed": null,
        "minSpeed": 1.5,
        "maxSpeed": 60,
        "timekeeping": false,
        "readerIds": [ "Start01", "Start03" ],
        "newSport": "running",
        "lineStringId": "64514d7ec3ab09659eb29e71",
        "coordinateIndex": 0,
        "creatorId": "51782b0cd37706937400000d",
        "updaterId": "51782b0cd37706937400000d",
        "createdAt": "2023-05-02T17:50:54.446Z",
        "updatedAt": "2025-01-27T12:20:36.771Z",
        "offset": 0,
        "oldId": "_wi57w51ay"
      },
      "type": "Feature",
      "geometry": {
        "type": "Point",
        "coordinates": [13.704979999999978, 51.02677, 165]
      },
      "id": "64514d7ec3ab09659eb29e78"
    },
    {
      "properties": {
        "racemapType": "split",
        "hidden": true,
        "eventId": "61a2055b10cacc0001302283",
        "name": "ZIEL",
        "shortName": "",
        "color": "#ffffff",
        "icon": "https://static-cdn.racemap.com/img/map-icons/finish-01_borderless.svg",
        "timekeeping": false,
        "readerIds": [],
        "newSport": "",
        "lineStringId": "64514d7ec3ab09659eb29e71",
        "coordinateIndex": 1191,
        "creatorId": "51782b0cd37706937400000d",
        "updaterId": "c001cafe15abad1deabada55",
        "createdAt": "2023-05-02T17:50:54.551Z",
        "updatedAt": "2023-05-02T17:50:57.512Z",
        "offset": 99504.03889646452,
        "oldId": "_9q5ec0nno",
        "resetSpeed": null,
        "minSpeed": 1.5,
        "maxSpeed": 60
      },
      "type": "Feature",
      "geometry": {
        "type": "Point",
        "coordinates": [13.705079999999953, 51.02636, 173]
      },
      "id": "64514d7ec3ab09659eb29e93"
    },
    {
      "properties": {
        "racemapType": "split",
        "hidden": false,
        "eventId": "61a2055b10cacc0001302283",
        "name": "VP1",
        "shortName": "",
        "color": "#ffffff",
        "icon": "https://static-cdn.racemap.com/img/map-icons/refreshment-food_borderless.svg",
        "timekeeping": true,
        "newSport": "",
        "lineStringId": "64514d7ec3ab09659eb29e71",
        "coordinateIndex": 292,
        "creatorId": "51782b0cd37706937400000d",
        "oldId": "_okhk7667m",
        "readerIds": [],
        "updaterId": "c001cafe15abad1deabada55",
        "createdAt": "2023-05-02T17:50:56.269Z",
        "updatedAt": "2023-05-02T17:50:56.269Z",
        "offset": 19029.765609128855,
        "resetSpeed": null,
        "minSpeed": 1.5,
        "maxSpeed": 60
      },
      "type": "Feature",
      "geometry": {
        "type": "Point",
        "coordinates": [13.806170000000066, 50.93263999999999, 342]
      },
      "id": "64514d8010e583b28d736c7d"
    },
    {
      "properties": {
        "minSpeed": 0.1,
        "maxSpeed": 360,
        "racemapType": "poi",
        "hidden": false,
        "eventId": "61a2055b10cacc0001302283",
        "name": "Danger",
        "shortName": "",
        "color": "#36739a",
        "description": "",
        "icon": "https://static-cdn.racemap.com/img/map-icons/black-spot_borderless.svg",
        "creatorId": "51782b0cd37706937400000d",
        "oldId": "Danger",
        "readerIds": [],
        "updaterId": "c001cafe15abad1deabada55",
        "createdAt": "2023-05-02T17:50:57.589Z",
        "updatedAt": "2023-05-02T17:50:57.589Z"
      },
      "type": "Feature",
      "geometry": {
        "type": "Point",
        "coordinates": [13.605496742105894, 51.094757189936146, 106]
      },
      "id": "64514d811186e2e551ee4c69"
    }
  ]
}
```

{% endcode %}


# \*/unified

API that unifies a lot of features from our other API's.

{% 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#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#splits) in the event's map settings with an activated "timekeeping" property.

<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><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: sum of straight lines between 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: segments covered on 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>speedSt</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 at <code>gapCalcTime</code>.</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>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>speedSt</code> value of the leader at <code>gapCalcTime</code>.</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>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>speedSt</code> value of the chaser at <code>gapCalcTime</code>.</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 took 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 timestamp of <code>resultTime</code> with the <code>speedSt</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>speedSt</code> value of the leader at <code>resultTime</code>.</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>speedSt</code> value of the chaser at <code>resultTime</code>.</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 took 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](/glossary#read) object

Does not provide all received [detections](/glossary#read) 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.

<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>


# Tools to extract live data

Poll specific parameters from \*/current API to show race data in real time. Handy tools to feed overlays for video production and web broadcasting.

* The grabber is an HTML file and runs in a browser tab.
* Adjust the grabber in an editor with the settings in the tables.
* The grabber pulls one specific parameter from the \*/current API.
* The \*/current API must be activated and switched on.
* Monochrome background.

{% content-ref url="/pages/-MZHPcWTCiAwX6xi9dt6" %}
[\*/current, location data](/api/current)
{% endcontent-ref %}

### Basic grabber

{% hint style="info" %}
[<mark style="color:blue;">**Download the basic grabber for your usage.**</mark>](https://drive.google.com/uc?id=14sVBD9RNkzpkP5FxbxPK01ZrGZzijrFD\&export=download)\
The file (grabCurrentAPI.html) is set to call a sample event with infinite real-time data.
{% endhint %}

{% tabs %}
{% tab title="deviceIds" %}
**Options 1 to 3:** With set `deviceIds` or with set `startNumbers` or with set `showLeaders` the grabber shows the parameter for one or for more specific devices instead of the list with all devices.
{% endtab %}

{% tab title="refDeviceId" %}
**Options 4 and 5:** Set `refDeviceId` or `refStartNumber` for calculation with reference device instead of the leader device.\
`gapAverage`, `gap`, `gapChase` and `gapDistance` are calculated for the leader (device with smallest `toFinish`) by default.
{% endtab %}
{% endtabs %}

<figure><img src="/files/hZrjGlURQ6UnBKeDOQns" alt=""><figcaption><p><code>deviceIds = "6336f41309be310001a58976"</code> to show one participant only</p></figcaption></figure>

<figure><img src="/files/Cin7XzK8CnYN5nx41uM8" alt=""><figcaption><p><code>refDeviceId = "6336f41309be310001a58971"</code> to show <code>gapDistance</code> to team PLAN:LOS</p></figcaption></figure>

<figure><img src="/files/GfnIRWzy0shDvtJvl091" alt=""><figcaption><p>Without <code>deviceIds</code>: list of all participants</p></figcaption></figure>

<table><thead><tr><th width="191">Field</th><th>Description [unit]</th><th>Sample</th></tr></thead><tbody><tr><td><code>eventId</code></td><td>Id of the tracking map<br>Add optional query parameters, also</td><td><code>"6336f41309be310001a5894b"</code> or<br><code>"6336f41309be310001a5894b?interpolation=false&#x26;currentSpeedDuration=60"</code></td></tr><tr><td><code>outputData</code></td><td>Parameter to be shown in browser tab</td><td><code>"gapAverage"</code> or <code>"speed"</code></td></tr><tr><td><code>textBehind</code></td><td>Add text behind the unit</td><td><code>"Distance to go"</code> or <code>"🏁"</code></td></tr><tr><td><code>withStarterName</code></td><td>Show or hide the name of the participant</td><td><code>true</code> or <code>false</code></td></tr><tr><td><code>withStartNumber</code></td><td>Show or hide the race number of the participant</td><td><code>true</code> or <code>false</code></td></tr><tr><td><code>pollingRate</code></td><td>Time beween polling in [s]</td><td><code>2</code> or <code>15</code></td></tr><tr><td><code>deviceIds</code></td><td><strong>Option 1</strong>: ids of one or more devices, values of these devices only are pulled, <code>[]</code> shows all devices</td><td><code>[]</code> or <code>["6336f41309be310001a58976"]</code> or <code>["6336f41309be310001a58975", "6336f41309be310001a58973"]</code></td></tr><tr><td><code>startNumbers</code></td><td><strong>Option 2</strong>: Race numbers of one or more devices, values of these devices only are pulled, <code>[]</code> shows all devices</td><td><code>[]</code> or <code>["051"]</code> or <code>["051", "050"]</code></td></tr><tr><td><code>showLeaders</code></td><td><strong>Option 3</strong>: Number of shown leading devices determined of <code>fromStart</code>; <code>0</code> shows all devices</td><td><code>0</code> or <code>1</code> or <code>5</code> or <code>10</code></td></tr><tr><td><code>refDeviceId</code></td><td><strong>Option 4</strong>: id of a reference for calculation of <code>gapAverage</code>, <code>gap</code>, <code>gapChase</code> and <code>gapDistance</code></td><td><code>"6336f41309be310001a58977"</code></td></tr><tr><td><code>refStartNumber</code></td><td><strong>Option 5</strong>: Bib of a reference for calculation of <code>gapAverage</code>, <code>gap</code>, <code>gapChase</code> and <code>gapDistance</code></td><td><code>"053"</code></td></tr></tbody></table>

#### Set imperial units

<figure><img src="/files/boO4lnffIRV4bEvsfXBm" alt=""><figcaption><p>Open grabber tool in an editor</p></figcaption></figure>

In order to show `speed` values as miles per hour replace line 50 with:

```html
speed: { value: 2.2369356, unit: "mph", sorting: "DESC" },
```

In order to show `speedRaw` values as miles per hour replace line 51 with:

```html
speedRaw: { value: 2.2369356, unit: "mph", sorting: "DESC" },
```

In order to show `fromStart` values as miles replace line 52 with:

```
fromStart: { value: 0.000621371, unit: "mile", sorting: "DESC" }
```

In order to show `toFinish` values as miles replace line 53 with:

```
toFinish: { value: 0.000621371, unit: "mile", sorting: "DESC" }
```

### Drafting tool

{% hint style="info" %}
[<mark style="color:blue;">**Download the drafting tool for your usage.**</mark>](https://drive.google.com/uc?id=1HHA8DAGreR5sLF4W3P9DXcnitFt5_LQV\&export=download)\
The file (grabCurrentAPIDrafting.html) is set to call a sample event with infinite real-time data.
{% endhint %}

* The table sorts all devices in ascending order according to the `toFinish` parameter.
* "To previous"-column shows the distance to the device that moves ahead.
* "Draft time"-column starts counting the time when the device is moving within the draft zone (`alertValue` in \[m] set distance to the device ahead).
* "Drafts"-column detects a draft when drafting takes longer than the set `alertTime` in \[s].
* Hover over the number of drafts for additional information.

<figure><img src="/files/6dJ28RMh2EINefPWovq8" alt=""><figcaption><p>Christoph overtakes Konrad monitored by the drafting tool. At 14:27:31 Christoph was moving for 44s in the draft zone behind Konrad.</p></figcaption></figure>

### Spotter tool

{% hint style="info" %}
[<mark style="color:blue;">**Download the spotter tool for your usage.**</mark>](https://drive.google.com/uc?id=1gKwfzmfXn-VVGpws1mDMW5wPjTuUinHL\&export=download)\
The file (spotter.html) is set to call a sample event with infinite real-time data.
{% endhint %}

* Define up to three different spots (distance from start in m).
* The table sorts participants in the sensitive range (`rangeBeforeSpot` and `rangeAfterSpot`) coming closer to the spot.

<figure><img src="/files/1NRCnGB3LZOBxQn6BinG" alt=""><figcaption><p>Real-time information from anywhere on the race-course e.g. for the speaker.</p></figcaption></figure>


# Authentication

Requests to the RACEMAP APIs must include a valid API token which serves as a secure key.

The token authenticates you to the RACEMAP platform to **retrieve** your data from or **direct** your data to RACEMAP. Requests without a valid token will be rejected - or, in the case of data‐retrieval calls, blocked.

### Obtain your API tokens

* Sign in to your RACEMAP account <https://racemap.com/auth/login>.
* Navigate to your account settings <https://racemap.com/admin/account>.
* Scroll to the API Tokens section and click the "Add Token"-button.
* Copy and store the token secure. You will not be able to view it again once you leave the page

<figure><img src="https://docs.racemap.com/~gitbook/image?url=https%3A%2F%2F1672210197-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252F-LSRNxaH2Ju9Flr7JhJD%252Fuploads%252Feh2oevZ1yFEeuxGyME2q%252Fimage.png%3Falt%3Dmedia%26token%3D89adbbcc-7548-412b-9471-73aee00280bc&#x26;width=768&#x26;dpr=4&#x26;quality=100&#x26;sign=937148c6&#x26;sv=2" alt=""><figcaption><p>Manage your API tokens in your RACEMAP account</p></figcaption></figure>

### Using API token

Sample to request participants from your event:

```
curl --location 'https://racemap.com/api/events/:eventId/starters' \
--header 'Authorization: Bearer <API_TOKEN>'
```


# Auto-pausation

Data APIs work while the datafeed module is active. Two hours after the event's end time, RACEMAP pauses active APIs automatically to prevent unintentional usage and costs.

### When do data APIs work?

The four APIs - [\*/current](/api/current), [\*/distance](/api/distance), [\*/times](/api/times), and [\*/ranks](/api/ranks) - are available for your event when the data API module is activated in the API settings for each event.

If the API add-on is not activated or the APIs are manually paused, it returns an error indicating the feed is paused, and requests are rejected.

### Auto-pausing after the event has ended

Two hours after the event's end time, RACEMAP automatically pauses the API module. The auto-pausation protects from API usage and associated costs once the event has finished. The auto-pausation is triggered on the first API request two hours after the event's end time.

{% hint style="info" %}
[**Live replay events are excluded from auto-pausation:**](/api#live-replay-loop) If the event is configured as a live loop event, its APIs are not automatically paused.
{% endhint %}

### Re-activating APIs after pausation

You can manually activate the APIs again after auto-pausation — for example, for data evaluation and analysis after the event:

1. Open the event in RACEMAP
2. Go to Data API settings
3. Activate the datafeed again

After re-activating the APIs respond immediately, and the auto-pausation doesn't trigger again for the same event end time.

Auto-pausation resets with a new event's end time. That way, you can set the event's end time to the future, and two hours after the new end time, the APIs are automatically paused again.


# Post-race analysis

Replay and explore finished events with the Current API Analyser. Compare participants, gaps, speeds and ETAs after the race — no code required.

After an event has finished, you can replay and explore its data with the **Current API Analyser**. The tool calls the [\*/current API](/api/current) over a time window you choose and lets you compare participants, gaps, speeds and ETAs — no code required.

{% embed url="<https://racemap.com/current-api-analyser/100km-duathlon-2026?refStarterId=69f357aee863ca7e7bfc6865&starterId=69f33559fd27920e359dad0e&endAt=2026-05-02T15%253A00%253A00.000%252B02%253A00&beginAt=2026-05-02T08%253A00%253A00.000%252B02%253A00&autoFetch=true>" %}

{% hint style="info" %}
[<mark style="color:blue;">**Open the Current API Analyser — 100 km Duathlon 2026 sample**</mark>](https://racemap.com/current-api-analyser/100km-duathlon-2026?refStarterId=69f357aee863ca7e7bfc6865\&starterId=69f33559fd27920e359dad0e\&endAt=2026-05-02T15%253A00%253A00.000%252B02%253A00\&beginAt=2026-05-02T08%253A00%253A00.000%252B02%253A00\&autoFetch=true)\
Play around with a real finished race: change the reference participant, the time window and the parameters.
{% endhint %}

### Video walkthrough

{% embed url="<https://youtu.be/B0QLp9wi-F8>" %}
Post-race analysis with the RaceMap Current API — compare participants, read gap distance and gap time, and find the exact moment of maximum lead.
{% endembed %}

### What you can change

The analyser is driven by the URL parameters, so you can bookmark or share any view you set up:

* `beginAt` / `endAt` — the start and end of the analysis time window (ISO timestamps). Narrow it to a single lap, or widen it to the whole race.
* `starterId` — the participant to compare against the reference.
* `refStarterId` — the reference participant the gaps are calculated against (`gap`, `gapAverage`, `gapChase`, `gapDistance`).


# Import participant data

Synchronize participants' data from your timekeeping system or online registration with the events in your RACEMAP account.

* Keep the participant list up-to-date and prevent mistakes.
* Use your system to add tracking devices (GPS trackers, transponders, decoders, track boxes) to specific athletes. Synchronize the tracking devices with RACEMAP.
* Manage participant information such as name, race number, key, status (DNF, DSQ, DNS), start- and finish time, and much more.

<figure><img src="/files/dEXnVQQ00Ekou5fGRxAj" alt=""><figcaption><p>Import athletes from various sources in the participants section >> import/export</p></figcaption></figure>

![Organize athletes for live tracking](/files/Gg2PA6goGXzw980AH2bF)

{% content-ref url="/pages/-LXTN05KRuN3LHs0iY6u" %}
[Import with API, automatically](/api-import-and-export-data/import-basics)
{% endcontent-ref %}

{% content-ref url="/pages/-MBKork\_GNvfGpnpwShV" %}
[Import with CSV file](/api-import-and-export-data/import-data-from-csv)
{% endcontent-ref %}

### Import and visibility rules

Import of RACEMAP tracking keys: Only those keys are imported, that belong to this RACEMAP event.

To show a participant in the visualization its device id must be known. The visibility of different devices depends on the activation of predictive tracking.

| Device id               | Predictive tracking |                    NO predictive tracking                    |
| ----------------------- | :-----------------: | :----------------------------------------------------------: |
| IMEI of GPS tracker     |          ✔️         |                              ✔️                              |
| Id of tracking app      |          ✔️         |                              ✔️                              |
| Id of uploaded activity |          ✔️         |                              ✔️                              |
| Transponder code        |          ✔️         | <p>➖<br>participants with a transponder id are not shown</p> |
| No device id            |          ➖          |                               ➖                              |


# Import with API, automatically

Import and synchronize participants- and device data with your events in RACEMAP to automate processes.

* Synchronization of participants' data with tracking map every 1 min.
* Synchronization until three days after the end time of the event.
* Import additional information such as tracking key, color, tags, start- and finish time, and IMEI of your tracking device.
* The `importId` is the anchor for the synchronization of a specific participant.
* A new `importId` creates a new participant in the RACEMAP event.
* Removal of `importId` from synchronization deletes the corresponding participant in the RACEMAP event.

{% content-ref url="/pages/-LTq5TdE6GKt2S6dgesz" %}
[Generic import](/api-import-and-export-data/import-basics/metadata-api)
{% endcontent-ref %}

{% content-ref url="/pages/-LTh-oAm96bieBZVeffZ" %}
[RACE RESULT import](/api-import-and-export-data/import-basics/metadata-import-via-rr)
{% endcontent-ref %}


# Generic import

Import and synchronize participant- and device data from your side.

Paste the URL of your hosted data to synchronize participants and devices with the event in your RACEMAP account. Import data from multiple online files, also. The generic import checks the format of your hosted data and replies to which parameters are imported.

![Past URLs of online sources to import the participants into Racemap event](/files/jZlo2iKJbfy7SLufXZ73)

<figure><img src="/files/HVYirjup32ggtbyZfmiR" alt=""><figcaption><p>Detailed description of errors when import fails for specific entries</p></figcaption></figure>

{% hint style="success" %}
Test the API with your RACEMAP event. Use the sample files.

* json sample file: <https://static-cdn.racemap.com/importSamples/GenericImportSampleArray.json>
* xml sample file: <https://static-cdn.racemap.com/importSamples/GenericImportSample.xml>
  {% endhint %}

### Format of import data

<table data-full-width="false"><thead><tr><th width="188">Field</th><th width="311">Description</th><th width="294">Sample</th><th data-hidden></th></tr></thead><tbody><tr><td><code>importId</code></td><td>Required user-defined ID, unique within Racemap event, a new <code>importID</code> creates a new participant</td><td><code>"import_DWBK"</code> or <code>"03487"</code> or <code>"1sl71kaut2"</code></td><td></td></tr><tr><td><code>name</code></td><td>Name</td><td><code>"Max"</code> or <code>"🔥"</code> or <code>"40012"</code></td><td></td></tr><tr><td><code>startNumber</code></td><td>Bib number</td><td><code>"40012"</code> or <code>"🔥"</code> or <code>"Max"</code></td><td></td></tr><tr><td><code>startTime</code></td><td>Time in UTC of first possible geolocation, earlier location data is ignored for visualization and leaderboard</td><td><code>"2022-01-24T15:00:00.000Z"</code></td><td></td></tr><tr><td><code>endTime</code></td><td>Time in UTC of last possible geolocation, later location data is ignored for visualization and leaderboard</td><td><code>"2022-01-24T23:00:00.000Z"</code></td><td></td></tr><tr><td><code>key</code></td><td>No import, if value of <code>key</code> does not belong to Racemap event</td><td><code>"3Z2GPX"</code></td><td></td></tr><tr><td><code>markerColor</code></td><td>Marker color in visualization, hex code</td><td><code>"#023d10"</code></td><td></td></tr><tr><td><code>tags.age</code> or<br><code>tags.sex</code></td><td>Attributes to filter participants eg. age group or nation, format</td><td><code>"35"</code> or <code>"male"</code> or <code>"Island"</code></td><td></td></tr><tr><td><code>times.start</code></td><td>Timestamp in UTC of start detection, considered in the leaderboard; <code>startTime</code> used instead, if import doesn't contain <code>times.start</code></td><td><code>"2022-01-24T15:25:10.000Z"</code></td><td></td></tr><tr><td><code>times.end</code></td><td>Timestamp in UTC of finish detection, considered in the leaderboard; <code>endTime</code> used instead, if import doesn't contain <code>times.end</code></td><td><code>"2022-01-24T22:53:45.000Z"</code></td><td></td></tr><tr><td><code>times.5km</code> or <code>times.loop</code></td><td>Timestamp in UTC of read from split</td><td><code>"2022-01-24T20:17:24.000Z"</code></td><td></td></tr><tr><td><code>device.id</code></td><td>IMEI of GPS unit or transponder ID</td><td><code>"4106050246"</code> or <code>"RRPing_ZDKAR32"</code> or <code>"RRPing_70761"</code></td><td></td></tr><tr><td><code>device.class</code></td><td>Device class</td><td><code>"Mobile"</code> or <code>"Tracker"</code> or <code>"Upload"</code> or <code>"Transponder"</code> or <code>"null"</code></td><td></td></tr><tr><td><code>device.type</code></td><td>Device type</td><td><code>"GL320-MG"</code> or <code>"GL300"</code> or <code>"LK106"</code> or <code>"active"</code> or <code>"passive"</code> or <code>"null"</code></td><td></td></tr></tbody></table>

{% tabs %}
{% tab title="json" %}
{% code lineNumbers="true" %}

```javascript
[
  {
    "importId": "UniqueImportID_0",
    "name": "Petra Pan Minimal",
    "startNumber": "A1206",
    "tags.age": "25",
    "tags.sex": "w"
  },
  {
    "importId": "UniqueImportID_1",
    "name": "Peter Pan With Color",
    "startNumber": "A1207",
    "markerColor": "#4d79ff",
    "tags.age": "35",
    "tags.sex": "m"
  },
  {
    "importId": "UniqueImportID_3",
    "name": "Peter Pan With Tracker and specific type/class",
    "startNumber": "A1209",
    "device.class": "Tracker",
    "device.type": "Gl300",
    "device.id": "001111112222223"
  },
  {
    "importId": "UniqueImportID_4",
    "name": "Peter Pan With Times",
    "startNumber": "A1210",
    "times.start": "2020-04-24T14:30:06.708Z",
    "times.end": "2020-04-24T15:30:06.708Z"
  },
  {
    "importId": "UniqueImportID_4",
    "name": "Peter Pan With Start and End Times",
    "startNumber": "A1210",
    "startTime": "2020-04-25T14:30:06.708Z",
    "endTime": "2020-04-25T15:30:06.708Z"
  }
]
```

{% endcode %}
{% endtab %}

{% tab title="xml" %}

<pre class="language-xml" data-line-numbers><code class="lang-xml">&#x3C;root>
  &#x3C;starters>
<strong>    &#x3C;importId>UniqueImportID_0&#x3C;/importId>
</strong>    &#x3C;name>Petra Pan Minimal&#x3C;/name>
    &#x3C;startNumber>A1206&#x3C;/startNumber>
    &#x3C;tags>
       &#x3C;age>25&#x3C;/age>
       &#x3C;sex>w&#x3C;/sex>
    &#x3C;/tags>
  &#x3C;/starters>
<strong>  &#x3C;starters>
</strong>    &#x3C;importId>UniqueImportID_1&#x3C;/importId>
    &#x3C;name>Peter Pan With Color&#x3C;/name>
    &#x3C;startNumber>A1207&#x3C;/startNumber>
    &#x3C;markerColor>#4d79ff&#x3C;/markerColor>
    &#x3C;tags>
<strong>      &#x3C;age>35&#x3C;/age>
</strong>     &#x3C;sex>m&#x3C;/sex>
    &#x3C;/tags>
  &#x3C;/starters>
  &#x3C;starters>
    &#x3C;importId>UniqueImportID_2&#x3C;/importId>
    &#x3C;name>Peter Pan With Tracker&#x3C;/name>
    &#x3C;startNumber>A1208&#x3C;/startNumber>
    &#x3C;devices>
      &#x3C;class>Tracker&#x3C;/class>
      &#x3C;type>Gl300&#x3C;/type>
      &#x3C;id>001111112222223&#x3C;/id>
    &#x3C;/devices>
  &#x3C;/starters>
  &#x3C;starters>
    &#x3C;importId>UniqueImportID_3&#x3C;/importId>
    &#x3C;name>Peter Pan With Times&#x3C;/name>
    &#x3C;startNumber>A1209&#x3C;/startNumber>
    &#x3C;times>
      &#x3C;start>2020-04-24T14:30:06.708Z&#x3C;/start>
      &#x3C;end>2020-04-24T15:30:06.708Z&#x3C;/end>
      &#x3C;loop>2020-04-24T15:15:06.708Z&#x3C;/loop>
    &#x3C;/times>
  &#x3C;/starters>
  &#x3C;starters>
    &#x3C;importId>UniqueImportID_4&#x3C;/importId>
    &#x3C;name>Peter Pan With Start and End Times&#x3C;/name>
    &#x3C;startNumber>A1210&#x3C;/startNumber>
    &#x3C;startTime>2020-04-25T14:30:06.708Z&#x3C;/startTime>
    &#x3C;endTime>2020-04-25T15:30:06.708Z&#x3C;/endTime>
  &#x3C;/starters>
&#x3C;/root>
</code></pre>

{% endtab %}
{% endtabs %}

### Filter input by tag

You can filter the incoming participants by a single tag category. To achieve this, activate the filtering option using the filter symbol. Subsequently, select the category and the specific tag values to be imported.

<figure><img src="/files/YBbmsL2KFW8kantvuB0t" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
By default, we import every participant who does not have the selected filter category. To prevent this, you must assign a tag to the participant and set the value to `none`, for example.
{% endhint %}

### RACE RESULT lists

Use predefined lists to import and synchronize participants and devices into Racemap within seconds.

{% hint style="info" %}
Download templates\
\
[**Download full sample**](https://drive.google.com/uc?id=1LnXjkS0P7A7J0AOTE914Qjaa1n3xwBZi\&export=download) with `importId`, `name`, `startNumber`, `markerColor`, `tags.age`, `device.id`, `device.class`, `device.type`, `times.start`, `times.loop`, `times.finish` :\
\
[**Download minimal sample**](https://drive.google.com/uc?id=1iw1HUnHUy6XXIe_KaWvOfMZcXPK3hn0h\&export=download) with `importId`, `name`, `startNumber`, `markerColor`, `tags.age`, `device.id`, `times.start`, `times.finish` :
{% endhint %}

**Upload template file**

Upload the list template in RACE RESULT, Lists, Import icon

<figure><img src="/files/na3YFZGs3mCcljNNpccB" alt=""><figcaption></figcaption></figure>

The new "List Template full" is shown under Lists, Participants.

<figure><img src="/files/eDUifQIjf8LxQOYrKw2n" alt=""><figcaption></figcaption></figure>

**Activate access**

Enable the access to the list in Basic Settings, Access Rights.

* Check the "Active" field
* Select "List" in Type field
* Select the "List Template full" list in Details field
* Select JSON
* Copy the link

<figure><img src="/files/DxOmBeCzgONTjeKoAtU4" alt=""><figcaption></figcaption></figure>

**Past the link**

Past the link in RACEMAP, Generic Import field

<figure><img src="/files/2mjA1F7KXD7erX9zVAKB" alt=""><figcaption></figcaption></figure>


# RACE RESULT import

Synchronize participants data in your RACEMAP events with RACE RESULT Simple API. Use the import for automatization.

Go to participants settings in your RACEMAP event and open the import/export tab. Paste the RACE RESULT event id or the URL of the access file. RACEMAP checks the access and provides feedback. Select the contests for synchronization with your event RACEMAP.

<figure><img src="/files/DT4iV4OL8zZo9w36SjZ0" alt=""><figcaption><p>Participants settings, Import</p></figcaption></figure>

{% tabs %}
{% tab title="Event ID" %}

<figure><img src="/files/A8YoKCFoEb199xlRtu4N" alt=""><figcaption><p>Synchronize participants from RACE RESULT with the event id</p></figcaption></figure>
{% endtab %}

{% tab title="Event URL" %}

<figure><img src="/files/pfZYsDHL2lIJmX80a6fZ" alt=""><figcaption><p>Synchronize participants from RACE RESULT with the URL of the access file</p></figcaption></figure>
{% endtab %}
{% endtabs %}

{% hint style="info" %}
Multi-stage events with one participant file in RACE RESULT: To prevent overwriting start- and finish reads in finished stages with data from the running stage, deactivate the synchronization in finished stages.
{% endhint %}

## Simple API

To let RACEMAP query participant data go to Main Window, Simple API, and select Racemap access.

<figure><img src="/files/HTDpKs8Rce17HmYaomie" alt=""><figcaption><p>Main Window, Simple API, Racemap access</p></figcaption></figure>

{% hint style="info" %}
Simple API must provide the parameters:

* `ID` in Id field
* `Contest`

If `Id` or `Contest` parameter are missing the participants arn't pulled to RACEMAP.
{% endhint %}

<figure><img src="/files/qKS99c8n74g46uLu5P8F" alt=""><figcaption><p>Simple API</p></figcaption></figure>

* `ID` must be unique within each contest.
* `ID` is the identifier to address participant information in RACEMAP when synchronizing with RACE RESULT.
* A new `ID` creates a new entry in the event in RACEMAP.
* If one `ID` is removed then the corresponding entry is deleted in RACEMAP.
* Timestamps in Start- and Finish fields in UTC format: ISO 8601 <https://en.wikipedia.org/wiki/ISO_8601>
* Timestamps in Start- and Finish fields set the First- and the Last Time of the participants in RACEMAP, and directly impact the visibility of devices in the tracking map.
* The fields Age, Sex, Club, Nationality, and Status are imported as tags into RACEMAP participant list.

Parameters of the simple API displayed in tracking map: `RaceNr`, `Firstname`, `Lastname`, `Status`, `Age`, `Sex`, `Club` and `Nationality`.

<figure><img src="/files/QWDnPRExkrV0mCyAJP3r" alt=""><figcaption><p>Age, Sex, Club and Nationality as tags in the tracking map</p></figcaption></figure>

### Transponder1 field

Adapt the Transponder1 field for the transponder id of passive- (`Bib`) or active timing (`Transponder1`) or use the `TransponderInChipFile` argument.

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

<figure><img src="/files/pDkirpyeA8zNFxlQGnw9" alt=""><figcaption><p>Transponder1 field: <code>Bib</code> for transponder id of passive chips</p></figcaption></figure>
{% endtab %}

{% tab title="Transponder1" %}

<figure><img src="/files/Nzcw5B6ol0Hu2Y2MD9Tr" alt=""><figcaption><p>Transponder1 field: <code>Transponder1</code> for transponder id of active chips</p></figcaption></figure>
{% endtab %}

{% tab title="TransponderInChipFile" %}

<figure><img src="/files/0qfzDGh4Akzj1IuuLZtp" alt=""><figcaption><p>Transponder1 field: <code>TransponderInChipFile</code> for transponder id</p></figcaption></figure>
{% endtab %}
{% endtabs %}

When conducting predictive tracking, you can hide participants from visualization depending on their status. The if function in the Transponder1 field removes the transponder id of participants with DNS, DSQ, or DNF status.

{% code overflow="wrap" %}

```
if([StatusText]="DNS" OR [StatusText]="DSQ" OR [StatusText]="DNF";"";[Bib])
```

{% endcode %}

Prediction: Passings from timekeeping for live extrapolation of participants' location and speed.

{% content-ref url="/pages/-M3ehfiMPavdV-qchvwu" %}
[Predictive tracking with reads from race timing](/prediction)
{% endcontent-ref %}

### Custom field and User defined fields

Use the custom field in the simple API to flexibly import additional parameters:

* [**\[Color\]**](#color) to specify markers in the visualization with different colors,
* [**\[Key\]**](#key) to enable live tracking with Racemap App,
* [**\[IMEI\]**](#imei) ids of GPS trackers,
* [**\[APPID\]**](#appid) and
* [**\[TAGS\]**](#tags) additional tags to filter participants in the visualization and in the leaderboard.

```
[Color]&";"&[Key]&";"&[IMEI]&";"&[TAGS]
```

<figure><img src="/files/qTFOSutQoAkfeYqGqyff" alt=""><figcaption><p>Simple API, custom field</p></figcaption></figure>

Go to Main Window, Participants Data, User Defined Fields to define the arguments in the custom field.

<figure><img src="/files/S26iMJESyMa1l8stvTt2" alt=""><figcaption><p>Main Window, Participant Data, User Defined Fields</p></figcaption></figure>

#### **\[Color]**

The color parameter sets various colors of the markers in the tracking map and needs to be defined as [color hex code](https://www.color-hex.com/).

Color depending on contests: Switch function in user defined fields. If Contest.Name of a participant is "Gravel" then color is "#F2F2F2". If Contest.Name is "MTB"color is "#04B404".

{% code overflow="wrap" %}

```
switch([Contest.Name]="Gravel";"#F2F2F2";[Contest.Name]="MTB";"#04B404")
```

{% endcode %}

<figure><img src="/files/6m7kZxIeHq70gomvcLkz" alt=""><figcaption><p>User defined fields: Switch function, marker color depending on the contest</p></figcaption></figure>

Color depending on gender: Translate function in user defined fields: Set the first color ("#F2F2F2") for female and the second color ("#000000") for male.

```
translate([gender];"#F2F2F2";"#000000")
```

![User defined fields: Translate function, marker color depending on gender](/files/stfXqOaiZ37h2wYnQ235)

<figure><img src="/files/VWw0SyJBCgYTkzgNixtq" alt=""><figcaption><p>Different colors depending on gender</p></figcaption></figure>

#### **\[Key]**

Tracking keys connect the RACEMAP App (and custom tracking apps) to enable live tracking for a specific event. You can use keys to offer live tracking as an optional purchase in your online registration form, allowing all participants to join live tracking.

{% content-ref url="/pages/-LXLDfyEEiuGO8RHSmWq" %}
[Keys and passcode](/apps/tracking/keys)
{% endcontent-ref %}

Assign keys to participants.

![User defined fields: Assign one key to every participant, paste keys from Racemap](/files/RrnZshtrg2on81HrghXo)

The switch function in the Key field assigns one key to every participant.

{% code overflow="wrap" %}

```
switch([Bib]>0 AND [Bib]<=500;[Key_1];[Bib]>500 AND [Bib]<=1000;[Key_2];[Bib]>1000 AND [Bib]<=1500;[Key_3])
```

{% endcode %}

Choose function in Key\_1 field:

* Paste keys from Racemap of the corresponding Racemap event.\
  `choose([Bib];"xxxxxx";"yyyyyy";"zzzzzz";...)`
* Up to 500 keys fit in one user defined field.
* For more than 500 participants in the contest set up a second field Key\_2 and so on.\
  `choose([Bib]-500;"XXXXXX";"YYYYYY";"ZZZZZZ";...)`

Online registration with optional live tracking through Racemap App e.g. when the event wants to sell live tracking. Go to Main Window, Participants Data, Additional Fields, and add a checkbox "App".

![Additional fields: Checkbox to let participants agree to live tracking](/files/2pLcuNRmntSEsqBRikFW)

![User defined fields: Link to the checkbox and paste keys](/files/8XON7XWpALk0N5Y1mrVA)

If function in Key field: If the participant checks "Agree to live tracking with Racemap App" one key is assigned to this participant.

{% code overflow="wrap" %}

```
if([App]=1;switch([Bib]>0 AND [Bib]<=500;[Key_1];[Bib]>500 AND [Bib]<=1000;[Key_2];[Bib]>1000 AND [Bib]<=1500;[Key_3]))
```

{% endcode %}

#### \[IMEI]

You own GPS trackers or you have rented trackers for an event. You can assign the devices to participants in RACE RESULT, directly. That way the participants data and the tracker information are synchronized with your event in RACEMAP.

<figure><img src="/files/T2sT7kQHd9sRukqgpgEH" alt=""><figcaption><p>Simple API</p></figcaption></figure>

#### \[APPID]

For live tracking with RACEMAP App of an event with stages it can be useful to assign the App-Id to the participant information in RACE RESULT. Before the 1st stage, the participants redeem their keys in RACEMAP App. The specific App-Id of one participant becomes known and can be queried with the starters API. This way you can import the participant information including the App-Id for the subsequent stages.

{% content-ref url="/pages/-M\_zgpFYgo28IJBo4zVF" %}
[\*/starters, athlete data](/api/participants)
{% endcontent-ref %}

{% hint style="info" %}
A participant in RACEMAP, which already has an App-Id, can't get another device id (like a different App-Id, IMEI, or Transponder-Id). It is not possible to delete, refresh, or overwrite an App-Id of a participant through the RACE RESULT import.

To address a different device id you have to import the same participant information with a new import id, which creates a new participant on RACEMAP side.
{% endhint %}

<figure><img src="/files/qYqf5fOvha1wuoaVPoN0" alt=""><figcaption><p>additional APPID field</p></figcaption></figure>

<figure><img src="/files/IQ0mfr1NXkA1CAcj6vj8" alt=""><figcaption><p>add the App-Id in the simple API</p></figcaption></figure>

#### \[TAGS]

Synchronize additional information about categories such as sponsor, mixed team, ... in order to filter participants in the visualization and in the leaderboard. Go to Main Window, Participants Data, Additional Fields, and add the test fields "Team" and "Sponsor".

<figure><img src="/files/kcc3BgkAcf5WlTpeXyVP" alt=""><figcaption><p>Additional fields: "Team" and "Sponsor" text fields for additional tags</p></figcaption></figure>

<figure><img src="/files/Oyb6R0eSf37aksFp8Uv6" alt=""><figcaption><p>User defined fields: Insert team and sponsor tags</p></figcaption></figure>

Argument in TAGS field of the user defined fields to insert the two tags `Team` and `Sponsor` of the participant.

```
"TAGS"&"Team:"&[Team]&",Sponsor:"&[Sponsor]
```

## Best-practice samples

### Assigning GPS devices to participants

Efficiently connecting GPS trackers with participant information is essential for a smooth deployment process. To minimize errors and streamline operations, staff members assigning tracking devices should not have to manually read and enter the long IMEI numbers of the trackers.

#### **Automatically assign GPS trackers to participants using bib number**

Before each event, prepare your GPS trackers with stickers of the bib numbers.

Go to Main Window, Participants Data, User Defined Fields, and add the field `IMEI`. Insert the bib number that is attached to the tracker and the corresponding IMEI number of the device.

<figure><img src="/files/wbHuWqcRBmPQiDZG74c1" alt=""><figcaption></figcaption></figure>

The code sample inserts five GPS devices with bib numbers into RACE RESULT.

```
"IMEI" & switch(
        [Bib]="1"; 
        "860201061635184"; 
        [Bib]="2"; 
        "860201061637206"; 
        [Bib]="3"; 
        "860201061636521"; 
        [Bib]="4"; 
        "860201061319011"; 
        [Bib]="5"; 
        "860201061179373"; 
        -1; 
        "NULL"
    )
```

#### **Friendly name to manually assign a specific GPS tracker to a participant**

RACEMAP devices come labeled with a friendly name of six letters. You might use your GPS trackers with your own label system.

Go to Main Window, Participants Data, User Defined Fields, and add the field `IMEI`. Paste the friendly name of the tracker and the corresponding IMEI number.

<figure><img src="/files/FQAKEPq3JMxztYjjKfoS" alt=""><figcaption><p>User defined fields, add IMEI field</p></figcaption></figure>

The code sample inserts five GPS devices with its friendly names into RACE RESULT.

```
"IMEI" & switch(
        [Tracker]="A00B40"; 
        "860201061635184"; 
        [Tracker]="A00CFD"; 
        "860201061637206"; 
        [Tracker]="A00CFA"; 
        "860201061636521"; 
        [Tracker]="A00CF8"; 
        "860201061319011"; 
        [Tracker]="A00DC5"; 
        "860201061179373"; 
        -1; 
        "NULL"
    )
```

Go to Main Window, Participants Data, Additional Fields, and add the field `Tracker`.

<figure><img src="/files/Eqvq14aqTdlRgDWdLv0i" alt=""><figcaption></figcaption></figure>

Go to participants and paste the friendly name to address a specifc tracker to the participant. The IMEI of this device will be synchronized through the simple API with the RACEMAP event.

<figure><img src="/files/TO6kddjS6KEbfFRyo8wz" alt=""><figcaption></figcaption></figure>

#### **Registration form with live tracking option**

Create an online registration form with the option for live tracking either with RACEMAP App or with GPS trackers.

Go to Main Window, Participants Data, Additional Fields, and add the checkbox `App` and add a second checkbox `Tracker`.

![Additional fields: Checkbox to let participants select Tracking App and GPS Tracker](/files/ODUsN4lMfmgEseqikYoK)

<figure><img src="/files/ZrKziQQoaG4nnJBley24" alt=""><figcaption><p>User defined fields: Insert keys and IMEI numbers and corresponding links to checkboxes</p></figcaption></figure>

`Key` and `Key_1` fields are similar to the sample above.

`If` function in `IMEI` field: If the participant checks "Live Tracking GPS Tracker" one IMEI is assigned to this participant.

```
if([Tracker]=1;switch([Bib]>0 AND [Bib]<=100;"IMEI"&[IMEI_1]))
```

`Choose` function in `IMEI_1` field, past the IMEI numbers from the GPS devices.

```
choose([Bib];"xxxxxx";"yyyyyy";"zzzzzz";...)
```

Tracking keys connect the RACEMAP App (and custom tracking apps) to enable live tracking for a specific event. You can use keys to offer live tracking as an optional purchase in your online registration form, allowing all participants to join live tracking.

{% content-ref url="/pages/-LXLDfyEEiuGO8RHSmWq" %}
[Keys and passcode](/apps/tracking/keys)
{% endcontent-ref %}

### Cut-off time at checkpoint

{% tabs %}
{% tab title="before cut-off time" %}
Participants reach the checkpoint before the cut-off time and continue on the white course.<br>
{% endtab %}

{% tab title="after cut-off time" %}
Participants reach the checkpoint after the cut-off time and continue on the black course (or finish at this checkpoint or ...).
{% endtab %}
{% endtabs %}

* RACE RESULT settings with three contests - grey, white and black
* User defined field for sorting participants during the event from grey contest to white or to black depending on detections at the checkpoint.

| cut-off            | grey             | white                                     | black                                        |
| ------------------ | ---------------- | ----------------------------------------- | -------------------------------------------- |
| until cut-off time | all participants | no participant                            | no participant                               |
| from cut-off time  | no participant   | participants with detection at checkpoint | participants without detection at checkpoint |

RACEMAP settings:

* create a tracking map with the white course (shadowtrack) and synchronize participants from grey and white contests
* create another map with the black course and synchronize participants from grey and black contests
* create a group and add the white map

Description of the process:

* From the start, all participants are calculated on the white- and on the black shadowtrack. That means each participant is shown twice - in the white and the black map.
* At the cut-off time the participants in the white (black) contest are synchronized with the white (black) map. That means each participant is visible in either the white or the black map.
* Now, add the black map to the group map. That way spectators continue streaming the same group with the new sorting of participants.

{% hint style="info" %}
To select a contest in the RACE RESULT import at least one participant needs to be assigned to this contest. That means at the beginning you need to add one participant in the white and the black contest. This one participant does not need to have a transponder Id.
{% endhint %}


# Import with CSV file

Use a CSV file to upload participants and devices for live tracking in RACEMAP. Download the participant list as a CSV file or automatically call the API endpoint.

### Usage of CSV file

* Import participants and add devices (GPS tracker, transponder, Track Box, decoder).
* Download the participant list for further processing eg. updating an existing list.
* Automatically call the participants' information from the given API endpoint.

![Mange the list of participants & devices in your event](/files/HNmdzexet1E9CTmiXJIQ)

#### Upload participant list

You want to use a CSV file to upload basic participant information - `startnumber`, `name`, `tags`, and `marker_color` - to a specific event.

Where to upload the CSV file with participant's information? Select the relevant event from your event list - <https://racemap.com/admin/events> - open the (1.) Participants section and select (2.) Import/Export.

{% tabs %}
{% tab title="1. Participants >> Import/Export" %}

<figure><img src="/files/TuRyCiyFJBQP9BqJWjs4" alt=""><figcaption></figcaption></figure>
{% endtab %}

{% tab title="2. Upload CSV file" %}

<figure><img src="/files/9gZjsCxQK374KTg6tSZa" alt=""><figcaption></figcaption></figure>
{% endtab %}

{% tab title="3. Success" %}

<figure><img src="/files/37RNoTOp3caOO3EidefV" alt=""><figcaption></figcaption></figure>
{% endtab %}
{% endtabs %}

This section introduces the two options - CSV file & tracker management - on how to merge the information of a participant with a specific GPS tracker that this participant will use for live tracking. Both options work with your GPS trackers the same way as with rented GPS trackers from RACEMAP.

{% tabs %}
{% tab title="Merge in CSV file, direcly " %}

1. GPS trackers from RACEMAP: We provide a CSV file with devices' information `imei` and `device_name` of the trackers sent to you. `device_name` matches the sticker on the device, helping to identify a specific device with a friendly name.

{% file src="/files/1dDtYVCATPXoE91ru7OM" %}
Sample CSV file with `imei` and `device_name` of rented the trackers.
{% endfile %}

2. Use the provided CSV file with the device information as a template and add participant information `startnumber`, `name`, `tags`, and `marker_color`. Upload the resulting CSV file - that contains the merged information of participants and trackers - to your event.

{% file src="/files/bzElbu21s2EzDqzkukYG" %}
Sample CSV file with merged information of your participants and the rented trackers.
{% endfile %}

<figure><img src="/files/omP5WWAlMa9jMqZQ6xK5" alt=""><figcaption><p>Sample CSV file such that the participant list provides this information about participants and GPS trackers.</p></figcaption></figure>
{% endtab %}

{% tab title="Merge with the tracker management" %}
{% file src="/files/YRu4cSzFFgrA5llKfb5X" %}
Add participant information in this minimal sample file.
{% endfile %}

1. Add participant information `startnumber`, `name`, `tags`, and `marker_color` in the minimal sample participant CSV file. Upload the resulting participant CSV file to your event.

{% file src="/files/zvALdKziepzKUhuG1mTA" %}

<figure><img src="/files/KpJFdSr14ZikQNFDxJuG" alt=""><figcaption><p>Sample CSV file such that the participant list provides this information about participants.</p></figcaption></figure>

2. Merge your GPS trackers with uploaded participants in the tracker management according the instructions on [Add devices to event](https://docs.racemap.com/tracker-management/add-to-event).
   {% endtab %}
   {% endtabs %}

#### Update participant list

Follow the workflow to update & add entries in an existing participant list using a CSV file.

* There is a unique `starter_id` generated for each new participant that is uploaded without a `starter_id`.
* Download the current participant list. The CSV file includes `starter_id` for each participant.
* Modify or add data in the CSV file such as race number, name, color, IMEI or app ID, key, tags.
* Upload the reworked CSV file. The entries in Racemap are updated corresponding to the `starter_id`.
* It is not possible to delete entries by uploading a CSV file.

### Format of CSV file

{% file src="/files/9zyAv2EPeg5GljOAUYiW" %}

![sample\_participant\_file.csv in an editor](/files/WnrBVim0QHZ94c585VI1)

* Only refresh the needed parameters. No need to keep all parameters in the file.
* Parameters are semicolon-separated.
* Any sequence of parameters is allowed.
* Empty cells are accepted.

<table><thead><tr><th width="216.7146836227593">Parameter</th><th width="332.7637445340682">Description</th><th>Sample</th><th data-hidden></th></tr></thead><tbody><tr><td><code>startnumber</code></td><td>bib number of participant</td><td>40012, 🔥, Max</td><td></td></tr><tr><td><code>name</code></td><td>name of participant</td><td>Max, 🔥, 40012</td><td></td></tr><tr><td><code>imei</code></td><td>IMEI or transponder ID of device</td><td>4106050246, RRPing_ZDKAR32, RRPing_70761</td><td></td></tr><tr><td><code>device_class</code></td><td>specific device class</td><td>Mobile, Tracker, Upload, Transponder, TrackPingTransponder</td><td></td></tr><tr><td><code>device_type</code></td><td>specific device type</td><td>GL300, LK106, active, passive</td><td></td></tr><tr><td><code>marker_color</code></td><td>color of marker in tracking map, hex code</td><td>#023d10</td><td></td></tr><tr><td><code>tags.[attribute]</code></td><td>additional attributes to filter participants eg. age group, status or nationality <code>tags.Age</code> or <code>tags.Status</code></td><td>35, 24<br>DSQ, DNS, DNF</td><td></td></tr><tr><td><code>startTime</code></td><td>timestamp of first location in UTC, first location that is considered in the event, locations before are ignored</td><td>2021-10-23T00:35:00.000Z</td><td></td></tr><tr><td><code>endTime</code></td><td>timestamp of last location in UTC, last location that is considered in the event, locations after are ignored</td><td>2021-10-23T01:15:59.710Z</td><td></td></tr><tr><td><code>manualResult</code></td><td>duration to finish [hh:mm:ss]</td><td>06:10:13</td><td></td></tr><tr><td><code>times.start</code></td><td>timestamp of first timing split in UTC, considered in leaderboard. If <code>startTime</code> is undefined, then <code>startTime</code> is written accordingly.</td><td>2021-10-23T00:55:35.000Z</td><td></td></tr><tr><td><code>times.end</code></td><td><p>timestamp of last timing split in UTC,</p><p>considered in leaderboard. If <code>endTime</code> is undefined, then <code>endTime</code> is written accordingly.</p></td><td>2021-10-24T05:31:41.021Z</td><td></td></tr><tr><td><code>key</code></td><td>no import if value of <code>key</code> does not belong to Racemap event</td><td>3Z2GPX</td><td></td></tr><tr><td><code>starter_id</code></td><td>unique Racemap ID of participant, assigned to specific participant</td><td>617bb83e4cc0e8c92c7bfcb5</td><td></td></tr><tr><td><code>device_id</code></td><td>unique Racemap ID of device</td><td>5b6ac1561c6a700020a00133</td><td></td></tr><tr><td><code>device_name</code></td><td>name of GPS device in tracker management</td><td>A00133</td><td></td></tr><tr><td><code>player_link</code></td><td>URL to select participant in tracking map</td><td><a href="https://racemap.com/player/participant-list-sample#selected=617bb83e4cc0e8c92c7bfcb5">https://racemap.com/player/participant-list-sample#selected=617bb83e4cc0e8c92c7bfcb5</a></td><td></td></tr></tbody></table>


# Tracker management

Dashboard: Efficiently handling of multiple tracking devices & associated SIM cards. Prepare GPS units for live tracking before a race, monitor & adjust the hardware during, and analyze data afterward

<figure><img src="/files/VWhVeqwSU9vcZFWPrAaN" alt=""><figcaption><p>Overview of GPS units in your account</p></figcaption></figure>

{% hint style="success" %}
Access your devices in the tracker management\
<https://racemap.com/admin/trackers>
{% endhint %}

Whether you're managing numerous trackers or overseeing multiple users of your GPS units across various events, the tracker page offers valuable insights into device status, streamlining your workflow and reducing reaction time. Tracker management enhances your operational capabilities and provides a central hub for managing your GPS devices seamlessly. The tracker dashboard includes:

* **Overview of your GPS trackers:** Get a comprehensive view of all your devices, providing a quick snapshot of their current status, including ICCID of the inserted SIM card.
* **Filters for quick selection:** Utilize filters to swiftly find and select specific units based on your criteria, enhancing efficiency in device management.
* **Detailed device information:** Access detailed information for each device, allowing you to monitor configuration, battery status, reception, GPS fix, and other relevant metrics.
* **Messaging platform:** Use the platform to send messages, facilitating communication with the devices. You can even compose and store commands.
* **Access rules:** Control how other RACEMAP accounts can (temporarily) access your GPS trackers, eg. when lending devices or shared working among an organization.
* **Manage SIM cards:** Control your RACEMAP M2M SIM cards.

Select specific devices in the above section of the dashboard and click [⚙️](https://emojipedia.org/gear) for possible actions. The action always applies to all devices in the selection section.

For device selection you can drag and drop or use the [Orga App](/apps/orga).

<figure><img src="/files/BD1VRMAeIKG6sBJtV58A" alt=""><figcaption><p>Work on selected GPS trackers</p></figcaption></figure>

Under "Activation Type", you archive GPS devices to prevent accidental use in the tracker management. Use this option e.g. if a GPS tracker is lost.

<figure><img src="/files/l8hciKs7NJ18VxqcpAX5" alt=""><figcaption></figcaption></figure>


# Add GPS trackers

Upload your GPS units to the tracker management of your Racemap account.

{% hint style="success" %}
Use the URL <https://racemap.com/admin/trackers/add> or the "Add Tracker" button to upload your GPS trackers into the tracker management.
{% endhint %}

### Add one GPS tracker

<figure><img src="/files/4bDYjYWH3uq8V7MQbpGo" alt=""><figcaption><p>Add one GPS tracker to the Tracker Management manually.</p></figcaption></figure>

Use the form fields to select the tracker type, provide an optional device name, and paste the IMEI of your device. This allows you to add GPS trackers manually, one by one.

### Add multiple GPS trackers

<figure><img src="/files/aAFwIgBkkXmlGPp17z7b" alt=""><figcaption><p>Drop csv file with your trackers' information.</p></figcaption></figure>

Add multiple devices to your Tracker Management at once by uploading a CSV file.

{% tabs %}
{% tab title="minimal sample" %}
**Syntax:** use the IMEI in the tracker\_id column

{% code lineNumbers="true" %}

```
tracker_id,tracker_name,device_type
860297002626525,Tr0047,GL320LTE-MG
```

{% endcode %}

{% file src="/files/VgUDoNyz2NPVyQ6TIhAe" %}
**Download csv file, minimal sample file**
{% endfile %}
{% endtab %}

{% tab title="iccid of inserted SIM card" %}
**Syntax:** use the IMEI in the tracker\_id column

{% code lineNumbers="true" %}

```
tracker_id,tracker_name,device_type,iccid
860297002626525,Tr0047,GL320LTE-MG,9845435823031369005,47454525920082
```

{% endcode %}

{% file src="/files/FKZXORqEy5xXmy3ctCZz" %}
**Download sample file including iccid of inserted SIM card**
{% endfile %}
{% endtab %}
{% endtabs %}

{% hint style="info" %}
**IMEI requirements:** To add a GPS device, the IMEI must meet the requirements:

* Unique: The IMEI must not already exist in the tracker management.
* 15 digits long: IMEIs must be exactly 15 characters.
* Digits only: Only numbers 0–9, no spaces, hyphens, or letters.
* [Luhn check digit](https://en.m.wikipedia.org/wiki/Luhn_algorithm)

You can validate IMEIs using an IMEI checker such as <https://imeicheck.net/>
{% endhint %}

### Rename devices in Tracker Management

When customizing your GPS trackers, you may need to change the names of your devices in the Tracker Management.

{% hint style="warning" %}
RACEMAP does not save previous tracker names. To retain a record of the original names, we recommend exporting and saving a CSV file of the current tracker information before making any changes.
{% endhint %}

1. **Export tracker data**\
   Select the devices you want to rename and download the CSV file containing their details.

<figure><img src="/files/w1YwuyVKJEiGgkn8KX4q" alt=""><figcaption></figcaption></figure>

{% code lineNumbers="true" %}

```
id;tracker_id;tracker_name;device_type;iccid;tracker_link
5ae88c82208b1df57805ab91;352887073845640;test(rename);GL300;;https://tr.racemap.com/5ae88c82208b1df57805ab91
5ae88c82208b1df57805acdb;352887073766457;Racemaptracker-11;GL300;;https://tr.racemap.com/5ae88c82208b1df57805acdb
```

{% endcode %}

{% file src="/files/VQEbYKRQnxhwqsy8i0BP" %}

2. **Edit CSV file**\
   Open the CSV file in a text editor and delete all columns except the essential ones: `id`, `tracker_id`, `device_type` and `tracker_name`.
3. **Rename devices**\
   Update the `tracker_name` column with the new names you want to assign.

{% code lineNumbers="true" %}

```
id;tracker_id;tracker_name;device_type
5ae88c82208b1df57805ab91;352887073845640;Lead Tracker;GL300
5ae88c82208b1df57805acdb;352887073766457;Swap Device;GL300
```

{% endcode %}

{% file src="/files/5VKy7kvHxta3iz6JQovH" %}

4. **Upload the Updated CSV**\
   Click the Add Tracker button and upload the modified CSV file. The device names will be updated immediately.

<figure><img src="/files/Nvxh3iyHYLHAJBYqLHGD" alt=""><figcaption></figcaption></figure>


# Add RACE RESULT readers

Integrate the timing hardware of your RACE RESULT account - ubidium, track boxes, and decoders - to use them as GPS trackers in RACEMAP.

* Log in to your RACE RESULT account and generate an API key. More details in RACE RESULT knowledge base: <https://www.raceresult.com/en-us/support/kb?id=42853-API-Keys>
* Provide your RACE RESULT customer ID and API key in the settings of your RACEMAP account under integrations: <https://racemap.com/admin/account>

<figure><img src="/files/HOxBuduCceCcQUB9rIfw" alt=""><figcaption></figcaption></figure>

* Go to the tracker management and click "Add Tracker": <https://racemap.com/admin/trackers>

<figure><img src="/files/XwNajNnmSUEKY6Zkgc0k" alt="" width="563"><figcaption></figcaption></figure>

* Select the RACE RESULT hardware you want to use in RACEMAP.

<figure><img src="/files/u7gJrMGfp30ifhFtmPXb" alt=""><figcaption></figcaption></figure>


# Add devices to event

Attach multiple GPS trackers to an event.

![](/files/dwuvnAjUjr4k82nhGN0H)

<figure><img src="/files/crhUpmR3EnMooG9ftalf" alt="" width="375"><figcaption><p>Search the event to add selected GPS trackers</p></figcaption></figure>

* Select (multiple) GPS tracker(s).
* Select "Add tracker to event" to attach the selected devices to your event.
* Refresh the participants section of your event and the trackers are appended.

Note: New participants will be created in the event when adding the trackers before participant information is uploaded in the event.

{% content-ref url="/pages/-M3ehZR5FRb3OtNJtvds" %}
[Import participant data](/api-import-and-export-data)
{% endcontent-ref %}


# Send messages

Use the tracker management to efficiently send commands to multiple GPS trackers at once. You can even schedule commands for a specific time frame.

{% hint style="success" %}
Contact us, when missing a specific message you want to apply to your devices. You can also compose your own message templates.
{% endhint %}

{% hint style="info" %}

### Messaging through API <a href="#trackers-api" id="trackers-api"></a>

Independent from sending [commands through the UI of the tracker management](/tracker-management/messages) dashboard you can use message templates to integrate command sending into your system eg. to level up the automatization of your processes.

**URL** `https://racemap.com/api/v1/trackers/messages`\
**Method** Send\
**Sample message template** - Set report interval - for Queclink GL3xx GPS trackers:\
<https://racemap.com/admin/message-templates/6613c31ad019cb0ece29e251>

Get the required `deviceId`(s) from the [current API](/api/current).
{% endhint %}

{% content-ref url="/pages/GZlSTdBBq82OSB9ep68p" %}
[Message templates](/tracker-management/trackersapi)
{% endcontent-ref %}

### Basics

* Identify and select the GPS trackers to which you want to send commands. The tracker management targets the commands to all devices in the above list.
* Ensure that the devices are switched on and currently connected with Racemap to receive commands.

<figure><img src="/files/Hi5FxWPmYzUUcK0Cs6Vq" alt=""><figcaption><p>Selected devices in above table, 11 GPS trackers are connected with Racemap</p></figcaption></figure>

* Monitor the acknowledgment from each device to confirm the successful receipt of the command.
* Check the messages timeline for each device to track the progress of sending commands. Inspect the message details to gather additional information on each device's response.

<figure><img src="/files/ngLB3nSnYA46vXPMwCg5" alt=""><figcaption><p>Messages timeline of specific device.</p></figcaption></figure>

<figure><img src="/files/SZZHNNN6zgXwiojBfgFJ" alt=""><figcaption></figcaption></figure>

#### Options sending commands:

* **Time:** Send the message right away ("Now") or schedule the time frame ("Not before" and "Not after") in which Racemap attemps to send the command to the device.
* **Command:** Select the command.\
  ![](/files/ghA3LgQitVrOr40OR7DT)
* **Transport:** By default, messaging with GPS trackers works via TCP connection. However, if you're running the devices with our M2M SIM cards, you can choose to send messages as SMS instead.\
  To receive an SMS, the device must not have an open socket connection with RACEMAP server. This provides the alternative to sending SMSs to devices that are not connected, making it useful for tasks like rebooting the device or requesting the last known location.\
  ![](/files/kfTLCSyt9Q4X4BzYObNR)

{% content-ref url="/pages/PeqJ8IeSuTZT3q7B6xST" %}
[Manage SIM cards](/tracker-management/sim-cards)
{% endcontent-ref %}

You can schedule commands for a group of GPS trackers to automatically adjust the devices' settings according to the time.

A couple of days before the race:

* Switch on all devices manually.
* Place devices for a good connection.
* Select all devices in tracker management.
* Check connection and location in tracker management.
* Clear undelivered commands from messages timeline before scheduling new commands with the "Revoke all messages" function.

<figure><img src="/files/YJfckZxVlt8j7Jv2FSxI" alt=""><figcaption></figcaption></figure>

* Schedule commands according to SLEEP, AWAKE and RACE profile.
* Don't switch devices off after you have scheduled commands.

**SLEEP profile:** "heartbeat", every 10 to 20 min refreshes the connection to Racemap, if there is reception

<table data-full-width="false"><thead><tr><th width="81">#</th><th width="269">Command</th><th width="257">Parameter</th><th>Time</th></tr></thead><tbody><tr><td>S1</td><td>GPS Module</td><td>mode: 1</td><td>Now</td></tr><tr><td>S2</td><td>GPS Report Interval</td><td>3600; 3600</td><td>Now</td></tr><tr><td>S3</td><td>Non-Movement Detection</td><td>10; 3600; 3600</td><td>Now</td></tr></tbody></table>

{% hint style="info" %}

* Participants must not use the power button! When deploying the devices to participants the devices are turned on already.
* Devices lose about 5 to 7 % battery level in 24 hrs.
  {% endhint %}

**AWAKE profile:** It takes up to 60 min until all devices receive the new configuration. Check the tracker management if there is a device that does not establish a connection. The participant might have turned the device off. You still have time to change the device before the race starts.

<table><thead><tr><th width="77">#</th><th width="260">Command</th><th>Parameter</th><th>Not before</th><th>Not after</th></tr></thead><tbody><tr><td>A1</td><td>GPS Report Interval</td><td>180; 180</td><td>4 hrs before race starts</td><td>3 hrs before race starts</td></tr><tr><td>A2</td><td>Non-Movement Detection</td><td>10; 180; 180</td><td>4 hrs before race starts</td><td>3 hrs before race starts</td></tr></tbody></table>

**RACE profile:** It takes up to 10 min until all devices receive the new configuration.

<table><thead><tr><th width="84">#</th><th width="258">Command</th><th width="134">Parameter</th><th>Not before</th><th>Not after</th></tr></thead><tbody><tr><td>R1</td><td>GPS Module</td><td>mode: 0</td><td>1 hr before race starts</td><td>no entry</td></tr><tr><td>R2</td><td>GPS Report Interval</td><td>10; 10</td><td>1 hr before race starts</td><td>no entry</td></tr></tbody></table>

{% hint style="info" %}

* Devices lose about 5 % battery level every 1 hr.
* With 60; 60 parameter setting, devices lose about 2 % battery level every 1 hr.
  {% endhint %}

For stage events you can schedule subsequent SLEEP and RACE profiles for each stage.

After the race: Use the "Shut down" command to remotely switch devices off. When the device has received the shot down it must be switched on manually. There is no possibility to remotely turn on a device.


# Message templates

Create, edit & manage commands to operate your GPS trackers flexibly using RACEMAP’s message dashboard. This platform empowers you to control and tailor messages to your specific needs.

{% hint style="info" %}
Access the message dashboard: <https://racemap.com/admin/message-templates>
{% endhint %}

<figure><img src="/files/H2IeGvwMI8PlNivv4aTu" alt=""><figcaption><p>Overview over the message dashbord with custom commands and public commands.</p></figcaption></figure>

**The message dashboard provides:**

* Private messages: Custom messages you create, accessible only in your account.
* Public messages: Provided by RACEMAP and available for all users.

**Key features:**

* Device support: Manage message templates for a variety of tracker types supported in RACEMAP. For more details on supported hardware, visit [supported GPS devices](https://docs.racemap.com/hardware-for-live-tracking#various-gps-devices-for-live-tracking-in-racemap).
* Ownership control: Private messages can be applied only to devices you own or can edit. These messages cannot be shared with borrowers.
* Template ID: Each template is assigned a unique `templateId`, which is required when sending messages from external systems.
* Export your private messages as GeoJSON files for external use.

{% hint style="info" %}

### Messaging through API <a href="#trackers-api" id="trackers-api"></a>

Independent from sending [commands through the UI of the tracker management](/tracker-management/messages) dashboard you can use message templates to integrate command sending into your system eg. to level up the automatization of your processes.

**URL** `https://racemap.com/api/v1/trackers/messages`\
**Method** Send\
**Sample message template** - Set report interval - for Queclink GL3xx GPS trackers:\
<https://racemap.com/admin/message-templates/6613c31ad019cb0ece29e251>

Get the required `deviceId`(s) from the [current API](/api/current).
{% endhint %}

#### Compose your own message templates

* Use the "Add template" button to create a new private message.
* Duplicate & edit: Copy an existing message and modify it to create a private version.

<figure><img src="/files/iXMyzCxsBF7InQxwvmPB" alt=""><figcaption></figcaption></figure>

For each message template the below information must be provided.

* Name: The name of the template
* Variant: Either single or group
  * Single: The same template is applicable for one or multiple trackers.
  * Group: Groups several single templates with the same function for different tracker types (e.g., the "Shut down" command for GL300, LK106, and M20 grouped together).
* Description: Explain the effect of the message on the GPS tracker and clarify any parameters, including their units.
* Tracker types: Select the supported trackers to which the message applies.
* Allowed user roles: Specify whether the message can be used by you as the owner and or editors.
* Template: Provide the command, that will be send with the message.
* Arguments: If the command uses parameters, define them here.
* Example: A copyable example of the template.


# User access to devices

Set different roles for other RACEMAP accounts to access your GPS trackers.

The tracker management supports three different user roles. There is one "owner" for each device. The owner can share access to the same device for multiple users through the "editor" and "borrower" roles.

<table><thead><tr><th width="119">User role</th><th>Use case</th><th>Permissions</th><th>Messages</th></tr></thead><tbody><tr><td><strong>Owner</strong></td><td><strong>Standard device owner:</strong> RACEMAP account that initially added the device to tracker management.</td><td><p>Can add/remove editors and borrowers.<br></p><p>Cannot bulk remove users or manage other owners.</p></td><td>Can use all <a href="/pages/GZlSTdBBq82OSB9ep68p">message templates</a> assigned to its account.</td></tr><tr><td><strong>Editor</strong></td><td><strong>Shared management access:</strong> Members in the same organization to manage device rentals and borrowers.</td><td><p>Can add/remove borrowers.</p><p>Cannot bulk remove, cannot manage owners or editors.</p></td><td>Can use all <a href="/pages/GZlSTdBBq82OSB9ep68p">message templates</a> assigned to its account.</td></tr><tr><td><strong>Borrower</strong></td><td><strong>Temporary access:</strong> A user that rented your devices. The access period is set by start and end date.</td><td>Cannot add or remove other users. No access to manage user roles).</td><td>Can use only specific messages.</td></tr></tbody></table>

<figure><img src="/files/jPj1OCJ2FKAVTq77PfKC" alt=""><figcaption><p>Manage user access and permissions in the user tab for each device separately.</p></figcaption></figure>

#### How to add users and change user roles, bulk

* Select multiple GPS trackers.
* Select "Manage User" to open the modal to manage user access.

<figure><img src="/files/MBoCRdq3aKCwkUDh4FAx" alt=""><figcaption></figcaption></figure>

**Add a user role**

* Search field: Type the email address or name of the RACEMAP account you want to add.
* Add the user from the dropdown results.

<figure><img src="/files/ubFb4CkgkpgvBVQO8V3T" alt=""><figcaption></figcaption></figure>

* Select the role you want to assign.

<figure><img src="/files/nAqFmBkT9KfAWFwp9arR" alt="" width="375"><figcaption></figcaption></figure>

**Change a user role**

* Click the button showing the user role (eg., "Editor") to open the "Change role" modal.

<figure><img src="/files/hwm2BzinMfLQK8LSR0AU" alt=""><figcaption></figcaption></figure>

* Select the role you want to assign.

<figure><img src="/files/nAqFmBkT9KfAWFwp9arR" alt="" width="375"><figcaption></figcaption></figure>


# Manage SIM cards

Manage RACEMAP M2M SIM cards through our platform.

{% hint style="info" %}
Access the SIM cards dashboard: <https://racemap.com/admin/sim-cards>
{% endhint %}

<figure><img src="/files/fHaK1KTL2msnrseoG7RR" alt=""><figcaption><p>Manage your SIM cards in RACEMAP</p></figcaption></figure>

Manage your RACEMAP SIM cards on our platform

* Activation and Deactivation: Activate or terminate specific SIM cards at any time.
* Tracker Association: View the name of the associated GPS tracker within the tracker management system.
* Data Usage: The "Data Usage" column provides an estimate of current traffic consumption for the month. Exact data usage figures are available with a delay of nearly one month, as we don’t receive real-time updates from the SIM card provider.
* Send SMS to specific cards: This feature is helpful when you don't know the exact hardware in which the SIM card is inserted eg. when [initializing new GPS devices](/gps-devices/config/remote). In that case, you can directly address messages to specific SIM cards

Using RACEMAP SIM cards allows you to send messages via SMS instead of relying on a TCP connection. Learn more about sending messages in the tracker management:

{% content-ref url="/pages/WEc6rUIhSCe1qyxMD4Sa" %}
[Send messages](/tracker-management/messages)
{% endcontent-ref %}


# Hardware for live tracking

Use your GPS units for sports live tracking. Queclink GPS trackers of the GL3xx series are highly integrated into RACEMAP platform.

#### Various GPS devices for live tracking in RACEMAP platform <a href="#types" id="types"></a>

The listed GPS trackers are supported for live tracking in our platform. Our tracker management allows remote messages and commands for some devices. The Queclink GL3xx series has the deepest integration, enabling high-level automation.

Are you missing your GPS tracker? Are you going to use a significant number of devices in RACEMAP? We are open to developing the implementation for new devices. Get in touch [racemap.com/#contact](https://racemap.com/#contact)

<table><thead><tr><th width="185">Provider</th><th width="261">Device Type</th><th>Messages</th></tr></thead><tbody><tr><td><a href="https://www.queclink.com/">Queclink</a></td><td>GL30MG</td><td>✔️</td></tr><tr><td><a href="https://www.queclink.com/">Queclink</a></td><td>GL320M</td><td>✔️</td></tr><tr><td><a href="https://www.queclink.com/">Queclink</a></td><td>GL310M</td><td>✔️</td></tr><tr><td><a href="https://www.queclink.com/">Queclink</a></td><td>GL300M, GL300W, GL300W</td><td>✔️</td></tr><tr><td><a href="https://www.queclink.com/">Queclink</a></td><td>GL300/GT560</td><td>✔️</td></tr><tr><td><a href="https://www.micronwireless.net/">Micron</a></td><td>Prime II</td><td>✔️</td></tr><tr><td><a href="https://www.mictrack.com/">Mictrack</a></td><td>MT825 / MT710</td><td>✔️</td></tr><tr><td><a href="https://www.meitrack.com/en/vehicle-tracker/">Meitrack</a></td><td>MT90</td><td>✔️</td></tr><tr><td><a href="https://superspring.co.id/">Superspring</a></td><td>M20</td><td>✔️</td></tr><tr><td><a href="https://teltonika-mobility.com/">Teltonika</a></td><td>TMT250</td><td></td></tr></tbody></table>

#### Running time of the GPS tracker

| Report- & Send Interval \[sec] | GL320, GL310 \[hr] | GL300 \[hr] |
| ------------------------------ | ------------------ | ----------- |
| 5                              | 13                 | 8           |
| 10                             | 19                 | 13          |
| 30                             | 35                 | 26          |
| 60                             | 60                 | 42          |
| 120                            | 70                 | 50          |

The running time of an GPS device during live tracking depends on:

* settings of GPS tracker
* network coverage
* visibility of GPS device for satellites - How is the device stowed?
* constitution of battery
* temperature


# Configure Queclink GL3xx trackers

Initially set-up of your Queclink GL3xx GPS trackers for live tracking on RACEMAP.

* If you don't want to spend time on tracker configuration, you can directly purchase ready-to-use units at <https://racemap.com/gps-tracker#buy>. All GPS trackers shipped with:
  * inserted M2M SIM cards,
  * the latest firmware and
  * RACEMAP configuration.
* You can also use devices you already own or purchase elsewhere, along with your own SIM cards, or with our M2M SIM cards. In that case, you configure the trackers on your own. For other tracker types than Queclink GL3xx series, consult your supplier for the commands for initial configuration.\
  [Check the list of supported devices](https://docs.racemap.com/hardware-for-live-tracking#various-gps-devices-for-live-tracking-in-racemap).

{% hint style="success" %}
Communication with RACEMAP server of GPS devices supporting DNS:

* domain racemap.com
* port 5000

All other GPS devices

* ip 116.203.167.141
* port 5000
  {% endhint %}

#### Configuration of your Queclink GL3xx trackers

Step-by-step playbook to configure Queclink GL3xx GPS trackers on your own.

**1. Remote configuration:** Our migration guide enables you to configure multiple devices at once with automated, scalable workflows.

{% content-ref url="/pages/XvkUON56j9Gs0KcRLikT" %}
[Remote configuration](/gps-devices/config/remote)
{% endcontent-ref %}

**2. Local (physical) configuration:** Configure devices individually using a computer, the Queclink Manage Tool (download of local software), and the appropriate data cable.

{% content-ref url="/pages/XPmWCVRGZAculFILIebN" %}
[Configuration via cable](/gps-devices/config/cable)
{% endcontent-ref %}

After successful configuration, the devices are ready to establish a TCP connection with RACEMAP and you can communicate remotely through the tracker management e.g. to send commands.

<figure><img src="/files/ata8rYxULyz4azpDSj3a" alt=""><figcaption></figcaption></figure>


# Remote configuration

This migration guide walks you step-by-step through the remote initial configuration of large numbers of GL3xx devices for live tracking in RACEMAP.

### Initial configuration of Queclink GL3xx series <a href="#initial-config-queclink-gl3xx" id="initial-config-queclink-gl3xx"></a>

We recommend utilizing bulk SMS sending from your SIM platform.

* Insert your SIM cards into the devices.
* Turn on the devices.
* Place devices outdoors for mobile reception.
* Wait 10 minutes and proceed with steps A to D.\
  (Step A is not required if the device password is `gl320m`, `gl310m`, and `gl300m` corresponding to the device type. Start with step B)

#### A) SMS - Set device password <a href="#set-password" id="set-password"></a>

If the previous owner changed the password, set the required password. To set a new password, you need to know the `<old_password>`. Send the command via SMS.

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

```
AT+GTCFG=<old_password>,gl320m,gl320m,0,0,1,5,003F,,,3FFF,0,0,1,3600,2,0,,1,0000,0,20,0,,FFFF$
```

{% endtab %}

{% tab title="GL310M" %}

```
AT+GTCFG=<old_password>,gl310m,gl310m,0,0,1,5,003F,,,3FFF,0,0,1,3600,2,0,,1,0000,0,20,0,,FFFF$
```

{% endtab %}

{% tab title="GL300M" %}

```
AT+GTCFG=<old_password>,gl300m,gl300m,0,0,1,5,003F,,,3FFF,0,0,1,3600,2,0,,1,0000,0,20,0,,FFFF$
```

{% endtab %}
{% endtabs %}

If working with RACEMAP SIM cards: When you don't know exactly which SIM card is inserted in which device and you want to address SMS messages to specific SIM cards directly you can use our SIM cards dashboard.

{% content-ref url="/pages/PeqJ8IeSuTZT3q7B6xST" %}
[Manage SIM cards](/tracker-management/sim-cards)
{% endcontent-ref %}

#### B) SMS - Address RACEMAP server, set APN of SIM provider <a href="#set-apn-ip-port" id="set-apn-ip-port"></a>

{% hint style="success" %}
domain racemap.com\
port 5000
{% endhint %}

Send the command via SMS to set the APN of your SIM provider (replace `<your_APN>`) and RACEMAP server.

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

```
AT+GTBSI=gl320m,<your_APN>,,,<your_APN>,,,0,2,0,1,,,,,FFFF$AT+GTSRI=gl320m,3,,1,racemap.com,5000,racemap.com,5000,,10,1,1,0,60,,FFFF$
```

{% endtab %}

{% tab title="GL310M" %}

```
AT+GTBSI=gl310m,<your_APN>,,,<your_APN>,,,0,2,0,1,,,,,FFFF$AT+GTSRI=gl310m,3,,1,racemap.com,5000,racemap.com,5000,,10,1,1,0,60,,FFFF$
```

{% endtab %}

{% tab title="GL300M" %}

```
AT+GTBSI=gl300m,<your_APN>,,,<your_APN>,,,0,2,0,1,,,,,FFFF$AT+GTSRI=gl300m,3,,1,racemap.com,5000,racemap.com,5000,,10,1,1,0,60,,FFFF$
```

{% endtab %}
{% endtabs %}

Send the command via SMS if the APN access of your SIM provider requires a user and a password. Replace `<APN_user>` and `<APN_password>`.

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

```
AT+GTBSI=gl320m,<your_APN>,<APN_user>,<APN_password>,<your_APN>,<APN_user>,<APN_password>,0,2,0,1,,,,,FFFF$AT+GTSRI=gl320m,3,,1,racemap.com,5000,racemap.com,5000,,10,1,1,0,60,,FFFF$
```

{% endtab %}

{% tab title="GL310M" %}

```
AT+GTBSI=gl310m,<your_APN>,<APN_user>,<APN_password>,<your_APN>,<APN_user>,<APN_password>,0,2,0,1,,,,,FFFF$AT+GTSRI=gl310m,3,,1,racemap.com,5000,racemap.com,5000,,10,1,1,0,60,,FFFF$
```

{% endtab %}

{% tab title="GL300M" %}

```
AT+GTBSI=gl300m,<your_APN>,<APN_user>,<APN_password>,<your_APN>,<APN_user>,<APN_password>,0,2,0,1,,,,,FFFF$AT+GTSRI=gl300m,3,,1,racemap.com,5000,racemap.com,5000,,10,1,1,0,60,,FFFF$
```

{% endtab %}
{% endtabs %}

#### C) Upload devices to Tracker Management <a href="#upload-to-tracker-page" id="upload-to-tracker-page"></a>

With step(s) (A to) B the devices are configured for the communication with RACEMAP. Read how to add the devices to the Tracker Management for further messaging.

{% content-ref url="/pages/9zKei47tnVUSkRlJC5Bv" %}
[Add GPS trackers](/tracker-management/add-devices)
{% endcontent-ref %}

#### D) Load configuration for your devices <a href="#load-config" id="load-config"></a>

Step D) is processed in Tracker Management. Therefore the trackers need to have established a connection with the Tracker Management.

Select the devices, and use "Load Configuration" message. This command loads a hosted configuration file. Use RACEMAP configuration URL or paste the URL to load your own configuration file.

<div data-full-width="true"><figure><img src="/files/LggthQ8AWlKImZ24yAVx" alt=""><figcaption><p>The "Load Configuration" command loads a hosted configuration file.</p></figcaption></figure></div>


# Configuration via cable

Configure Queclink's GL3xx devices one by one using a computer and a data cable. Step-by-step instructions for initial configuration of the devices for live tracking in RACEMAP.

#### Requirements

* Software: Queclink manage tool
* PC: The manage tool works on Windows computers only.
* Data cable for USB port: Each device type of the GL3xx series requires a specific data cable.

<figure><img src="/files/O4bUogsK7Y9sh9gMdtjS" alt=""><figcaption><p>Queclink UART cable is required to configurate GL3xx GPS trackers through management tool</p></figcaption></figure>

Download the Queclink manage tool corresponding to your device type.

{% tabs %}
{% tab title="GL320M" %}
<https://static-cdn.racemap.com/trackers/firmwares/gl320m/latest-manage-tool.zip>
{% endtab %}

{% tab title="GL310M" %}
<https://static-cdn.racemap.com/trackers/firmwares/gl310m/latest-manage-tool.zip>
{% endtab %}

{% tab title="GL300M" %}
<https://static-cdn.racemap.com/trackers/firmwares/gl300m/latest-manage-tool.zip>
{% endtab %}

{% tab title="GL300W" %}
<https://static-cdn.racemap.com/trackers/firmwares/gl300w/latest-manage-tool.zip>
{% endtab %}

{% tab title="GL300" %}
<https://static-cdn.racemap.com/trackers/firmwares/gl300/latest-manage-tool.zip>
{% endtab %}
{% endtabs %}

{% hint style="info" %}
Download Queclink manage tool for a specific firmware version (e.g. R01A11V14) according to the format of the sample URL. <https://static-cdn.racemap.com/trackers/firmwares/gl320m/R01A11V14/manage-tool.zip>
{% endhint %}

{% hint style="info" %}
The computer needs a driver to enable the USB port for communication with the uart chip in the data cable.
{% endhint %}

Device settings of the computer: COM >> USB-Serial CH340

<figure><img src="/files/OjHe5lL1ZJFPnkF3kuZh" alt=""><figcaption></figcaption></figure>

We used this driver: <https://www.wch-ic.com/search?q=CH340&t=downloads>

<figure><img src="/files/KZnLP7rL37QdNJjG3Arv" alt=""><figcaption></figcaption></figure>

For GL300M we installed the driver according to this documentation: <https://embetronicx.com/uncategorized/fixed-prolific-pl2303ta-usb-to-serial-and-windows-11/>

### Load RACEMAP configuration on your device

Download the latest Racemap configuration file config.ini.

{% tabs %}
{% tab title="GL320M" %}
<https://static-cdn.racemap.com/trackers/configs/gl320m/config.ini>
{% endtab %}

{% tab title="GL310M" %}
<https://static-cdn.racemap.com/trackers/configs/gl310m/config.ini>
{% endtab %}

{% tab title="GL300M" %}
<https://static-cdn.racemap.com/trackers/configs/gl300m/config.ini>
{% endtab %}

{% tab title="GL300" %}
<https://static-cdn.racemap.com/trackers/configs/gl300/config.ini>
{% endtab %}
{% endtabs %}

Rename file ending to GL320M, respectively.

<figure><img src="/files/zLDAcB133U3S2vtJNV4T" alt=""><figcaption></figcaption></figure>

* Turn on the GPS tracker.
* Connect the data cable to a COM port.
* Connect the data cable to the device.
* Open the Queclink manage tool.
* Select the COM port and click 'Try to Connect'.
* Click 'Read All from Device' will show the IMEI of your device.

<figure><img src="/files/3ZnjqYhjxTxTcjjwMXut" alt=""><figcaption><p>Select the COM port</p></figcaption></figure>

<figure><img src="/files/HEuYMIZUUiBOuYOsobvD" alt=""><figcaption><p>'Read All from Device' will show the IMEI of the connected device.</p></figcaption></figure>

{% hint style="info" %}
Note: Different firmware versions may require specific manage tool versions, so the combination of firmware and manage tool might differ.

The 'Read All from Device', 'Send All to Device', and 'Load from Local' functions in the tool apply a configuration file. If the tool encounters an unknown command, it issues a warning. Check the warning and proceed.
{% endhint %}

<figure><img src="/files/UZvQuVX0T9j6NN3U4KQd" alt=""><figcaption><p>Check the warnings and proceed.</p></figcaption></figure>

Click 'Load from Local' and select the configuration file config.GL320M.

<figure><img src="/files/QmH2PgELtPlsMNNhPCbO" alt=""><figcaption><p>'Load from Local' to select the configuration file config.GL320M</p></figcaption></figure>

Click 'Send All to Device' to apply the configuration file config.GL320M on the device. With 'Operation Log' you can monitor this process. Use 'COM Wizard' to continue with the next device.

<figure><img src="/files/h1YmZ64C7fycJL0p275b" alt=""><figcaption><p>'Send All to Device' writes the configuration on the device.</p></figcaption></figure>

### Configure your SIM card

* Insert your SIM card in the device.
* Turn on the tracker.
* Connect the data cable to a COM port.
* Connect the data cable to the device.
* Open the manage tool.
* Select the COM port and click 'Try to Connect'.
* Click 'Read All from Device' will show the IMEI of the connected device.
* Select 'Server Connection' >> 'Bearer Setting Information'

![Server Connection >> Bearer Setting Information](/files/K0xOHTETDfoU2TdEhek4)

<figure><img src="/files/Xu84n1xFEofROKIjkm7C" alt=""><figcaption><p>Backend Server Register Information</p></figcaption></figure>

* Paste the APN information of your SIM card provider and overwrite the previous filling\
  **required:** APN for LTE and GPRS, normally both same\
  **optional:** USERNAME and PASSWORD
* Send the command to your tracker.
* Use 'COM Wizard' to continue with the next device.


# Update firmware

Remote firmware update of Queclink GL3xx GPS Tracker with RACEMAP Tracker Management

* Add the GPS devices to Tracker Management

{% content-ref url="/pages/9zKei47tnVUSkRlJC5Bv" %}
[Add GPS trackers](/tracker-management/add-devices)
{% endcontent-ref %}

* Turn devices on
* Wait for devices have connected with RACEMAP
* Send message "Start Firmware Update", the command triggers four times to update the hosted firmware.

{% content-ref url="/pages/WEc6rUIhSCe1qyxMD4Sa" %}
[Send messages](/tracker-management/messages)
{% endcontent-ref %}

<figure><img src="/files/FjVDS1x1oNxcklabDpRp" alt="" width="545"><figcaption></figcaption></figure>

{% hint style="info" %}

#### Hints for a smooth firmware update

* The firmware file must be hosted on HTTP. HTTPS is not supported — the tracker cannot download from HTTPS URLs.
* Reboot the GPS tracker before sending the "Update firmware" message.
* The device must hold a stable server connection for the entire duration of the update. Any interruption will cause it to fail.
  * Avoid basements and enclosed rooms — poor signal is the most common reason updates fail.
  * Before starting, configure the device for stability: disable non-movement detection and set a high-frequency report interval (e.g., 10 sec / 10 sec).
  * Use the SIG column in [tracker management](/tracker-management) to verify signal strength before triggering the update.\
    ![](/files/H7INwra15E0aKQAmtG1e)
    {% endhint %}

{% tabs %}
{% tab title="GL320M" %}
hosted FW: R01A13V03\_R10A02V03

```
AT+GTUPD=gl320m,0,3,10,0,,,http://static-cdn.racemap.com/trackers/firmwares/gl320m/latest.enc,,0,,,0001$
```

Important: Devices running older firmware must first be updated to R01A12V09, which is the required bridge firmware, before applying the latest version. This is the URL for FW: R01A12V09 <http://static-cdn.racemap.com/trackers/firmwares/gl320m/R01A12V09/GL320M_B7K1_R01A12V09.enc>
{% endtab %}

{% tab title="GL310M" %}
hosted FW: R01A11V05

```
AT+GTUPD=gl310m,0,3,10,0,,,http://static-cdn.racemap.com/trackers/firmwares/gl310m/latest.enc,,0,,,0001$
```

{% endtab %}

{% tab title="GL300M" %}
hosted FW: R20A14V02

```
AT+GTUPD=gl300m,0,3,10,0,,,http://static-cdn.racemap.com/trackers/firmwares/gl300m/latest.enc,,0,,,0001$
```

{% endtab %}
{% endtabs %}

* Updating the firmware does not reset the previous configuration.
* Updating the firmware can be done while charging devices.
* If the battery level is too low the device aborts the update process.
* You might send the custom command `AT+GTUPD` multiple times as devices might fail to complete downloading the firmware.
* Devices automatically reboot after installing the new firmware, which you observe by flashing LEDs. GL320M and GL310M flash with blue LED, GL300M does not noticeably flash with blue LED.
* Devices remain turned on and will try to reconnect with the tracker management.
* The firmware version in the tracker management is automatically updated. Verify the tracker info.

<figure><img src="/files/jkUY27W2sFpp2daRhOHX" alt="" width="375"><figcaption><p>Current fw version of devices is automatically requested</p></figcaption></figure>


# Configuring trackers for increased autonomy

Increasing the Running Time of GL3xx LTE GPS trackers

For long-lasting sports events such as endurance cycling, it is crucial to extend the autonomy of GL3xx devices. You can significantly increase the running time of your device by minimizing the communication between the device and the server.

{% content-ref url="/pages/-LT3ehO2UEcTbOBZOJF0" %}
[Tracker management](/tracker-management)
{% endcontent-ref %}

The tracker management provides four commands to reduce communication and maximize the autonomy of Quecklink GL3xx LTE trackers. Apply the four commands for optimal autonomy:

* **Activate Non-Movement-Detection** - This message enables non-movement detection feature: With no motion detected by the internal motion sensor for a specified period of time, the device automatically enters sleep mode. Communication with the server is reduced to minimize power consumption.
* **Deactivate Heartbeat** - This command stops the periodic messages between the device and the server. Note: This may reduce the stability of the mobile connection.
* **Deactivate (Device) Events** - The device stops sending events such as turning ON, turning OFF, charging, and rebooting. Note: The tracker management receives less information about the current status of the device.
* **Deactivate Server Acknowledge** - The device will no longer wait for a response from Racemap server.
* **Disable the periodical Device Info Report**

<figure><img src="/files/9eO9DCeQ5Go2n9vtgstf" alt=""><figcaption></figcaption></figure>

With these settings and a report interval of 5 minutes, it is possible to achieve an autonomy of four days and five hours. The battery decreases from 100% to 20%.

<figure><img src="/files/UBENPwpa4Wel4z0hQ9d5" alt=""><figcaption></figcaption></figure>


# Track Box forwarding

Set RACE|RESULT track boxes directly to racemap server to reduce the delay when real-time processing data

* use RACE|RESULT TagTool: <https://www.raceresult.com/en/software/download.php>
* set "Status URL": <http://trackping.racemap.com/api/v2/trackping_input/pings>
* set "Track Ping URL": <http://trackping.racemap.com/api/v2/trackping_input/pings>

![](/files/tebuEPhMgfDlrt6YYDUM)

{% hint style="info" %}
Read more about track box configuration in RACE|RESULT knowledge base: <https://www.raceresult.com/en/support/kb.php?id=23544-Configuration-Using-TagTool--Management-Box>
{% endhint %}


# HTTP tracker

Flexibly forward geo coordinates from any location service or your tracking devices to RACEMAP with HTTP trackers.

To utilize 3rd-party sources of geographic coordinates, such as

* your GPS tracker backend that works as a gateway,
* a public source of geo data like a public transportation network, or a naval positioning system,
* built-in GPS in camera systems during TV productions.

Instead of connecting a physical device, you create a virtual tracker that receives location updates through an HTTP endpoint.

### Create an HTTP tracker

* Go to the [tracker management](https://racemap.com/admin/trackers) and click "+ Add Tracker".
* This opens a modal, select "HTTP GPS Tracker" as tracker type.
* The unique tracker ID is generated automatically, provide a device name.
* Confirm with "Add Tracker" and the new HTTP tracker is created
* The new HTTP tracker is shown in the device list of your tracker management.

<figure><img src="/files/cZGDIvHbuJWzhYb4m98B" alt=""><figcaption></figcaption></figure>

### Send locations to the HTTP tracker

Send messages to the specific endpoint of the HTTP tracker.

```
POST /api/trackers/:id/points
```

{% hint style="warning" %}
Copy the required `id` for the endpoint in the tracker management, info tab.\
`id` **is not** the generated tracker id!

<img src="/files/KIsXd3TpkeE3CIY1lp8w" alt="" data-size="original">
{% endhint %}

Sample request in the terminal:

```
curl -X POST \
  --url https://racemap.com/api/trackers/69b12d04a440a83c52a9ee8c/points \
  --header 'authorization: Bearer {{API_TOKEN}}' \
  --header 'content-type: application/json' \
  --data '[{ "lng": 13.74179, "lat": 51.05471, "time": "2026-03-11T09:15:00Z" }]'
```

{% hint style="info" %}
Only authorized users can direct to the endpoint.\
[Create your authentication with an API token.](/api/authentication)
{% endhint %}

When directing valid and current coordinates, the HTTP tracker updates its location on the map and APIs.

#### Parameters

<table data-full-width="false"><thead><tr><th width="188">Field</th><th width="311">Description</th><th width="294">Sample</th><th data-hidden></th></tr></thead><tbody><tr><td><code>lng</code></td><td>Longitude in degree</td><td><code>13.74179</code></td><td></td></tr><tr><td><code>lat</code></td><td>Latitude in degree</td><td><code>51.05471</code></td><td></td></tr><tr><td><code>time</code></td><td>Timestamp of the coordinate, UTC</td><td><code>"2022-01-24T23:00:00.000Z"</code></td><td></td></tr><tr><td><code>elv</code></td><td>Elevation in meter, optional</td><td><code>445</code></td><td></td></tr></tbody></table>


# Insiders GPS trackers

Use Insiders 10 Hz GPS trackers with RACEMAP to access real-time, high-precision sports data.

Insiders (<https://insiders.live/>) provides high-precision sports data devices that collect athlete performance metrics and transmit them to the insiders cloud in real-time. RACEMAP directly retrieves this data, ensuring seamless integration on our tracking platform.

### Connecting insiders with RACEMAP

To integrate insiders devices with RACEMAP, follow these steps.

1. Register on RACEMAP - If you don't have an account, sign up here: <https://racemap.com/auth/register>
2. Set up your insiders account - Log in to your insiders manager account and take ownership of your insiders devices. Follow the setup according to your device type ([INTENSE](https://help.insiders.live/en/blog/2023/03/13/how-to-activate-your-intense/) or [INSPIRIT](https://help.insiders.live/en/blog/2023/03/10/how-to-activate-your-inspirit/)).
3. Contact <support@racemap.com> with your manager account credentials (username/email and password). If you prefer not to share your password, change it to a temporary value.
4. We will configure RACEMAP to receive data from your insiders devices via insiders cloud.
5. Confirmation - Once setup is complete, we will notify you.

### Add insiders devices to tracker management

After receiving confirmation you have to [add your insiders devices to the tracker management](https://racemap.com/admin/trackers/add) to operate the devices on RACEMAP.

{% content-ref url="/pages/9zKei47tnVUSkRlJC5Bv" %}
[Add GPS trackers](/tracker-management/add-devices)
{% endcontent-ref %}

Select "Add Tracker," choose either "Intense" or "Inspirit" as the device class, then select your device and assign it an alias.

<figure><img src="/files/Nyh3ILDNi1OduPfQHdMq" alt="" width="563"><figcaption><p>Select tracker type: "Intense" or "Inspirit"</p></figcaption></figure>

## Add insiders device to an event

Your insiders trackers are now ready for use. To let the devices send real-time location data to RACEMAP

* Add the devices to an event
* Within the start- and the end time of the event (not in an upcoming event).

{% content-ref url="/pages/XXI5G3fvMe8yhwW6XSBl" %}
[Add devices to event](/tracker-management/add-to-event)
{% endcontent-ref %}

{% hint style="info" %}
Check the firmware of your insiders device here:\
<https://dev.insiders.live/>
{% endhint %}


# Using GPS trackers On-Site

References and experiences using GPS trackers for live tracking of long-distance sports events.

### Basics

Most types of GPS trackers basically operate with the three main components:

1. **GPS module**: Determines the device's location.
2. **GSM modem**: Sends all data such as location, battery level, etc. via mobile network to the RACEMAP.
3. **Memory:** If the device is unable to establish a TCP connection with RACEMAP, no data can be sent, even if the GPS module is working perfectlyy. In this case, the data is stored in the device’s memory until a connection is re-established.

In [RACEMAP tracker management](/tracker-management) system:

* The **CON** (Connection) column shows the duration since when the device established a TCP connection to RACMEAP respectively since when the socket was closed.
* The **LOCATION** column provides the duration of the most recent known location and the status of the GPS module.

<figure><img src="/files/LZ8dIo7bAVpNJKzGUMbU" alt=""><figcaption><p>Status of GSM modem and GPS module in the tracker dashboard</p></figcaption></figure>

For example, during a trail run with poor reception - such as between the 30K and 38K marks - the tracker may temporarily lose its connection. During this period, real-time data won't be transmitted to RACEMAP but kept in memory. However, once the device reconnects, it will upload the stored data, filling in gaps in the race playback, so all data will be available in the event replay after a short delay.

You can see this relationship very well in the [track chart](https://docs.racemap.com/hardware-for-live-tracking/debugging#track-chart).

You can schedule commands for a group of GPS trackers to automatically adjust the devices' settings according to the time.

A couple of days before the race:

* Switch on all devices manually.
* Place devices for a good connection.
* Select all devices in tracker management.
* Check connection and location in tracker management.
* Clear undelivered commands from messages timeline before scheduling new commands with the "Revoke all messages" function.

<figure><img src="/files/YJfckZxVlt8j7Jv2FSxI" alt=""><figcaption></figcaption></figure>

* Schedule commands according to SLEEP, AWAKE and RACE profile.
* Don't switch devices off after you have scheduled commands.

**SLEEP profile:** "heartbeat", every 10 to 20 min refreshes the connection to Racemap, if there is reception

<table data-full-width="false"><thead><tr><th width="81">#</th><th width="269">Command</th><th width="257">Parameter</th><th>Time</th></tr></thead><tbody><tr><td>S1</td><td>GPS Module</td><td>mode: 1</td><td>Now</td></tr><tr><td>S2</td><td>GPS Report Interval</td><td>3600; 3600</td><td>Now</td></tr><tr><td>S3</td><td>Non-Movement Detection</td><td>10; 3600; 3600</td><td>Now</td></tr></tbody></table>

{% hint style="info" %}

* Participants must not use the power button! When deploying the devices to participants the devices are turned on already.
* Devices lose about 5 to 7 % battery level in 24 hrs.
  {% endhint %}

**AWAKE profile:** It takes up to 60 min until all devices receive the new configuration. Check the tracker management if there is a device that does not establish a connection. The participant might have turned the device off. You still have time to change the device before the race starts.

<table><thead><tr><th width="77">#</th><th width="260">Command</th><th>Parameter</th><th>Not before</th><th>Not after</th></tr></thead><tbody><tr><td>A1</td><td>GPS Report Interval</td><td>180; 180</td><td>4 hrs before race starts</td><td>3 hrs before race starts</td></tr><tr><td>A2</td><td>Non-Movement Detection</td><td>10; 180; 180</td><td>4 hrs before race starts</td><td>3 hrs before race starts</td></tr></tbody></table>

**RACE profile:** It takes up to 10 min until all devices receive the new configuration.

<table><thead><tr><th width="84">#</th><th width="258">Command</th><th width="134">Parameter</th><th>Not before</th><th>Not after</th></tr></thead><tbody><tr><td>R1</td><td>GPS Module</td><td>mode: 0</td><td>1 hr before race starts</td><td>no entry</td></tr><tr><td>R2</td><td>GPS Report Interval</td><td>10; 10</td><td>1 hr before race starts</td><td>no entry</td></tr></tbody></table>

{% hint style="info" %}

* Devices lose about 5 % battery level every 1 hr.
* With 60; 60 parameter setting, devices lose about 2 % battery level every 1 hr.
  {% endhint %}

For stage events you can schedule subsequent SLEEP and RACE profiles for each stage.

After the race: Use the "Shut down" command to remotely switch devices off. When the device has received the shot down it must be switched on manually. There is no possibility to remotely turn on a device.

### Fix GPS trackers for different types of Sports

<figure><img src="/files/haeAU8nQivigmB2IYZLd" alt=""><figcaption><p>Seal GPS Tracker in a waterproof bag and place it under the swimming cap.</p></figcaption></figure>

<figure><img src="/files/fxuSsq8UnIlEM2orFtTg" alt=""><figcaption><p>Fix the GPS tracker to a bag using an adapter with velcro strap.</p></figcaption></figure>


# Debug tracking devices

Analyzing data sent through the mobile network and debug GPS hardware.

## Data from Racemap platform

### Connection Chart

<figure><img src="/files/9PPnJr0USZN5IDapj0nA" alt=""><figcaption><p>Green to brown: delay of received coordinates, blue battery</p></figcaption></figure>

The interactive Connection Chart shows your GPS device's connectivity and communication mechanics at running operations. The Connection Chart features:

* Delay of received coordinates: The y-axis indicates the delay of received coordinates in seconds, sent from memory.
* Battery History: A dedicated second y-axis displays the battery history of your GPS tracker, enabling you to monitor power consumption.
* Network insights such as: Hover for Mobile Country Code (MCC), Mobile Network Code (MNC), Location Area Code (LAC), Cell ID, and the radio technology.
* Single events such as: Open socket, close socket, heartbeat, device info, movement, no movement, and power off.

<figure><img src="/files/7YNZMiXs15OqH8fEh4mV" alt=""><figcaption><p>Access the Track Chart for a specific device directly in the tracker management.</p></figcaption></figure>

{% hint style="success" %}
**syntax** `https://racemap.com/admin/track/<appId>?startDate=2023-11-14T12:30:00.000Z&endDate=2023-11-14T16:30:00.000Z`
{% endhint %}

### Tracks API

Pull the timestamps when a specific device recorded a location and when Racemap server received the same location, eg. to check the delay in sending live data through the mobile network.

{% hint style="success" %}
**syntax** `https://racemap.com/api/tracks/trackId/points?startTime=startTime&endTime=endTime`

**sample** <https://racemap.com/api/tracks/59e75469c8adf3c73d75fc66/points?startTime=2018-05-05T10:00:00Z&endTime=2018-05-05T10:15:00Z>
{% endhint %}

* `startTime` and `endTime` timestamps in UTC of the first and the last location in the query
* `trackId` unique Racemap ID of all locations of a specific device

![copy  trackId of the device you want to investigate in participants API](/files/5lDlqrDQwJ2NQcfxzQjO)

{% content-ref url="/pages/-M\_zgpFYgo28IJBo4zVF" %}
[\*/starters, athlete data](/api/participants)
{% endcontent-ref %}

| parameter    | description                                                                                                                  | type   |
| ------------ | ---------------------------------------------------------------------------------------------------------------------------- | ------ |
| `lng`        | longitude of location                                                                                                        | string |
| `lat`        | latitude                                                                                                                     | string |
| `elv`        | elevation                                                                                                                    | string |
| `time`       | timestamp in UTC when device recorded the location, in case of interpolation between last two points => linear interpolated  | string |
| `receivedAt` | timestamp in UTC when Racemap recorded the location, in case of interpolation between last two points => linear interpolated | string |

```json
[
{
"lng": 13.818634,
"lat": 51.107761,
"time": "2018-05-05T10:00:09Z",
"elv": 261,
"receivedAt": "2018-05-05T10:00:23.644Z"
},
{
"lng": 13.817738,
"lat": 51.107412,
"time": "2018-05-05T10:00:24Z",
"elv": 276,
"receivedAt": "2018-05-05T10:00:37.785Z"
},
{
"lng": 13.817476,
"lat": 51.107295,
"time": "2018-05-05T10:00:39Z",
"elv": 273,
"receivedAt": "2018-05-05T10:00:52.769Z"
},
{
"lng": 13.817476,
"lat": 51.107295,
"time": "2018-05-05T10:00:53Z",
"elv": 273,
"receivedAt": "2018-05-05T10:01:09.064Z"
},
{
"lng": 13.816854,
"lat": 51.106363,
"time": "2018-05-05T10:01:08Z",
"elv": 245,
"receivedAt": "2018-05-05T10:01:22.696Z"
},
{
"lng": 13.816932,
"lat": 51.105763,
"time": "2018-05-05T10:01:23Z",
"elv": 235,
"receivedAt": "2018-05-05T10:01:37.651Z"
},
{
"lng": 13.816588,
"lat": 51.105129,
"time": "2018-05-05T10:01:38Z",
"elv": 220,
"receivedAt": "2018-05-05T10:04:40.289Z"
}
]
```

## Record logs of tracking hardware

### Queclink GL320

#### Requirements

* Tracking device is turned on.
* UART data cable
* Windows computer
* We use the CoolTerm software to record the logs of the tracking device. Download CoolTerm here <https://coolterm.en.lo4d.com/windows>
* Enable the USB port of the computer for UART communication.\
  [Read documentation.](/gps-devices/config/cable#requirements)

{% hint style="info" %}
The device needs to be connected to the computer to record logs. You have to take the computer with you when reproducing specific tracking scenarios.
{% endhint %}

On Clicking on CoolTerm icon. The first window you see is this

<figure><img src="/files/STKNOG8I38RJYt5FlCBX" alt=""><figcaption></figcaption></figure>

When connecting a powered-on device to the COM port via the UART cable, CoolTerm won't display it automatically. Users must configure CoolTerm each time it's opened, making sure the device is powered on and connected before initiating the application.

**Settings in CoolTerm**

Options >> Serial Port:

* UART: Select the port which is enabled for UART communication.
* Baudrate: 115200

<figure><img src="/files/U9yNdQxwhpr6wvUNWRUw" alt=""><figcaption></figcaption></figure>

Terminal:

* Line Mode
* Local Echo

<figure><img src="/files/bT5BB0in9ASnEYd9J6sj" alt=""><figcaption></figcaption></figure>

Receive

* Add timestamps to received data

<figure><img src="/files/wPUxSm4rPpvCZqKR9t9M" alt=""><figcaption></figcaption></figure>

File Capture:

* Select the file in which you want to capture the logs.

**Commands:**

Send the command to the device to send logs using the command field:\
`AT+UARTLOG=9`

Send the command to the device to stop sending battery-related logs:\
`AT+UARTLOG=0,BAT`

Send the command to the device to stop sending logs:\
`AT+UARTLOG=0`

<figure><img src="/files/IhxG0AVfy9wD10xBhBXT" alt=""><figcaption></figcaption></figure>


# Apps

RACEMAP offers two distinct apps - Tracking App and Orga App - each designed for different users and purposes during sports events.

### Tracking App

The RACEMAP Tracking App is for participants and spectators. It provides live GPS tracking of athletes and keeps watchers updated on race progress.

Key features:

* Real-time location updates of participants
* Race status and timing information
* Interactive map view for spectators

This app is focussed on participants' race tracking and spectator engagement.

{% content-ref url="/pages/pRPakpUVDPxwhG1ls0Xb" %}
[Tracking app](/apps/tracking)
{% endcontent-ref %}

### Orga App

The RACEMAP Orga App is for users managing a large number of GPS trackers. It is not intended for participants or spectators.

Key features:

* Quick identification and selection of GPS devices via QR codes
* Efficient assignment of trackers to participants
* Parallel operations with multiple Orga Apps working simultaneously

This app connects trackers via QR code scanning, ensuring smooth operations for event staff.

{% content-ref url="/pages/9VhCSLoJpJm25YX7QObE" %}
[Orga app](/apps/orga)
{% endcontent-ref %}


# Tracking app

RACEMAP app & our white-label apps for versatile, multi-event tracking: Turn participants' smartphones into a live tracking device & show the race for spectators.

{% tabs %}
{% tab title="Google Play" %} <a href="https://play.google.com/store/apps/details?id=racemap.de" class="button primary" data-icon="google-play">Google Play</a>

<div align="left" data-full-width="false"><figure><img src="/files/cTpK4oJB24FfMEv64856" alt="" width="300"><figcaption><p>Get free RACEMAP app in Google Play</p></figcaption></figure></div>
{% endtab %}

{% tab title="App Store" %} <a href="https://apps.apple.com/de/app/racemap/id640797527" class="button primary" data-icon="app-store">App Store</a>

<div align="left"><figure><img src="/files/laNIVj8mKCN4cM3CiGd0" alt="" width="300"><figcaption><p>Get free RACEMAP app in the App Store</p></figcaption></figure></div>
{% endtab %}
{% endtabs %}

* Exciting information: Easy-to-use interface provides a live visualization of all participants.
* Scalable live tracking for all kinds of events: Set visibility for each of your competitions to reach your target group.
* RACEMAP app saves your on-site staff time while live tracking the race for little cost.

<figure><img src="/files/XHDIdb6VOVHRWOuXVdgz" alt="" width="360"><figcaption></figcaption></figure>

{% embed url="<https://youtu.be/NnZNs7yyZOY>" %}


# Custom app version

White-label RACEMAP tracking app for an annual event, a series, and for a timer to provide many events.

<figure><img src="/files/9AQQ52xtdzjtZmnjlAQg" alt="" width="375"><figcaption></figcaption></figure>

RACEMAP offers a branded version of our GPS tracking app. You can adapt this custom app solution for one specific event, for an event series, and as a timer to show all your events. The custom app includes the following benefits:

* Your branding is featured in the app for participants, spectators, and organizers.
* Separate listings in both Google Play (Android) and the App Store (iOS).
* Select specific events from your RACEMAP account to be exclusively published in your custom app(s).

We can deliver your app within **two weeks** after receiving the following content:

### Meta information

1. What languages should be supported (English, German, French, Spanish, Polish, Turkish)
2. List of existing events in RACEMAP to build screenshots for the app stores. Finished events can be used as well.
3. A contact mail address on your side for receiving updates about the app.
4. The preferred release date, keep two-weeks buffer in mind.
5. Three colors as html hex code in the flavors normal, light, and dark. You can use tools like [color pickers ](https://htmlcolorcodes.com/color-picker/)to get them.

<figure><img src="/files/6HWzUMhDTxuVZ8uLivoE" alt=""><figcaption><p>Three color codes and it's usage in the custom app. Set normal (<kbd>007f0e</kbd>), light (<kbd>d0e7d2</kbd>), and dark (<kbd>009b08</kbd>) color hex code.</p></figcaption></figure>

### Images

<table><thead><tr><th width="176">Name</th><th width="119">Format</th><th width="179.66668701171875">Resolution</th><th>Transparency</th></tr></thead><tbody><tr><td>In app logo</td><td><a href="https://en.wikipedia.org/wiki/SVG">SVG</a></td><td><a href="https://en.wikipedia.org/wiki/Image_resolution">300x80</a> px</td><td>transparent background</td></tr><tr><td>Launch logo</td><td>SVG</td><td>1024x1024 px</td><td>no</td></tr><tr><td>Feature graphic</td><td><a href="https://en.wikipedia.org/wiki/PNG">PNG</a></td><td>1024x500 px</td><td>no</td></tr><tr><td>Icon</td><td>SVG</td><td>1024x1024 px</td><td>no</td></tr></tbody></table>

<figure><img src="/files/lCH3ZIpCzU1bbT0W7YB2" alt=""><figcaption><p>Required four images for custom app: In app logo, launch logo, feature graphic, and icon</p></figcaption></figure>

### Texts

Provide all texts in the languages supported by your custom app.

**App store descriptions**

* Short Descriptio&#x6E;**\*** max. 80 characters
* Long Descriptio&#x6E;**\*** max. 400 characters

**Name of the custom app**

* Short nam&#x65;**\*** for app menu max. 12 characters
* Long nam&#x65;**\*** for stores max. 30 characters

### URLs

* Suppor&#x74;**\***
* Marketing
* Terms of Use

### Contact information

* Support Emai&#x6C;**\***
* Phone Numbe&#x72;**\***
* WhatsApp etc.
* List of email addresses for iOS testflight

**(\*) Mandatory information**

Send information to: **<apps@racemap.com>**


# Event details

The event details page summarizes information of your sports event in RACEMAP app.

{% hint style="success" %}
Set up the event details in the visualization settings of your event.

```
https://racemap.com/admin/events/:eventId/visualisation
```

{% endhint %}

{% embed url="<https://www.youtube.com/watch?v=1i5bja2Pboo>" %}

### Add basic event information

<figure><img src="/files/iFlhvHGEPrlh66INXjEh" alt=""><figcaption></figcaption></figure>

1. 𝗪𝗲𝗯𝘀𝗶𝘁𝗲: Link displayed. Tapping the globe icon opens this URL in the browser.
2. 𝗖𝗼𝗻𝘁𝗮𝗰𝘁 𝗣𝗵𝗼𝗻𝗲: Phone button shown. Tapping the icon opens the phone dialer with this number.
3. 𝗗𝗲𝘀𝗰𝗿𝗶𝗽𝘁𝗶𝗼𝗻: Event description text shown. Provide a short summary or key message.
4. **Contact Email Address:** Email address shown. Tapping the envelope icon opens the mailing app and users can contact the event host.
5. 𝗖𝘂𝘀𝘁𝗼𝗺 𝗟𝗶𝗻𝗸 𝗕𝘂𝘁𝘁𝗼𝗻: A custom button with caption and URL shown. Tapping it opens the provided link (e.g., FAQ, donation).
6. **Technical Support Email Address:** Not shown. Users' messages from the help page related to a specific event will be sent to this address.

### Add online registration

RACEMAP lets you integrate an online registration form into your event details page in two ways - each opens the form within the app when participants click the **Registration** button.

#### External registration

Paste the URL of your registration form.

<figure><img src="/files/TJs2FOk3g94PVA8lZNCW" alt=""><figcaption></figcaption></figure>

#### RACE RESULT registration

To embed the RACE RESULT form directly within RACEMAP app, complete the following steps.

Paste the RACE RESULT Event ID in your event’s integrations settings.

<figure><img src="/files/kqNpVyJE6oyeytjMheIw" alt=""><figcaption></figcaption></figure>

In your event's visualization settings:

* Select RACE RESULT from the registration options.
* Enter your registration key and the exact form name, these values must match.

<figure><img src="/files/EhSCwChmD4ErZgVInwPx" alt=""><figcaption></figcaption></figure>

Locate your registration key in RACE RESULT 12:

* Go to Main Window, Registration forms
* Select the form you want to embed
* Click General Settings, and in Website integrations you can copy the key.

<figure><img src="/files/vIiJS9lm2wApUq75o5Lg" alt=""><figcaption></figcaption></figure>


# Deep links

Deep links run functions in the tracking app. Integrate the deep links into your workflows to provide a seamless user experience with RACEMAP apps.

Use the deep links to automate interactions with participants and spectators:

* Add redeem key in the registration email
* open a specific event map
* open a leaderboard

You need to know the passcode or keys and the event id to flexibly compose the deep links.

* [Keys and the passcode](/apps/tracking/keys#connect-smartphone) connect the participants' phones for live tracking in a specific event.
* Copy the `eventId` from the URL in event settings\ <img src="/files/-MWUJXNR3kNkf8C4ydOw" alt="" data-size="original">

{% hint style="success" %}
<https://racemap.app>:

* Install RACEMAP App
* Test deep links on your phone and desktop to compare different behaviors.
  {% endhint %}

<table><thead><tr><th width="258">Syntax</th><th width="226">Sample deep link</th><th>Behavior in the app</th><th>Behavior on desktop</th></tr></thead><tbody><tr><td><code>https://racemap.app</code></td><td><a href="https://racemap.app">https://racemap.app</a></td><td>home</td><td>modal to download RACEMAP App</td></tr><tr><td><code>https://racemap.app/events/:eventId</code></td><td><a href="https://racemap.app/events/5dfce57c9240c60001f71a88">https://racemap.app/events<br>/5dfce57c9240c60001f71a88</a></td><td>open tracking map</td><td>open tracking map</td></tr><tr><td><code>https://racemap.app/events/:eventId/player</code></td><td><a href="https://racemap.app/events/5dfce57c9240c60001f71a88/player">https://racemap.app/events<br>/5dfce57c9240c60001f71a88/player</a></td><td>open tracking map</td><td>open tracking map</td></tr><tr><td><code>https://racemap.app/player/:eventId</code></td><td><a href="https://racemap.app/player/5dfce57c9240c60001f71a88">https://racemap.app/player<br>/5dfce57c9240c60001f71a88</a></td><td>open tracking map</td><td>open tracking map</td></tr><tr><td><code>https://racemap.app/timing/:eventId</code></td><td><a href="https://racemap.app/timing/5dfce57c9240c60001f71a88">https://racemap.app/timing<br>/5dfce57c9240c60001f71a88</a></td><td>open leaderboard</td><td>open leaderboard</td></tr><tr><td><code>https://racemap.app/eventgroups/:eventId</code></td><td><a href="https://racemap.app/eventgroups/66f26831d6727dc941fb2c72">https://racemap.app/eventgroups/66f26831d6727dc941fb2c72</a></td><td>open group or stage map</td><td>open group or stage map</td></tr><tr><td><code>https://racemap.app/redeem_key?key=[key]</code></td><td><a href="https://racemap.app/redeem_key?key=6G615L">https://racemap.app<br>/redeem_key?key=6G615L</a></td><td>redeem passcode or key</td><td>modal to download RACEMAP App</td></tr><tr><td><code>https://racemap.app/:eventId/edit</code></td><td><a href="https://racemap.app/5dfce57c9240c60001f71a88/edit">https://racemap.app/5dfce57c9240c60001f71a88/edit</a></td><td>edit bib and name, if user connected App for live tracking the event</td><td>modal to download RACEMAP App</td></tr><tr><td><code>https://racemap.app/eventdetails/:eventId</code></td><td><a href="https://racemap.app/eventdetails/686285285e17518f774d4ee5">https://racemap.app/eventdetails/686285285e17518f774d4ee5</a></td><td>open event details page</td><td>open tracking map</td></tr></tbody></table>

* The deep links work in the [custom apps](/apps/tracking/white-label) through `custom-name` e.g. `*/:custom-name/:eventId`
  * <https://racemap.app/time2win>
  * <https://racemap.app/chronoConsult>
* Add specific `startNumber` and `name`. Participants don't need to type their name and bib number. `*/redeem_key?key=[key]&startNumber=[STARTNUMBER]&name=[NAME]`. Test this sample on your phone <https://racemap.app/redeem_key?key=6G615L&startNumber=1&name=Peter> .


# Keys and passcode

With keys, participants seamlessly connect RACEMAP App for live tracking or upload their recorded activities. Keys also link participants' data with the tracking app.

![Participants use the passcode or keys to easily connect RACEMAP App for live tracking.](/files/Cx1reJbxKatWT9znOna4)

{% hint style="success" %}
Test live tracking of the event "Easy QR Code Run" with RACEMAP App (passcode 6G615L):

* Leaderboard: [racemap.com/timing/qrcode-test](https://racemap.com/timing/qrcode-test)
* Tracking map: [racemap.com/player/qrcode-test](https://racemap.com/player/qrcode-test)

There are two options for automatically connecting RACEMAP App for live tracking in this event:

* Click the link <https://racemap.app/redeem_key?key=6G615L>
* Scan the QR code (which is equal to the key link)\ <img src="/files/HrjvV95YDNCn7DtCOAyx" alt="" data-size="original">

After sign-up, you can contribute your activities to the activity challenge.
{% endhint %}

Keys are specific [deep links](/apps/tracking/deep-links) that target functions in our apps. Through keys, you can sell live tracking in the online registration for your event. Merge the participant data with a specific key. Distribute the key with the registration email or as a printed QR code. Keys enable an automated and convenient process for live tracking with RACEMAP apps.

## APIs for keys

You can automatically process keys through APIs, e.g., when selling live tracking in an online registration platform. You need to authenticate the requests to the APIs.

{% content-ref url="/pages/1bq15cJtzdnjBPSV9Bx7" %}
[Authentication](/api/authentication)
{% endcontent-ref %}

#### Generating keys via API

Endpoint to automatically generate keys on demand:

```json
 https://racemap.com/api/events/:eventId/actions/generate_starter_keys?count=10
```

Replace `:eventId` with the id of your addressed event. Set the number according to your demand, eg. `11` to generate 11 keys. More keys can be generated at any time.

#### Querying keys via API

Endpoint to automatically retrieve keys:

```json
https://racemap.com/api/events/:evenId/starter_keys?format=json
```

#### Generating QR code images

Endpoint to generate a QR code image for a specific key:

```json
https://racemap.com/api/starters/actions/generate_key_qrcode?key=[key]
```

Replace `[key]` with the desired key. For instance, to generate a QR code for the passcode `6G615L` (from the "Easy QR Code Run" sample), use:

```json
https://racemap.com/api/starters/actions/generate_key_qrcode?key=6G615L
```

The API request returns the QR code image, which you can embed or display directly in your application (e.g., within an email, newsletter, or dashboard).

<figure><img src="https://racemap.com/api/starters/actions/generate_key_qrcode?key=6G615L" alt=""><figcaption></figcaption></figure>

## Properties of keys and the passcode

* Assigned to one specific event, can't be used for a different event,
* Six characters, upper or lower case is irrelevant.
* Each with a specific landing page: `https://racemap.app/redeem_key?key=[key]`.

| Application                                            | Keys                                                                                    | Passcode                                              |
| ------------------------------------------------------ | --------------------------------------------------------------------------------------- | ----------------------------------------------------- |
| Usage for the event                                    | Multiple keys for one event                                                             | One passcode for one event                            |
| Usage by participants                                  | Personalized: each participant uses a different key                                     | Each participant uses the same passcode for one event |
| Merge with participant data                            | Match participant's name & race number with a specific key eg. in registration platform | No match with individual participant data possible    |
| Assign location data during the event - Total activity | Accumulate multiple activities with Racemap App                                         | Accumulate multiple activities with Racemap App       |
| Assign location data - Sum-up activities               | With Racemap App and upload recorded activities                                         | With Racemap App, only                                |

Read more about the synchronization of participant data with an event in RACEMAP:

{% content-ref url="/pages/-M3ehZR5FRb3OtNJtvds" %}
[Import participant data](/api-import-and-export-data)
{% endcontent-ref %}

Learn more about keys to upload recorded activities from fitness trackers such as Garmin and Polar:

{% content-ref url="/pages/-M4xF32x9PizOpA8KNfE" %}
[Activity upload](/live-tracking/activity-upload)
{% endcontent-ref %}

## Connect RACEMAP App for live tracking <a href="#connect-smartphone" id="connect-smartphone"></a>

Participants require a key to connect RACEMAP App for live tracking in one specific event. There are three options for participants to redeem their key in the app:

* Scan QR code.
* Click the key link.
* Manually paste the key in the search field of RACEMAP App.

#### Link to **redeem a key in RACEMAP App**

`https://racemap.app/redeem_key?key=[key]`

The key link provides a seamless user flow to connect the participants' phones for live tracking. The convenient user experience scales with a huge number of participants and saves support time. The process dynamically guides participants independent from

* The user's phone is iOS or Android.
* RACEMAP App is installed or not installed.
* The participant opens the key link on the smartphone or on the desktop.

![Key link landing page on desktop guides participants using their phones](/files/9RzFWxiSaP8CHVieeUOT)

{% tabs %}
{% tab title="RACEMAP App is not installed " %}
![](/files/iKicg8FKG2DL9vbROzpr)

The key link forwards to the App Store or to Google Play to install the tracking app.
{% endtab %}

{% tab title="RACEMAP App is installed" %}
![](/files/q5Q4yUDyhIcO6fLn7NRZ)

The key link

* Opens RACEMAP App.
* Addresses the corresponding event. Participants don't search for their race.
* Automatically redeems the key. Participants don't type the six characters of the key.
  {% endtab %}
  {% endtabs %}

![QR code on race kit to connect RACEMAP App for live tracking at ooredo marathon](/files/-LVgzaDiRVDIcs4O6WxP)

* Add specific `startNumber` and `name`. Participants don't need to type their name and bib number. `*/redeem_key?key=[key]&startNumber=[STARTNUMBER]&name=[NAME]`. Test this sample on your phone <https://racemap.app/redeem_key?key=6G615L&startNumber=1&name=Peter> .

#### **Redeem key manually**

Redeem a key respectively the passcode in the search field of RACEMAP App.

![](/files/DdNRkO7LwzDxTzfffRzX)

## Keys in predictive tracking events

Keys and transponder prediction work together in events that use [Predictive Tracking with reads from race timing](/prediction).

In that setup, participants are already tracked via their transponder — RACEMAP predicts their position on the race course from sporadic timing reads. Assigning a key to a transponder participant lets them optionally connect RACEMAP App for GPS-based tracking on top.

**Behavior while the key is unused:**\
The participant's position is shown from the prediction algorithm (transponder reads). The key badge in the participant list is green and the participant counts as visible.

**Behavior once the key is redeemed:**\
App GPS tracking takes over for that participant. Their position is now shown from live GPS instead of prediction. The participant remains visible — the key badge turns yellow (used).

{% hint style="info" %}
This makes keys optional in prediction events: participants who don't use the app are still shown via prediction; those who do use the app get GPS precision instead.
{% endhint %}


# Prepare smartphone

Prepare your smartphone befor live tracking with RACEMAP app.

Set location permission of RACEMAP app "allow all the time"

<figure><img src="/files/ZZbELdMOiG0yQ3StMP41" alt="" width="188"><figcaption></figcaption></figure>

* Test live tracking before your race, to get to know how tracking works well at the competition.
* Share the link of your tracking map in WhatsApp, Facebook. That way your family and friends keep track of your race easily.
* Stow smartphone: Fix your smartphone properly at the upper arm, in a tricot pocket or in the backpack lid pocket of your bag.

Use a powerbank for 15+ hours of live tracking with Racemap App. Tracking affects the battery life of your smartphone. Battery life depends on your device, the battery, your usage behavior and network coverage.

* Charge & restart your phone.
* Stop all apps you do not need.
* Use a powerbank for long events.


# Orga app

Easily manage all your GPS devices by scanning them. Select devices in Tracker Management and assign trackers to participants on-site. Visual identification makes handling fast and reliable.

{% tabs %}
{% tab title="Google Play" %} <a href="https://play.google.com/store/apps/details?id=com.racemap.orga.app&#x26;pcampaignid=web_share" class="button primary" data-icon="google-play">Google Play</a>

<div align="left"><figure><img src="/files/io8AWvvrMyCnGaCjxblf" alt="" width="375"><figcaption><p>Get free Orga App in Google Play</p></figcaption></figure></div>
{% endtab %}

{% tab title="App Store" %} <a href="https://apps.apple.com/us/app/racemap-orga/id1668767086" class="button primary" data-icon="app-store">App Store</a>

<div align="left"><figure><img src="/files/0ftPicd8MEiNJLi5SPHw" alt="" width="375"><figcaption><p>Get free Orga App in App Store</p></figcaption></figure></div>
{% endtab %}
{% endtabs %}

Orga App is designed for users operating large numbers of GPS trackers on RACEMAP. It speeds up device handling in both [Tracker Management](/tracker-management) and front desk operations by enabling quick device identification through QR code scanning.

{% hint style="info" %}

* To use the Orga App, you need to log in with your RACEMAP credentials.
* The devices need the unique RACEMAP QR code.
  {% endhint %}

### **Select devices in tracker management**

<figure><img src="/files/uZYRhKXKayeBbjUoIkOG" alt=""><figcaption></figcaption></figure>

With the Orga App, users can quickly identify and select GPS devices in [Tracker Management](/tracker-management). This eliminates the need to manually search through device lists, saving time and reducing errors when handling large inventories.

* Connect your Orga App with Tracker Management
* Scan devices to select them instantly
* Work in parallel: Multiple Orga Apps can operate simultaneously within the same Tracker Management

### **Assign devices to participants**

Pairing of GPS trackers to participants is streamlined through QR code scanning. Staff links a device to a participant directly at the help desk. This ensures fast and accurate assignment. Both scenarios are supported:

* Participant data is available in the event
* Participant data is not available in the event.

{% tabs %}
{% tab title="With participant data" %}
Participant information (name & bib number) is already available in the RACEMAP event (e.g., via [CSV upload](/api-import-and-export-data/import-data-from-csv), or [synchronization](/api-import-and-export-data/import-basics) with timing system or online registration).

<figure><img src="/files/3XypVNOhvoVQmkXR0DMZ" alt=""><figcaption></figcaption></figure>

* Type the participant's name or bib number that wants to pick up a device
* Select the correct participant shown in the Orga App
* Scan the QR code of the GPS Tracker
* Result: The device is linked with the participant
  {% endtab %}

{% tab title="Without participant data" %}
Participant information is not yet available in the RACEMAP event.

<figure><img src="/files/8v5cOnfWrd1guJHVpvLd" alt=""><figcaption></figcaption></figure>

* Create a participant
* Type bib number and name
* Scan the QR code of the GPS tracker
* Result: The device is linked with the participant
  {% endtab %}
  {% endtabs %}

**Advantages**

* Faster device handling through QR code scanning
* Reduced manual errors during assignment
* Clear workflow for users and staff
* No need to pre-assign devices before the event
* Assign only the devices that are actually used, reducing the total number of required trackers


# Predictive tracking with reads from race timing

Use sporadic detections from the timekeeping system to smoothly visualize a realistic race. Live extrapolation of location and speed for all participants, without GPS devices.

![Processing sporadic passings from the timekeeping into smoothly moving dots](https://static-cdn.racemap.com/custom/predictive-sequence.gif)

{% hint style="success" %} <a href="https://calendar.app.google/ZCAXvLr83BYhvM2k6" class="button primary">Schedule video call</a>

Would you like to get your event set up quickly? Just book a 20-min video call with our lead developer, Jens. He’ll walk you through everything to prepare your event for predictive tracking with RACEMAP.
{% endhint %}

Watch the recap of predictive live tracking at the Dresden Marathon with more than 12.000 participants: <https://racemap.com/player/ddm25>

![Predictive live tracking at München Marathon, decoder reads forwarded from RACE|RESULT](https://gblobscdn.gitbook.com/assets%2F-LSRNxaH2Ju9Flr7JhJD%2F-M0rll9AFXwscBSy-0F0%2F-M0rplagySzmaVYvxNQq%2Fc1571b9d-46dc-43a1-8258-faa441d37f9c.gif?alt=media\&token=5da620c0-11ce-44ba-94d6-116912f85739)

{% embed url="<https://youtu.be/p4aZmD56Cd0?si=M4ieoekYnIhO4ZtK>" %}
Webinar about predictive live tracking
{% endembed %}


# Prediction dashboard

The dashboard supports you during all phases of predictive tracking and provides insights into data processing.

* **Before the event:** Checklist to quickly prepare and test predictive live tracking.
* **During the race:** Relevant information for monitoring and adjusting the prediction.
* **After the race:** With the purpose of analyzing the prediction all data for each athlete is prepared and linked in a map, in diagrams, and in a table.

![Dashboard to monitor reads from the timing system in order to compose a live visualization of the race](/files/BlVTqxAsLLTWHuWciXiB)

**Status:** Checklist for settings required to conduct predictive tracking. The status tab also provides an auto-check of the forwarding settings in RACE RESULT.

**Readers:** When Racemap receives [detections](/glossary#read), the locations of corresponding readers are shown on a map. There is a hint for readers that are placed too far from the shadowtrack, and its reads are not considered for prediction (rejected reads). The track is also shown as an elevation profile with the corresponding readers' locations.

**Transponders:** Table showing various information of the last received read for each transponder: recorded- and received timestamp, location, reader id. Additionally, the start- and finish time is shown if imported to the participant data.

[**Reads**](/glossary#read)**:** Continuously running list of all received reads from your timing system.

**Analysis:** Select one participant and analyze all its aggregated information. Data is linked in a map, a table, and in diagrams.

**Parameters:** Set the parameters that impact predictive tracking.


# Test prediction before your event

Test predictive tracking well before your actual race through different options.

### Send reads

Send reads from your timing system to RACEMAP using either test data or a live setup, e.g. decoder and transponder in your office.

Check in the reads tab of the prediction dashboard: The smaller the difference between *READ AT* and *RECEIVED AT* timestamps, the better the data for live tracking.

* Positive difference: Delay in forwarding the reads from the timing system to RACEMAP. Minimize the delay for a good prediction.
* Negative differences - reads appearing to come from the future: This indicates an incorrect time / date setting at your hardware or in the timing system.

<figure><img src="/files/pV8JuetUNnzyFJzndFs8" alt=""><figcaption><p>Green - very good: Small difference, Red - not usable data: Huge difference</p></figcaption></figure>

### Prediction recap using recorded timing data <a href="#prediction-recap" id="prediction-recap"></a>

Create a past event in RACEMAP that you've already timed, then resend the recorded timing data from the timing system to RACEMAP. For testing and training, this approach is more effective and realistic than simulations with synthetic data. If you already have a specific event in mind where you want to offer predictive tracking, we recommend using recorded real race data from that event.

Workflow:

* Create an event in RACEMAP where the start and end times are in the past - trial, no activation required
* Import or synchronize the participant data of that past event
* Re-send the recorded timing data to RACEMAP

This allows you to visualize participants moving on the map in replay mode. At the same time, we can analyze and validate the prediction quality based on real race data. This approach requires less effort and delivers more meaningful results than testing with purely synthetic data. This ensures you are fully prepared and confident for your upcoming production event.


# Algorithm for predictive tracking

Processing of timing data for a smooth race visualization.

The prediction considers the timestamp when a read is recorded. The timestamp when RACEMAP receives the detection is not used for the forecast.

Check in the reads tab of the prediction dashboard: The smaller the difference between *READ AT* and *RECEIVED AT* timestamps, the better the data for live tracking.

* Positive difference: Delay in forwarding the reads from the timing system to RACEMAP. Minimize the delay for a good prediction.
* Negative differences - reads appearing to come from the future: This indicates an incorrect time / date setting at your hardware or in the timing system.

<figure><img src="/files/pV8JuetUNnzyFJzndFs8" alt=""><figcaption><p>Green - very good: Small difference, Red - not usable data: Huge difference</p></figcaption></figure>

For predictive live tracking RACEMAP needs to know:

* Transponder id of each participant you want to display
* Exact race course ("shadowtrack")
* Locations of the timing hardware
  * Readers with a GPS module eg. track boxes send their locations to Racemap
  * Readers without own locations: set the location of the reader in Racemap

The prediction works differently from a timing system. The prediction does not know a reader's location ahead, and potentially upcoming reads are not taken into account. Each detection is processed stand-alone. This approach enables flexibility when applying predictive tracking for sports events.

* **Auto-Mapping** to a location of the shadowtrack within 50 m distance:
  * A reader can be mapped to several locations of the same shadowtrack. If reader is placed in laps it is mapped on each lap automatically.
  * If reader is placed too far (> 50 m) from the shadowtrack its reads are not considered for prediction (rejected reads).
* **Moving reader**: Variable locations of readers during the race, e.g. place track boxes on cars or boats. The prediction considers the current location of every detection for live and replay.
* **Multiple contests detection**: One reader can detect several contests (shadowtracks), simultaneously. Racemap assigns reads to the correct shadowtrack, corresponding to transponder id and contest.
* **High performance:** prediction calculates location & speed for > 50,000 participants simultaneously, e.g. [München Marathon](https://racemap.com/player/muenchen-marathon-staffel-marathon-racemap_2019-10-13#follow=5da571f0fb1cf413081cb0c4\&selected=5da571f0fb1cf48a431cb10f,5da571f0fb1cf413081cb0c4)

{% hint style="info" %}
Strategically place readers along the race course.

* 1st & 2nd read approx 0.5 & 1 km behind the start.
* Place readers along the race course to detect each transponder every 20 min.
* Read 1 to 0.5 km before finish.
* Swimming events: place track boxes on buoys. eg. <https://racemap.com/player/wa-open-water-swimming-series-race-8_2019-01-25/>
* Transition area: t\_in, t\_out with decoders, track boxes too inaccurate.
  {% endhint %}

#### **Parameters to adjust the prediction**

Predictive live tracking involves the below parameters. Set these parameters carefully, as they impact the quality of your prediction.

**Max distance from shadow track** in meters: Maximum distance between the shadowtrack and the reader in which detections can be considered for the prediction. Readers with a greater distance from the shadowtrack are not considered for prediction and are shown as "Out of range". If the distance is 40 m the width of the whole corridor is 80 m.

**Jumping dot threshold** in seconds: With a new read, there is a new speed calculated for a predicted virtual participant (represented by the location of the dot in the tracking map). The "Jumping dot threshold" is the maximum time difference between the latest read and the virtual participant. If this difference is greater, the dot jumps to the location of the latest read. If this difference is smaller, the dot will either move faster or slower to smoothly reduce the difference during the ongoing event.

**RSSI threshold** in dBm; With Track Boxes the reads have a Received Signal Strength Indicator (RSSI). The RSSI threshold is the minimal value to be considered for prediction. Reads with a smaller RSSI are not considered for prediction. Small values indicate a significant distance between the Track Box and the transponder. Allowing small RSSI values increases possible errors as the transponder could be detected by multiple Track Boxes over a long distance at nearly the same time.

**Future track scale value:** The relative distance in which the predicted virtual participant "meets" the real participant moving along with the measured average speed. The greater the track scale value the longer takes the correction.

**Look back distance** in meters: The look back distance makes prediction less susceptible to measurement errors. With a new read, there is a new speed calculated for a predicted virtual participant. The prediction might receive many reads from a short section of the track. These reads can have location errors and therefore cause malicious velocities. The look back distance is the length for calculating an average speed for the prediction.

**Look forward time** in seconds: The look forward time compensates for the delay in data transmission and processing throughout our systems.

Speed filters to check the plausibility of reads: Set a range of expected speed values eg. swimming, transition, and cycling for triathlon to enable prediction ignoring unlikely reads.

* filter\_max: ignore reads with two times faster speed than expected speed
* filter\_min: ignore reads with 0.1 x speed than expected speed

#### **Different visualization of live and replay**

With every new input data, the prediction is recalculated automatically. Input data can be a detection, new speed filters for segments, adjustment of the shadowtrack, import of finish time.

|                       | Live                                                                                                                                                                                                                                                                                                         | Replay                           |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------- |
| Appearance of markers | With 2nd read, eg. prediction receives detection from start without delay and markers will show from 1st reader behind                                                                                                                                                                                       | From start detection             |
| Movement of markers   | <p>Speed extrapolation until detection from next reader's location;</p><p>speed correction depending on difference between marker in visualization from detection of real participant;</p><p>As readers (especially track box) might miss detections, marker moves on over location of following reader.</p> | Average speed between detections |


# Timing system

Use different timing systems for predictive live tracking.

{% content-ref url="/pages/-LXNtDr2IOra38JB8x9C" %}
[RACE RESULT](/prediction/timekeeping/raceresult)
{% endcontent-ref %}

{% content-ref url="/pages/-M0I\_OH4kZyU21S-cw7U" %}
[Other timing system](/prediction/timekeeping/other-timingsystem)
{% endcontent-ref %}


# RACE RESULT

Apply predictive tracking with detections from Track Boxes (active and passive), decoders, and loop boxes.

### Settings in RACE RESULT

Create your event with the required contests in your RACE RESULT account.

Synchronize participants with Racemap:

{% tabs %}
{% tab title="List import" %}
<https://docs.racemap.com/api-import-and-export-data/import-basics/metadata-api#race-result-lists>
{% endtab %}

{% tab title="simple API" %}
<https://docs.racemap.com/api-import-and-export-data/import-basics/metadata-import-via-rr>
{% endtab %}
{% endtabs %}

#### **Tracking channel**

Active transponders have to use the same tracking channel as TrackBoxes. Set up with management box, default configuration: channel 1 should be different from channel for timing.

#### **Track Box settings - Forwarding**

Set up your Track Boxes for live tracking to directly forward all the Track Pings to RACEMAP:\
Timing » Systems » Track Box Configuration Rules

![Track Box configuration](/files/-M-tzEF0tQr7X5QSBmWC)

* Channel ID: using Track Boxes for live tracking requires a different channel than for timing system
* Tracking Partner: Racemap

<figure><img src="/files/pcekW4BYSgjvYmQPqUTh" alt=""><figcaption></figcaption></figure>

![](/files/-M-tznuBILcqrYCFVq56)

#### **Loop box settings**

Loop box detections are forwarded with the device ID of the connected decoder. That means, Racemap has no information, if the detection is received from loop box or decoder.

* Repeat mode: Detections are forwarded directly and can be used for live visualization.
* Store mode: Detections are forwarded with delay and can not be used for live visualization, but for the replay of the contest.

Loop box detections are forwarded through the exporters with the coordinates of the

* decoder OR
* specific timing point

  Use the automatic timing point assignment rules for these detections (based on loop ID and channel ID), if loop and channel ID have been manually defined in Main Window » Timing Points

![Set coordinates for loop boxes, independent from location of connected decoder](/files/-M-u-cmzugvZPZmQw3e-)

#### Exporter to forward timing points

The exporters send reads addressed to specific timing points. Forwarding through exporters is the only way to consider decoders for predictive live tracking.

Go to **Timing » Settings » Exporters + Tracking**: For each timing point set "Racemap" in the destination field, enter your RACE RESULT customer ID.

<figure><img src="/files/T5SR9Zgg2lBMWTgUYOEc" alt=""><figcaption></figcaption></figure>

Go to **Timing » Chip Timing » Systems**: Click the green play button to start forwarding. Also, for each reader is a box ping sent every 4 min. That way your systems are shown in the [prediction dashboard](/prediction/dashboard). After the race your can use all recorded reads can be sent to RACEMAP through the play button.

<figure><img src="/files/P5rKDPqdI2Oh1iREvfH2" alt=""><figcaption></figcaption></figure>

{% embed url="<https://youtu.be/E_tcRhAbUuc>" %}
Webinar about predictive tracking with data from RACE|RESULT, thanks Ugo Durand (<https://timit.pro/>)
{% endembed %}

{% hint style="info" %}
Information related to live tracking in the RACE RESULT knowledge base:

* Track Box configuration for forwarding track pings:\
  <https://www.raceresult.com/en/support/kb?id=19552-Track-Box-Configuration>
* Setup exporters for forwarding timing points and splits for live tracking:\
  <https://www.raceresult.com/en/support/kb.php?id=8649-Tracking-Data-Forwarding>
* Timing point selection for loop boxes: <https://www.raceresult.com/en/support/kb.php?id=3940-Automatic-Timing-Point-Selection>
* Track Box protocol:\
  <https://www.raceresult.com/de-de/support/kb?id=4962-TrackPing-Call>
  {% endhint %}


# Other timing system

Predictive live tracking with reads from any timing system.

Your timing system provides the information of **UTC timestamps**, **chip IDs** (or transponder IDs), and ideally **GEO locations and** you can send this data to RACEMAP server.

When a participant passes a decoder, the timing system generates data including the **timestamp** and the **ID**. You can format this data as a **JSON array** (as shown below) and send it to our servers.

You can use any programming language that supports **HTTPS-based POST requests with JSON bodies**. To test the approach, follow the steps below or set up **permanent forwarding** within your timing system.

For this setup, a **programmer** or someone with **technical expertise** is recommended. However, if you need assistance, reach out to us — we support you build a **reliable, and easy-to-use solution**, similar to our solution with RACE RESULT.

Therr are two scenarios **RACEMAP** receives data from a timekeeping software.

1. Recommended: [Reads](/glossary#read) ([detections](/glossary#read)) include the reader's GEO location.
2. Reads without the GEO location. In that case, the [readers' locations must be set in RACEMAP](#set-readers-locations) map editor.

### HTTP Request

**URL** `https://racemap.com/services/trackping/api/v1/timing_input/pings`

**Method** `POST`

#### [Reads](/glossary#read) object

A read can have the following data fields. Some of them are required, some are optional.

<table data-full-width="false"><thead><tr><th width="169">Field</th><th width="311">Description</th><th width="294">Sample</th><th data-hidden></th></tr></thead><tbody><tr><td><code>timingId</code></td><td>Unique ID of the reader</td><td><code>"XF32098"</code> or <code>"_8nx7uoyun"</code></td><td></td></tr><tr><td><code>timingName</code> *</td><td>Name of reader in timing software</td><td><code>"5K-split"</code> or <code>"Start II"</code></td><td></td></tr><tr><td><code>chipId</code></td><td>Transponder ID</td><td><code>"RRPing_ZDKAR32"</code> or <code>"RRPing_70761"</code> or <code>"HH32098"</code></td><td></td></tr><tr><td><code>timestamp</code></td><td><a href="https://en.wikipedia.org/wiki/Coordinated_Universal_Time">Timestamp in UTC</a> when the reader detects the transponder</td><td><code>"2023-11-09T16:35:05.248Z"</code></td><td></td></tr><tr><td><code>lat</code> **</td><td>Latitude of the reader</td><td><code>51.5074</code></td><td></td></tr><tr><td><code>lng</code> **</td><td>Longitude of the reader</td><td><code>13.7276</code></td><td></td></tr></tbody></table>

(\*) Optional parameter without impact on processing the reads in RACEMAP.

(\*\*) If unavailable you have to set GEO locations for each reader in the [RACEMAP](https://racemap.com/admin/events) map editor

### Examples

The examples demonstrate the process of

* converting your timing data into **RACEMAP**-compatible reads,
* sending the data to our server, and
* testing access using the API token.

Once your timing data is successfully forwarded to RACEMAP, we can provide further support to help you build a reliable integration.

{% tabs %}
{% tab title="1. Using VS Code" %}
To test this example, use the [VS Code](https://code.visualstudio.com/) editor.

* Install VS Code on your computer.
* Install the [Rest Client Extension](vscode:extension/humao.rest-client).
* Save the below sample into a file with the name `test.rest` .
* Open the file in VS Code.
* Paste your **API token**.
* Send the HTTP request to our server.
* Check the **prediction section** of your event in RACEMAP for received reads.

In the 1st sample, the GEO locations of each reader are defined. The `timingId` identifies the reader and does not influence data processing in the RACEMAP backend. You can use these IDs to verify whether your data was correctly received by RACEMAP.

```json
POST https://racemap.com/services/trackping/api/v1/timing_input/pings
Content-Type: application/json
authorization: Bearer [Place your API token here]

[
  {
    "timingId": "XF32098",
    "timingName": "Start",
    "chipId": "HH32097",
    "timestamp": "2023-11-09T16:31:07.248Z",
    "lat": 51.5074,
    "lng": 13.7386
  },
  {
    "timingId": "XF32099",
    "timingName": "Start II",
    "chipId": "HH32098",
    "timestamp": "2023-11-09T16:31:05.248Z",
    "lat": 51.5074,
    "lng": 13.7386
  },
  {
    "timingId": "XF32100",
    "chipId": "HH32099",
    "timestamp": "2023-11-09T16:32:04.248Z",
    "lat": 51.5074,
    "lng": 13.7386
  }
]
```

In the 2nd sample, the GEO locations of the readers are not defined. You can manually set them in RACEMAP. For each `timingId`, you can define a GEO location in the map editor section of your event. Our prediction algorithm will then use these manually assigned locations.

However, this method is not recommended, as errors may occur if incorrect locations are defined.

<pre class="language-json"><code class="lang-json"><strong>POST https://racemap.com/services/trackping/api/v1/timing_input/pings
</strong>Content-Type: application/json
authorization: Bearer [Place your API token here]

[
  {
    "timingId": "XF32098",
    "timingName": "Start",
    "chipId": "HH32097",
    "timestamp": "2023-11-09T16:31:07.248Z"
  },
  {
    "timingId": "XF32099",
    "timingName": "Start II",
    "chipId": "HH32098",
    "timestamp": "2023-11-09T16:31:05.248Z",
  },
  {
    "timingId": "XF32100",
    "chipId": "HH32099",
    "timestamp": "2023-11-09T16:32:04.248Z",
  }
]
</code></pre>

{% endtab %}

{% tab title="2. Using Python" %}
Python Code for Sending Timing Data (with GEO locations)

Setup Instructions:

* Install [**VS Code** ](https://code.visualstudio.com/)on your computer.
* Install the [**Python extension**](vscode:extension/ms-python.python) in VS Code.
* Install the `requests` library if not already installed:
* Save the content below as `test.py`.
* Replace `YOUR_API_TOKEN` with your actual API token.
* Run the script in VS Code.
* On success `response.status_code` should be 200.
* Check the **prediction section** of your event in Racemap for received reads.

```python
import requests

# API Endpoint
url = "https://racemap.com/services/trackping/api/v1/timing_input/pings"

# API Token (Replace with your actual token)
api_token = "YOUR_API_TOKEN"

# Headers
headers = {
    "Content-Type": "application/json",
    "authorization": f"Bearer {api_token}"
}

# Timing data with GEO locations
data_with_geo = [
    {
        "timingId": "XF32098",
        "timingName": "Start",
        "chipId": "HH32097",
        "timestamp": "2023-11-09T16:31:07.248Z",
        "lat": 51.5074,
        "lng": 13.7386
    },
    {
        "timingId": "XF32099",
        "timingName": "Start II",
        "chipId": "HH32098",
        "timestamp": "2023-11-09T16:31:05.248Z",
        "lat": 51.5074,
        "lng": 13.7386
    },
    {
        "timingId": "XF32100",
        "chipId": "HH32099",
        "timestamp": "2023-11-09T16:32:04.248Z",
        "lat": 51.5074,
        "lng": 13.7386
    }
]

# Sending request
response = requests.post(url, json=data_with_geo, headers=headers)

# Output response
print(f"Status Code: {response.status_code}")
print(f"Response: {response.text}")

```

Python Code for Sending Timing Data (without GEO locations)

```python
import requests

# API Endpoint
url = "https://racemap.com/services/trackping/api/v1/timing_input/pings"

# API Token (Replace with your actual token)
api_token = "YOUR_API_TOKEN"

# Headers
headers = {
    "Content-Type": "application/json",
    "authorization": f"Bearer {api_token}"
}

# Timing data without GEO locations
data_with_geo = [
    {
        "timingId": "XF32098",
        "timingName": "Start",
        "chipId": "HH32097",
        "timestamp": "2023-11-09T16:31:07.248Z"
    },
    {
        "timingId": "XF32099",
        "timingName": "Start II",
        "chipId": "HH32098",
        "timestamp": "2023-11-09T16:31:05.248Z"
    },
    {
        "timingId": "XF32100",
        "chipId": "HH32099",
        "timestamp": "2023-11-09T16:32:04.248Z"
    }
]

# Sending request
response = requests.post(url, json=data_with_geo, headers=headers)

# Output response
print(f"Status Code: {response.status_code}")
print(f"Response: {response.text}")

```

{% endtab %}
{% endtabs %}

### **Response**

If everything is correct the HTTP code 200 is returned.

### **Set readers' locations**

Case 2, if reads are sent without coordinates:\
Virtually define the locations of your readers in the [map settings](/tab-map) of your tracking map.

* Upload the race track.
* Set this track as the [shadowtrack of the race](/live-tracking/shadowtrack#shadowtrack).
* Create a split representing the location of your reader at the race.
* Check "Timekeeping"
* Provide the unique `timingId` in the field "IDs of Timing Systems" of the split. You can add multiple `timingId` to a split, if you use multiple readers at the same location.

Note: If a single reader is used for multiple detections (e.g., timing a lap race at 5K and 10K), enter its location only once. There's no need to add the reader multiple times.

<figure><img src="/files/zUAT0yHimH2m8skSvoAc" alt=""><figcaption></figcaption></figure>

<figure><img src="/files/OoeXHFCT66KNpboyCmbY" alt=""><figcaption><p>Split "CP-1" with the unique split id U078</p></figcaption></figure>


# 2 RACEMAP forwarder

The forwarder is a program that runs locally to send reads from MyLaps and ChronoTrack timing systems to RACEMAP.

<figure><img src="/files/sROjDRSQDCp8Ti3KUeak" alt="" width="563"><figcaption><p>The forwarder UI shows the connected timing software and some stats.</p></figcaption></figure>

**The Forwarder: Simple Now, Powerful Tomorrow**\
The Forwarder features an intuitive, easy-to-use interface designed for seamless operation. And we’re just getting started — future updates will bring expanded functionality and support. RACEMAP is actively working to integrate more systems to ensure full compatibility with all major local timing solutions.

Want to see your system included in the Forwarder? We’d love to hear from you — reach out and let’s connect!

<figure><img src="/files/iXkiWOilvuPSx7HWcpWJ" alt=""><figcaption><p>Flow of information schema</p></figcaption></figure>

You can download the software for Windows and Linux from [github.com](https://github.com/racemap/2-racemap-forwarder)

### How does the forwarder work?

* Opens a port, on your local machine: **3000** for ChronoTrack
* Opens a second port, on your local machine: **3097** for MyLaps
* Listens on localhost IP: **127.0.0.1**
* Waits for TCP/IP connections from ChronoTrack Simple Client software
* Processes passings/reads send by the ChronoTrack Simple Client software
* Waits for TCP/IP connections from MyLaps Timing software
* Processes passings/reads send by the MyLaps Timing software
* Uses RACEMAP's **API token** to forward data to RACEMAP

### How to get an API token?

{% content-ref url="/pages/1bq15cJtzdnjBPSV9Bx7" %}
[Authentication](/api/authentication)
{% endcontent-ref %}

### **How to use the forwarder?**

1. Get the timing API token for your RACEMAP account, contact <info@racemap.com>.
2. Download the forwarder to the computer on which the ChronoTrack timing software is running.
3. Run the forwarder with the **RACEMAP\_API\_TOKEN** token as an environment variable.
4. Configure your ChronoTrack timing software to send data to the forwarder.
5. The forwarder will send your data to RACEMAP.

<pre class="language-sh"><code class="lang-sh"><strong>set RACEMAP_API_TOKEN=[APItoken]
</strong>.\chronotrack-to-racemap-forwarder.exe
</code></pre>

### How to operate the forwarder?

#### Basic

Download the latest binary for windows or for linux and run it with below commands.

{% tabs %}
{% tab title="Windows" %}
Download the forwarder here: [2-to-racemap-forwarder-win-x64-v1.1.0.exe](https://github.com/racemap/2-racemap-forwarder/releases/download/v1.1.0/2-racemap-forwarder-win-x64-v1.2.0.exe)

* Place it in a writable folder (your home folder)
* Start by double click
* Paste your API token into the corresponding input

<pre class="language-sh"><code class="lang-sh"><strong>set RACEMAP_API_TOKEN=[APItoken]
</strong>.\2-racemap-forwarder.exe
</code></pre>

<figure><img src="/files/HBUlk5Gbzyv2GDiCE9Ya" alt=""><figcaption></figcaption></figure>

* Start your MyLaps Timing or ChronoTrack Simple Client and configure a connection
* For ***MyLaps Timing*** use Port `3097` as destination
* For ***ChronoTrack SimpleClient*** use Port `3000` as destination.
  {% endtab %}

{% tab title="Linux" %}
Download the forwarder here: [2-racemap-forwarder-linux-x64-v1.1.0](https://github.com/racemap/2-racemap-forwarder/releases/download/v1.1.0/2-racemap-forwarder-linux-x64-v1.1.0)

In a shell use the following commands to configure and start the forwarder.

```sh
export RACEMAP_API_TOKEN=[APItoken]
./2-racemap-forwarder 
```

Replace `[APItoken]` with the unique API token of your RACEMAP account.
{% endtab %}
{% endtabs %}

**Expert**

Go to [github.com/2-racemap-forwarder](https://github.com/racemap/2-racemap-forwarder) and start developing.


# Integrations

Other systems processing RACEMAP data

Several third-party platforms and solutions have integrated RACEMAP data to enhance their own services. These integrations enable seamless data processing and extended functionality within their respective platforms.

If your platform is not listed and you have integrated RACEMAP data, feel free to reach out to us at <info@racemap.com>.


# Wiclax

Wiclax is a race scoring and timing software to manage events. Wiclax has integrated RACEMAP times API to import passings at virtual splits (geofences) and current API to display the live location.

More about Wiclax on the homepage: <https://www.wiclax.com/>.

This section provides a step-by-step guide to using RACEMAP GPS data in Wiclax.

### Integration of times API into Wiclax

{% content-ref url="/pages/-MZHS89A2\_1gjjvVpUfO" %}
[\*/times, reads and raw data](/api/times)
{% endcontent-ref %}

{% embed url="<https://files.gitbook.com/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LSRNxaH2Ju9Flr7JhJD%2Fuploads%2FAFGl6HwbvrJqjD5FOpw5%2FWhatsApp%20Video%202025-02-10%20um%2009.10.43_2ef914bb.mp4?alt=media&token=4b4ffee3-d6df-48b0-9024-8de87e850495>" %}
Only 30 seconds to set up, then the timing data is imported to Wiclax.
{% endembed %}

<figure><img src="/files/EuOCw44fStYsTv5e8Rp5" alt=""><figcaption><p>Same window to connect a TrackBox: Except the text "RaceResult online passings" on the right side</p></figcaption></figure>

Go to "Results - Classifications" Tab >> "Acquisitions" (same menu to connect a timing system)

<figure><img src="/files/vTaKrHXvNgdJb9akydRJ" alt=""><figcaption></figcaption></figure>

In the new window: Select "Online passings" >> "RACEMAP Cloud"

<figure><img src="/files/d5a5VgU5h0WS3Abd7nSV" alt=""><figcaption></figcaption></figure>

New line on the left side is created. RACEMAP cloud can be connected multiple times e.g. to call several eventIds or to mix a RACEMAP eventId, and others to connect timing points from RACE RESULT systems.

<figure><img src="/files/kAN620C4mluQSqM2inWC" alt=""><figcaption></figcaption></figure>

1. Insert the RACEMAP eventId(s).
2. Click "Rewind" button to initially call the API. Wiclax reads all splits from RACEMAP API. Wiclax shows this window:

<figure><img src="/files/z9XvLl7lV0Hweyj7JIvL" alt=""><figcaption><p>Close the with "Close"</p></figcaption></figure>

Wiclax reads the data in the API, including the names of the splits shown in "Source" column.

3. Match RACEMAP splits names with names of timing points into Wiclax. By default, Wiclax provides start and finish. Add all needed splits the same way as you do with any timing system.

<figure><img src="/files/gyLNcCduwL9r2zISttkV" alt=""><figcaption><p>The drop down menu when you can match splits name with Wiclax Timing point</p></figcaption></figure>

4. Select the "offset". As Wiclax works in local time and RACEMAP provides times in UTC format the time difference needs to be provided.
5. Click "play" button to launch the acquisition (by default every 60 seconds). The frequency can be changed in "Read frequency" field.

Options:

* Select "cross again timeout in seconds". For example, in a loop race this option ignores a new detection before XX seconds. If there is a large radius at a geofence you can set a time to ignore too close coordinates.
* Once you match a RACEMAP split to a Wiclax timing point, you can set it as "backup line". For example, if you have timing chip and GPS devices. In that case, timing provided by RACEMAP is used as a backup in case there is no time from the timing system.
* Select in the right part to import data only of the day, from XX to YY.

### Integration of current API into Wiclax

Click on the green button.

<figure><img src="/files/vYeW29QtMhDhwpUeo7Ki" alt=""><figcaption></figcaption></figure>

A new window opens.

<figure><img src="/files/qDjcqQnFDIefrEKNxxmC" alt=""><figcaption></figcaption></figure>

Select Map

<figure><img src="/files/RAhz8go8U7es04nrLXU1" alt=""><figcaption></figcaption></figure>

* Enable the checkbox "GPS Tracking > Event managed on a geo-tracking platform".
* Select RACEMAP in the drop-down.
* Paste the RACEMAP eventId in below field.

In the race column, there are the different races of the Wiclax file (eg 5K/10K/Marathon). It is possible to use one RACEMAP eventId several times for different Wiclax races.

Use the checkbox "Detailed data" to request ranks API to display the moving time by default. You only have the location of the athletes and their current speed.

Sample: <https://pyreneeschrono.fr/resultats/resultats-grand-8-des-pyrenees-by-oxygers-2023/>

There is no replay feature, the map always shows the live location.

If you zoom in, you will see the green dot = the athletes. In live, inside the label, you will have also their speed here. The webpage is auto refresh each 2 minutes. All other data (except the location of the green dots) are provided by Wiclax. So it's not the GPX from Racemap which is displayed here


# Map settings

Set-up geodata for your event eg. tracks, points of interest, transition zone AND parameters such as shadowtrack or splits to process geodata from participants.

{% hint style="info" %}
**Selecting and editing on the map:** Click a track, split or point of interest to select it. Hold **Shift** and click further elements to select several at once, then move or remove them together. Use the fit button (top-right) to zoom to all items, and the **?** button for a quick list of editing tips.
{% endhint %}

### Tracks

A track is a line of multiple points e.g. to show the race course or highlight a transition zone. You can add zero or multiple tracks for each event.

* upload or drag and drop (GPX, KML, GeoJson),
* draw a line with the drawing tool ("Add Track").

properties:

* shadowtrack,
* name and
* color respectively visibility.

{% embed url="<https://www.youtube.com/watch?v=7qj8oD1-ZwY>" %}

#### Shadowtrack

The shadowtrack is a specific track and one track only can be set as shadowtrack of your contest. The shadowtrack enables features and add-ons like elevation profile, statistics, leaderboard, predictive tracking etc. The shadowtrack represents the route on which participants move from start to finish. The length of the shadowtrack has to be the same length as the contest e.g. 42,195 km for a marathon.

* The shadowtrack for a triathlon includes swimming, cycling and running in one continuous line.
* If athletes have to run three laps, then the shadowtrack must include three laps.

properties:

* direction,
* type of sport,

### Points of Interest

Points of interest to highlight specific locations in the visualization e.g. water station, start and finish.

properties:

* location,
* name (or emoji),
* color and
* select a predefined icon.

{% embed url="<https://www.youtube.com/watch?v=HkT4TTWBCHo>" %}

### Elevation Profile

The elevation chart requires an active [shadowtrack](/live-tracking/shadowtrack), otherwise elevation profile is unavailable.

properties:

* visibility

{% embed url="<https://www.youtube.com/watch?v=_qtnJ4oPg64>" %}

### Splits

A split is a specific point of the shadowtrack. Split your shadowtrack into sections depending on

* leaderboard: the location of the virtual checkpoints and
* predictive tracking: the type of sport (default speed) AND the locations of your timing systems

{% embed url="<https://www.youtube.com/watch?v=vn10ENPVcmI>" %}

#### **Splits for leaderboard**

To add a split in the leaderboard you have to activate the "Timekeeping" checkbox.

{% content-ref url="/pages/-LYXfT2qbHHP6XDl9-g6" %}
[Leaderboard](/live-tracking/gps-timing)
{% endcontent-ref %}

#### Splits for predictive tracking​

To improve the prediction for events like triathlons you have to split the shadowtrack into sections for swimming, running, biking, transition area, ... . For every section you can set a type of sport with a default speed corresponding to last year results.

Set geolocation of local timing system:

* only if timing system doesn't forward its geolocation
* set split for each timing system with forwarded timekeeping ID., often the MAC-Address of the hardware.

{% content-ref url="/pages/-M3ehfiMPavdV-qchvwu" %}
[Predictive tracking with reads from race timing](/prediction)
{% endcontent-ref %}

### Hardware and Detections

Hardware and detections show the last forwarded detections (transponder ID and timestamp) of race|result timing hardware corresponding to your customer ID. Just add temporary customer IDs in case of rental hardware.

{% embed url="<https://www.youtube.com/watch?v=yhfv8qyZWU0>" %}

{% hint style="info" %}
Hardware and Detections for RACE|RESULT timing hardware, only. To use the "Show Hardware"-feature you have to provide your r|r customer ID in your Racemap user profile.
{% endhint %}

### Import/Export

Upload and download your tracks as GPX, KML or GeoJson file.

{% embed url="<https://www.youtube.com/watch?v=8guoPQhh4cc>" %}


# External map layer

To add an external WMS layer to the tracking map.

<figure><img src="/files/BJDt1WrPdZbv3brKZpsj" alt=""><figcaption><p>In Map settings >> External layer</p></figcaption></figure>

{% hint style="success" %}
sample map with swiss topo layer: <https://racemap.com/player/swiss-topo-sample>

URL to call external layer: <https://wms.geo.admin.ch/?SERVICE=WMS&REQUEST=GetMap&VERSION=1.3.0&LAYERS=ch.swisstopo.swissimage&STYLES=default&CRS=EPSG:3857&BBOX={bbox-epsg-3857}&WIDTH=256&HEIGHT=256&FORMAT=image/png>

more about swiss topo. <https://www.geo.admin.ch/en/geo-services/geo-services/portrayal-services-web-mapping/web-map-services-wms.html>
{% endhint %}

```
https://wms.geo.admin.ch/
     ?SERVICE=WMS
     &REQUEST=GetMap
     &VERSION=1.3.0
     &LAYERS=ch.swisstopo.swissimage
     &STYLES=default
     &CRS=EPSG:3857
     &BBOX={bbox-epsg-3857}
     &WIDTH=256
     &HEIGHT=256
     &FORMAT=image/png
```

|                            |                                     |
| -------------------------- | ----------------------------------- |
| SERVICE                    | WMS                                 |
| REQUEST                    | GetMap                              |
| VERSION                    | 1.3.0 or 1.1.0                      |
| STYLES                     | empty                               |
| CRS (1.3.0) or SRS (1.1.0) | EPSG:3857                           |
| BBOX                       | {bbox-epsg-3857} a variable         |
| WIDTH                      | 256; same as tile size respectively |
| HEIGHT                     | 256; same as tile size respectively |
| FORMAT                     | image/png or image/jpeg             |
| TRANSPARENT                | true                                |

LAYERS: different, available in GetCapabilities e.g. <https://wxs.ign.fr/`yourkey`/geoportail/r/wms?SERVICE=WMS\\&VERSION=1.3.0\\&REQUEST=GetCapabilities>

### Use GeoTIFF

{% file src="/files/YisBIpkK4t0DCYG36i5v" %}
Download the sample file GeoTiff
{% endfile %}

1. mapbox style editor\
   "Create a style" and "Start from scratch"

   <figure><img src="/files/yv2IQIG4pPXjLbGnkqKj" alt=""><figcaption></figcaption></figure>
2. Add a "Custom layer" and upload the GeoTIFF or KML file.

   <figure><img src="/files/rZdDn8tXi0bAbaeq8RYi" alt=""><figcaption></figcaption></figure>
3. mapbox creates the layer ID once the GeofTIFF is uploaded\
   `racemap.48p1az6b`<br>

   <figure><img src="/files/j4aE3nStUstyXSOqdJqR" alt=""><figcaption></figcaption></figure>
4. RACEMAP >> Map Settings >> External Layers\
   Add URL as external WMS: `https://api.mapbox.com/v4/racemap.48p1az6b/{z}/{x}/{y}.png?access_token={privateKeyMapbox}` and replace `{privateKeyMapbox}` with your mapbox key.

   <figure><img src="/files/phdpn4k5F9Pq207GlkKE" alt=""><figcaption></figcaption></figure>

The result shows the original TIFF file: <https://racemap.com/player/6a01a8d5bd1f6d9fc6f4f50d>

#### Remove the border in the GeoTIFF

1. Free download of [QGIS](https://qgis.org/)
2. Load GeoTIFF and create a new GeoPackage-layer

   <figure><img src="/files/rusLQX8XqUYlpgQO3Axu" alt=""><figcaption></figcaption></figure>
3. Select "Polygon"\
   ![](/files/Zb2PcpuPkwzgnsYkoEgY)
4. Define borders with the pencil and polygon tool - left click: add point, right click: finish polygon.

   <figure><img src="/files/GwvMVrcUdOhbwJYHiLmD" alt=""><figcaption></figcaption></figure>
5. Raster >> Extraction >> Clip Raster by Mask Layer: Data outside the polygon is removed.

<figure><img src="/files/Ba5BVy8H2K3Wzq1S6Xp4" alt=""><figcaption></figcaption></figure>

6. Select the GeoTIFF as the input file, the mask layer to use (previously created), enable "Create an output alpha band" and "Keep resolution of input raster".

   <figure><img src="/files/Ixm2UFP4pxbhGaM2aVuy" alt=""><figcaption></figcaption></figure>

   6\. QGIS generates a new GeoTIFF file, which you now use to create another mapbox layer.\
   ![](/files/D2lXFXupPHqNGwcKHUWc)

Sample: <https://racemap.com/player/external-layer-mask/>

{% hint style="info" %}
We needed to run "Fix Geometries" in QGIS before extraction processed successfully.
{% endhint %}


# Record a race course file

This guide explains how to use your GPS tracker to record a real-world track and upload it as a race course in RACEMAP

{% stepper %}
{% step %}
**Create a new single map**

<https://racemap.com/admin/events/new>\
The purpose of this event is track recording only.
{% endstep %}

{% step %}
**Add GPS devices to the new single ,aü**

Assign one or more GPS trackers that you want to use for recording the course.

<figure><img src="/files/4ZI9S5DjqxMe3yQKtEf3" alt=""><figcaption></figcaption></figure>
{% endstep %}

{% step %}
**Set the event time**

Configure the event start and end time to cover the full period when you plan to record the track.

<figure><img src="/files/IAnI5rY6dy0x1rnA67eI" alt=""><figcaption></figcaption></figure>
{% endstep %}

{% step %}
**Prepare the devices**

* Switch on the GPS trackers assigned to the event.
* Ensure the devices are connected to the RACEMAP server, eg. online status in [Tracker Management](/tracker-management).
  {% endstep %}

{% step %}
**Start recording at the start line of the upcoming event**

When you are physically at the start of the race course:

* Switch on the trackers
* Wait approximately **5 minutes** to ensure stable GPS signal.
* Open the tracking map and check if you can see the dots on the map.
  {% endstep %}

{% step %}
**Record the full course**

Move along the race course **only in the correct race direction** (from start to finish).\
The GPS devices will continuously send their positions to RACEMAP.
{% endstep %}

{% step %}
**Stop recording**

When you reach the finish line, switch off the GPS devices.
{% endstep %}

{% step %}
**Download the recorded track**

* Go to **Participants.**
* Download the recorded GPS data as a GPX file.

<figure><img src="/files/zq6quRuwGL44RK1VamzV" alt=""><figcaption></figcaption></figure>
{% endstep %}

{% step %}
**Upload the course to your race event**

* Open the event where you want to display the race course
* Upload the downloaded file as the official course track.

<figure><img src="/files/gMAQFw0SJgobC7z7m9Uh" alt=""><figcaption></figcaption></figure>
{% endstep %}
{% endstepper %}


# Export data from RACEMAP

Geolocations, ranks, timestamps, and elevation - Racemap data to process in 3rd party applications

{% content-ref url="/pages/-M3SgSM07LR\_o1bxsZ3i" %}
[Hosted elevation service](/data-export-from-racemap/self-hosted-elevation-service)
{% endcontent-ref %}

{% content-ref url="/pages/-LhnxKNsCDy9NQ9cu5Kq" %}
[Download leaderboard CSV](/data-export-from-racemap/download-gps-results)
{% endcontent-ref %}

{% content-ref url="/pages/-LhnxYV7IMKd9SKsSHNn" %}
[Download recorded GPX](/data-export-from-racemap/download-gpx)
{% endcontent-ref %}


# Hosted elevation service

Use our open elevation data API with highest vertical precision of 1 m

![](/files/-M3SkIGuY6wxiLbnZO2V)

The [Google elevation API](https://developers.google.com/maps/documentation/elevation/start?hl=de) provides a vertical accuracy of 30 m and there is no other open elevation service providing more accurate data available. During the development of [Predictive Tracking](/prediction) we noticed, that this cartographic data is not precise enough and we developed a self-hosted elevation service (vertical accuracy of 1 m), you can use for your own projects under MIT license. You either host this service yourself or just use our API.

* Mapzen terrain data: <https://registry.opendata.aws/terrain-tiles/>
* GitHub documentation and source code: <https://github.com/racemap/elevation-service#api-usage>
* hosted elevation service: <http://elevation.racemap.com/?lat=51.3&lng=12.5>

#### Working with the elevation data API

You can download portions of the data. The data is organized by latitude/longitude where each chunk is 1x1 degree. Eg. for downloading the UK data you need to know the lat/lng extent of the UK and download all the necessary files. Example:

```
aws s3 cp --no-sign-request s3://elevation-tiles-prod/skadi/N51/N51E000.hgt.gz /path/to/data/folder/N51
```

Make sure to reproduce the file structure when downloading, e.g. `./N51/N51E001.hgt.gz`. The whole dataset is just \~200GB, so maybe it is even feasible to download the whole thing.

Regarding the licensing, please check for yourself: <https://registry.opendata.aws/terrain-tiles/> & <https://www.mapzen.com/terms/>


# Hosted loads information

The loads API allows to retrieve hourly load data for specific endpoints over a set time period. By leveraging this API, you can automatically monitor load consumption.

## Request

**URL** `https://racemap.com/api/events/:eventId/pageviews?startTime=yyyy-mm-ddThh:mm:ss.SSSZ&endTime=yyyy-mm-ddThh:mm:ss.SSSZ`\
**Method** GET\
**Sample** <https://racemap.com/api/events/66bf4318d1c783279d183dd3/pageviews?startTime=2022-09-19T14:00:19.000Z&endTime=2024-09-23T23:59:59.999Z>

#### Query parameters

Set the event's start- and end times in UTC to specify the time frame for which you want to retrieve the load data.

{% hint style="info" %}

* String for API <mark style="background-color:red;">**?**</mark>**startTime=2024-09-11T06:00:00.000Z\&endTime=2024-09-11T09:00:00.000Z**
* Sample: <https://racemap.com/api/events/66e1410315ad59b9f52f1923/pageviews?startTime=2024-09-11T06:00:00.000Z&endTime=2024-09-11T09:00:00.000Z>
  {% endhint %}

## Response

<table><thead><tr><th width="139">Field</th><th>Description</th><th>Sample</th></tr></thead><tbody><tr><td><code>eventId</code></td><td>Unique id of event in RACEMAP, can be regular, group or stage event</td><td><code>"66bf4318d1c783279d183dd3"</code></td></tr><tr><td><code>time</code></td><td>Time in UTC</td><td><code>"2024-08-16T14:00:00.000Z"</code></td></tr><tr><td><code>type</code></td><td>Type of the endpoint</td><td><code>"MAP"</code> or <code>"TIMES_API"</code> or <code>"CURRENT_API"</code></td></tr><tr><td><code>count</code></td><td>Hourly number of loads</td><td><code>1</code> or <code>547</code></td></tr><tr><td><code>id</code></td><td>The unique id of the loads</td><td><code>"66bf5ccec31b3891a31c08e4"</code></td></tr></tbody></table>

### Sample response

```json
[
  {
    "eventId": "66e1410315ad59b9f52f192",
    "time": "2024-09-11T07:00:00.000Z",
    "type": "MAP",
    "count": 24,
    "id": "66e1444cc31b3891a31edd89"
  },
  {
    "eventId": "66e1410315ad59b9f52f192",
    "time": "2024-09-11T07:00:00.000Z",
    "type": "TIMES_API",
    "count": 1,
    "id": "66e147efc31b3891a3224d58"
  },
  {
    "eventId": "66e1410315ad59b9f52f192",
    "time": "2024-09-11T07:00:00.000Z",
    "type": "CURRENT_API",
    "count": 360,
    "id": "66e14937c31b3891a3237513"
  }
]
```


# Download leaderboard CSV

Safe results and rankings in a CSV file

You can download the leaderboard as a CSV file. The file provides the data

* as time difference within start and corresponding split, format: `hh:mm:ss`
* as raw data, timestamps, UTC format: `1970-01-01T05:50:30.000Z`

All options and settings for the leaderboard:

{% content-ref url="/pages/-LYXfT2qbHHP6XDl9-g6" %}
[Leaderboard](/live-tracking/gps-timing)
{% endcontent-ref %}

Instead of a local CSV file, you can pull the \*/ranks feed to automatically process the data in the leaderboard:

{% content-ref url="/pages/-MZHQpwp749Eg0tOuYuX" %}
[\*/ranks, ranking and results](/api/ranks)
{% endcontent-ref %}


# Download recorded GPX

Download and safe the recorded track from a specific participant as GPX file.

Download the activity data of specific athletes as a GPX file in the participant table through the cloud icon <img src="/files/jqDqNEzQCBQ17Lu6uZ0F" alt="" data-size="line">. The GPX file provides location data within the event start- and end times.

<figure><img src="/files/1pZd8000hBQrYZRhLE8C" alt=""><figcaption><p>Download recorded geo data as a GPX file for each participant</p></figcaption></figure>


# Billing cycles

How RACEMAP billing cycles work: a cycle is 7 whole days counted in UTC — not your local time. Understand why an event can occasionally cross into a second cycle, and how to avoid it.

Live tracking is billed per **event cycle**. This page explains exactly how a cycle is measured so you can predict your costs — and understand why, occasionally, one event is billed as two cycles.

For current prices and plans, see the [RACEMAP pricing page](https://go.racemap.com/pricing). This page explains the *timing* behind those prices.

### How a billing cycle works

A billing cycle is **7 days**, and it starts when your event first goes live. Once started, a cycle is billed **once** — no matter how many of those 7 days the event is actually active.

Two details decide how many cycles an event costs:

* **Days are counted in whole UTC calendar days.** Every day your event is active is recorded against a UTC calendar date (`YYYY-MM-DD` in UTC).
* **The cycle is anchored to the first UTC day your event is active.** It then covers that day plus the following 6 UTC days (7 dates in total). Any activity on an **8th** UTC date starts a **new** cycle.

### Why UTC — and not your local time

This is the part that surprises people. The day boundary that matters for billing is **00:00 UTC**, not midnight in your local timezone.

Because of the timezone offset, your local clock and the UTC date can disagree. For an organizer in a UTC+10 timezone, a race that starts at **09:00 local time** starts at **23:00 UTC the previous day**. So the very first UTC date of the event gets only \~1 hour of activity — but it still counts as a full UTC date of the cycle.

For short, single-day events this is invisible: the event simply spans one or two UTC dates, comfortably inside one 7-day cycle, and is billed once.

It only matters for **long events** that run close to the full 7 days.

<figure><img src="/files/9Ya3S4TYjCPFFYyXLHAp" alt="A timeline showing the same 6 day 13 hour event billed as one cycle when started at 00:00 UTC and two cycles when started at 23:00 UTC"><figcaption><p>The same event duration can cost one or two cycles, depending on its start time relative to 00:00 UTC.</p></figcaption></figure>

### Worked example: the same event, two outcomes

Consider a single event that is active for **6 days and 13 hours** — comfortably less than 7 days.

* **Starts at 00:00 UTC** → it ends midday on day N+6, touching **7 UTC dates** (day N through N+6). That fits in one cycle → **1 cycle billed.**
* **Starts at 23:00 UTC** → the first UTC date gets only \~1 hour of activity, and the event ends midday on day N+7, touching **8 UTC dates** (day N through N+7). The 8th date falls outside the first cycle → **2 cycles billed.**

The event is exactly the same length in both cases. The only difference is the start time relative to 00:00 UTC.

{% hint style="info" %}
**It is not about your local time, and not about the number of hours.** Cycles are counted in whole UTC calendar dates. A long event that begins shortly before 00:00 UTC "spends" a whole UTC date on a sliver of activity, which can push its tail into a second cycle.
{% endhint %}

### How to avoid an unexpected second cycle

* For multi-day events approaching 7 days, check the start time in **UTC**, not local time.
* Avoid starting an activation shortly **before 00:00 UTC** — that wastes almost a whole UTC date and brings the end of your 7-day window forward by a day.
* Remember the cycle is anchored to the **first** activation. A test or preview activation days before the event can start the clock early; keep it in mind for long events.
* To avoid accidental usage (and cost) after your event finishes, see [Auto-pausation](/api/auto-pausation).

### See also

* [RACEMAP pricing page](https://go.racemap.com/pricing) — current prices, plans and add-ons (the source of truth for amounts).
* [Auto-pausation](/api/auto-pausation) — how RACEMAP pauses the Data API after an event to prevent unexpected costs.


# Glossary

Common terms used across Racemap live tracking — with their synonyms. This list is intended to help users find documentation no matter which term they search for, and to guide AI-assisted documentation tooling toward the preferred vocabulary.

***

## Read

**Preferred term:** read\
**Synonyms:** detection, passing, ping, trackping, timestamp\
**Context:** prediction feature, timing integrations

A single data point recorded when a participant is observed by a timing reader or GPS device. In the prediction and timing context, **read** is the preferred term. The word **detection** is common in integrations with external timing systems (e.g. ChronoTrack, RACE RESULT). **Passing** appears in some timing-system UIs and older documentation. **Ping** and **Trackping** are RACE RESULT specific for Mobile Trackbox detections.

***

## Auto-pausation

**Preferred term:** auto-pausation\
**Synonyms:** auto-deactivation, automatic shutdown, automatic pause

The automatic pausing of the Data Feed API module that occurs on the first API request arriving more than 2 hours after an event's end time. Auto-pausation prevents unexpected billing costs when a feed is left active after the event finishes. Repeating (live loop) events are excluded. See [Auto-pausation](/api/auto-pausation).

***

## Billing cycle

**Preferred term:** billing cycle\
**Synonyms:** event cycle, billing period\
**Context:** billing

A 7-day period that live tracking is billed against. A cycle is counted in **whole UTC calendar days** and is anchored to the first UTC day the event is active; it covers that day plus the following 6 UTC dates and is billed once. Because days are counted in UTC — not local time — a long event that starts shortly before 00:00 UTC can touch an 8th UTC date and roll into a second cycle. See [Billing cycles](/billing) and the related [Auto-pausation](#auto-pausation).

***

## Timekeeping Point

**Preferred term:** timekeeping point\
**Synonyms:** split, checkpoint, geofence, virtual checkpoint, timing point, reader location

A virtual location defined on the course at which reads are recorded for timing or ranking purposes. The API field name is `timekeepings` (plural). In the UI and documentation the terms *split*, *checkpoint*, and *geofence* appear interchangeably — all refer to the same concept.

***

## Timing Reader

**Preferred term:** reader\
**Synonyms:** decoder, timing system, Track Box, antenna

Hardware or software positioned at a timekeeping point that records reads as participants pass. Different vendors use different names: RACE RESULT uses *decoder*, Racemap's own hardware is the *Track Box*, and the general abstraction in the API and documentation is *reader*.

***

## Data Feed

**Preferred term:** Data Feed\
**Synonyms:** Data API, live API, datafeed, data feed module

The real-time HTTP API that serves current event data — participant locations, ranks, times — to external consumers such as TV graphics, custom dashboards, or result systems. Enabled per event via the Data API settings. See [Data API overview](/api).