> For the complete documentation index, see [llms.txt](https://docs.racemap.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.racemap.com/api/current.md).

# \*/current, location data

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

Real-time locations, speeds and gaps of all participants of an event.

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

{% hint style="info" %}

* You can call the endpoint with different query parameters at the same time.
* Combine query parameters with `&` in one call, e.g. <https://racemap.com/api/data/v1/66bf4318d1c783279d183dd3/current?avgSpeedWindow=600&participantId=66bf4318d1c783279d183e3d>
  {% endhint %}

### Reference

### Leader and reference participant

Gap values (`gapDistance`, `gap`, `gapChase`, `gapAverage` and their `Ex` variants) are calculated against the leader by default.

* **Leader:** the participant with the smallest `toFinish` value at `resultTime`.
* Each time a leader reaches the finish, the participant with the next smallest `toFinish` becomes the leader. At that moment the gap values can jump.
* **Reference:** pass `participantId` (or `refStarterId`, `starterId`, `deviceId`) or `startNumber` (or `refStartNumber`) to calculate against that participant instead. Pass only one of them. An unknown participant fails with HTTP 404.
* The participant the gaps refer to has `isRef: true`. The field is only present when it is `true`.
* A negative gap means the reference is behind the participant.

### Shadowtrack fields

Most fields of the `current` object need a [shadowtrack](https://docs.racemap.com/live-tracking/shadowtrack.md#shadowtrack) and a [mapping of the geolocation](https://docs.racemap.com/live-tracking/shadowtrack.md#what-is-mapping) on it.

* The default max mapping distance is 100 m. Change it in the Advanced Settings of the event.
* If a geolocation cannot be mapped, `fromStart`, `toFinish`, `eta`, the gap values and the `Ex` values are `null`.
* `lngSt`/`latSt` still show the nearest point on the shadowtrack, also beyond the max mapping distance.
* `elv` is the altitude of the shadowtrack at `lngSt`/`latSt`. It is `null` if the geolocation is 100 m or more away from the shadowtrack.
* The `Ex` values extrapolate the mapped position along the shadowtrack to `resultTime`, using `speedSt`.
* Durations (`eta` and the gap values) are whole seconds.
* If no geolocation of a participant is known, `time` equals `resultTime` and all other fields are `null`.

### Device object

The `device` object provides additional information for GPS trackers used in the [tracker management](https://docs.racemap.com/tracker-management.md). It is `null` for other devices.

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

{% hint style="info" %}
`charging` is reported by Queclink GL3xx, Concox M20 and Mictrack GPS trackers. Other devices always report `false`.

Most devices send a message only when charging starts or stops, so the value keeps the last state the device reported. It is therefore of good quality only while `online` is `true`. If `online` is `false`, read `charging` as the last known state, not the current one.
{% 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.

### Speed calculations

Speeds can vary significantly in dense datasets, mainly because of GPS position inaccuracies. To reduce these fluctuations, use the `avgSpeedWindow` parameter to smooth the speed curve.

* `avgSpeedWindow` is a duration in seconds. The default is 300, the minimum is 30. There is no maximum.
* The window reaches back from the latest known geolocation before `resultTime`. Its other end is interpolated between recorded geolocations.
* `speed` sums the straight lines between geolocations. `speedSt` uses the distance covered on the shadowtrack.

The figure below illustrates the effect of `avgSpeedWindow` on both dense and sparse datasets.

<figure><img src="https://1672210197-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LSRNxaH2Ju9Flr7JhJD%2Fuploads%2Fgit-blob-5d539a20ce8a7fcf09823a45cb34eaf43f6dce53%2Fcurrent-api-speed.excalidraw%20(1).svg?alt=media" 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 gap values `gap`, `gapChase` and `gapAverage` are durations in seconds. Read them as the time it takes to close the gap.

* `gap` and `gapEx`: calculated with `speedSt` of the reference (by default the leader).
* `gapChase` and `gapChaseEx`: calculated with `speedSt` of the chaser.
* `gapAverage` and `gapAverageEx`: the time the reference actually took from the chaser's position to its own.

`gap` and `gapChase` are based on local speed conditions at the participants' positions. `gapAverage` includes the effect of elevation and stops along the way. The diagram below shows a short stop of the leader at around 68.8 km.

<div align="center"><figure><img src="https://1672210197-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LSRNxaH2Ju9Flr7JhJD%2Fuploads%2Fgit-blob-22d2b91a202fdd5b30fdea7dda592179decb8384%2Fgap-chart-100km%20Duathlon%202026.svg?alt=media" 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`

### Replay over a time range

`*/current-replay` returns the `current` response of one participant at regular intervals, together with its reference participant. Use it to replay or analyse a race. A request covers at most 30 days and 10000 frames, and counts as one load.

### Deprecated alias

`/api/data/v1/:eventId` without `/current` returns the same response. Use `*/current` instead.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

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

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.racemap.com/api/current.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

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