# \*/current, location data

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

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

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

* The <kbd>participantId</kbd> of a chosen reference participant for calculation `gapAverage`, `gap`, `gapChase` and `gapDistance`.
* String for API <mark style="background-color:red;">**?**</mark>**participantId=66bf4318d1c783279d183e3d**
* Sample <https://racemap.com/api/data/v1/66bf4318d1c783279d183dd3/current?participantId=66bf4318d1c783279d183e3d>
  {% endtab %}

{% tab title="startNumber" %}

* The `startNumber` of a chosen reference device for calculation `gapAverage`, `gap`, `gapChase` and `gapDistance`.
* 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="interpolation" %}

* `true` or `false`
* Default: true&#x20;
* Combine `interpolation` and `liveDelay` to smooth movement between consecutive coordinates.
* Sample [https://racemap.com/api/data/v1/66bf4318d1c783279d183dd3/current<mark style="background-color:red;">**?**</mark>**interpolation=false**](https://racemap.com/api/data/v1/66bf4318d1c783279d183dd3/current?interpolation=false)
  {% endtab %}

{% tab title="currentSpeedDuration" %}

* Duration in seconds used to derive speed values in the API. If `currentSpeedDuration` 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>**currentSpeedDuration=120**
* Sample [https://racemap.com/api/data/v1/66bf4318d1c783279d183dd3/current<mark style="background-color:red;">**?**</mark>**currentSpeedDuration=120**](https://racemap.com/api/data/v1/66bf4318d1c783279d183dd3/current?currentSpeedDuration=120)
  {% endtab %}

{% tab title="liveDelay" %}

* Duration in seconds from the timestamp recording a location until this location is provided in the API.&#x20;
* According to "Live delay time" in advanced settings of the tracking map. \
  The set `liveDelay` query parameter processes the values in the API without impact on the visualization.&#x20;
* Default value: 20 seconds
* Maximum value: 1800 seconds
* String for API <mark style="background-color:red;">**?**</mark>**liveDelay=200**
* Sample [https://racemap.com/api/data/v1/66bf4318d1c783279d183dd3/current<mark style="background-color:red;">**?**</mark>**liveDelay=200**](https://racemap.com/api/data/v1/66bf4318d1c783279d183dd3/current?liveDelay=200)
  {% 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/66bf4318d1c783279d183dd3/current?liveDelay=600&interpolation=false&currentSpeedDuration=600&participantId=66bf4318d1c783279d183e3d>

### Response

#### Event object

<table><thead><tr><th width="190">Field</th><th width="290">Description [unit]</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>starters</code></td><td>Array for participant objects </td><td></td><td></td><td></td></tr><tr><td><code>shadowTrackUrl</code></td><td>Link to download the shadow track as geo json </td><td></td><td></td><td></td></tr></tbody></table>

#### Participant object

<table><thead><tr><th width="189.71594043022614">Field</th><th width="301.0163895119767">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 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="../api-import-and-export-data/import-basics/metadata-api">Generic API</a> (<code>importId</code>) or <a href="../api-import-and-export-data/import-basics/metadata-import-via-rr">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</td><td><code>null</code> if no locations within <code>startTime</code> and <code>endTime</code></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&#x20;
* (\*) calculated only for events with a shadowtrack, projection of device locations on the shadowtrack within 100 m distance from shadowtrack&#x20;
* `gapAverage`, `gap`, `gapChase` and `gapDistance` are calculated for the leader by default. \
  **Leader:** device with the smallest `toFinish` value. \
  **Attention:** Each time a leader reaches the finish the device closest to the finish becomes the new leader. The speed value of the next leader may impact fluctuating gap values.\
  **Reference:** If query with `deviceId` or `startNumber`, then calculation with reference values instead of leader.

<table data-full-width="false"><thead><tr><th>Field</th><th>Description [unit]</th><th>Sample</th><th data-hidden>line</th><th data-hidden></th></tr></thead><tbody><tr><td><code>time</code></td><td>Timestamp in UTC when geolocation was recorded, if <code>interpolation=true</code> then linear interpolation between the latest two points</td><td><code>"2022-01-24T16:33:47.012Z"</code></td><td>14</td><td></td></tr><tr><td><code>lng</code></td><td>Current longitude of participant</td><td><code>13.727678288</code></td><td>15</td><td></td></tr><tr><td><code>lat</code></td><td>Latitude</td><td><code>50.976534023</code></td><td>16</td><td></td></tr><tr><td><code>elv</code></td><td>Altitude above zero on shadowtrack [m]</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>speed</code></td><td><p>Average speed [m/s] depending on <code>currentSpeedDuration</code>. </p><p>If event has a shadowtrack, than projection on shadowtrack. </p><p>If event without shadowtrack, than same value as <code>speedRaw</code>. </p></td><td><code>5.2727</code></td><td>21</td><td></td></tr><tr><td><code>speedRaw</code></td><td>Average speed [m/s] depending on <code>currentSpeedDuration.</code> Calculated from two interpolated raw coordinates. <br><br>Note: Curves are cut off between the two coordinates </td><td><code>4.9574</code></td><td></td><td></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><td>18</td><td></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><td>19</td><td></td></tr><tr><td><code>distanceToShadowTrack</code> *</td><td>Shortest Distance to shadowtrack [m] from <code>lat/lng</code></td><td><code>175.9</code></td><td>22</td><td></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><td>20</td><td></td></tr><tr><td><code>gapAverage</code> *</td><td>Duration [s] to reach current <code>toFinish</code> value of the leader, <mark style="background-color:blue;">prediction with leader's average speed for current segment between device and leader</mark>. <br></td><td><code>2360.36</code> or <code>null</code> if reference is behind device, <code>toFinish</code> of reference is greater than <code>toFinish</code> of device</td><td></td><td></td></tr><tr><td><code>gap</code> *</td><td>Duration [s] to reach current <code>toFinish</code> value of the leader, <mark style="background-color:blue;">prediction with <code>speed</code> value of leader</mark>,  if <code>speed &#x3C; 1 km/h</code> then prediction with default speed value of the event, </td><td><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 reach current <code>toFinish</code> value of the leader, <mark style="background-color:blue;">prediction with <code>speed</code> value of device</mark>,  if <code>speed &#x3C; 1 km/h</code> then prediction with default speed value of the event</td><td><code>968.81</code> or <code>-73.02</code> if reference is behind device</td><td></td><td></td></tr><tr><td><code>gapDistance</code> *</td><td>Distance [m] to reach current <code>toFinish</code> value of the leader.</td><td><code>3364.91</code> or <code>-554.03</code> if reference is behind device</td><td></td><td></td></tr><tr><td><code>lngSt</code> *</td><td>Current longitude of participant pinned on the shadowtrack</td><td><code>13.805551232</code></td><td></td><td></td></tr><tr><td><code>latSt</code> *</td><td>Latitude</td><td><code>50.93151590</code>1</td><td></td><td></td></tr></tbody></table>

#### Device object

The device object provides additional information for those GPS trackers, that are used in the [tracker management](https://docs.racemap.com/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>

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

* Device may have lost its GPS fix and is unable to record coordinates.&#x20;
* Could suggest potential tampering or manipulation, also.

If `online` is `false`:&#x20;

* Device may have lost its network connection.&#x20;
* Device may have been turned off, also.

#### Sample response// Some code

{% code expandable="true" %}

```javascript
{
  "name": "Sample live API | 100km-Duathlon",
  "location": "🇩🇪 Dresden",
  "startTime": "2024-08-16T12:05:07Z",
  "endTime": "2024-08-16T16:04:31Z",
  "starters": [
    {
      "id": "66bf4318d1c783279d183e3b",
      "name": "Wolfsrudel Mädels",
      "startNumber": "053",
      "importId": null,
      "current": {
        "time": "2024-08-16T12:34:00Z",
        "lng": 13.73032,
        "lat": 51.00622,
        "elv": 218,
        "speed": 2.94017094017094,
        "speedRaw": 1.6961880220903458,
        "fromStart": 5340,
        "toFinish": 93720,
        "distanceToShadowTrack": 4.759105903942731,
        "eta": 31875.697,
        "gapAverage": 900,
        "gap": 359.005,
        "gapChase": 387.732,
        "gapDistance": 1140,
        "lngSt": 13.805551232735626,
        "latSt": 50.93151590177507
      },
      "device": {
        "externalId": "ecbbaaa4-c968-46db-9b07-afc842387e27",
        "battery": 40,
        "online": false,
        "lastLocationGpsFix": true,
        "lastLocationAt": "2024-01-05T13:45:24Z"
        "deviceId": "5b6ac1561c6a700020a00135"
      }
    },
    {
      "id": "66bf4318d1c783279d183e1d",
      "name": "Lokomotive Prießnitzgrund",
      "startNumber": "034",
      "importId": null,
      "current": {
        "time": "2024-08-16T12:34:00Z",
        "lng": 13.70232,
        "lat": 51.02038,
        "elv": 204,
        "speed": 1.435897435897436,
        "speedRaw": 1.1986131178696222,
        "fromStart": 890,
        "toFinish": 98170,
        "distanceToShadowTrack": 6.054100654596742,
        "eta": 68368.392,
        "gapAverage": 2280,
        "gap": 1760.386,
        "gapChase": 3893.035,
        "gapDistance": 5590,
        "lngSt": 13.822277523839235,
        "latSt": 50.932650793111506
      },
      "device": null
    },
    {
      "id": "66bf4318d1c783279d183e51",
      "name": "Dude, where's the finish line?",
      "startNumber": "039",
      "importId": null,
      "current": {
        "time": "2024-08-16T12:27:11.254Z",
        "lng": 13.70364238,
        "lat": 51.02187489866667,
        "elv": 200,
        "speed": 2.1403508771929824,
        "speedRaw": 1.8131895855527116,
        "fromStart": 665.016,
        "toFinish": 98394.984,
        "distanceToShadowTrack": 11.873080816329555,
        "eta": 45971.426,
        "gapAverage": 1338,
        "gap": 1650.853,
        "gapChase": 1999.667,
        "gapDistance": 4279.989333333331,
        "lngSt": 13.818931968149625,
        "latSt": 50.93166731504501
      },
      "device": {
        "externalId": "999994106050526",
        "battery": 40,
        "online": false,
        "lastLocationGpsFix": true,
        "lastLocationAt": "2023-07-02T12:37:51Z",
        "deviceId": "5b3a7b3ebd61c4491dcfcef4"
      }
    }
  ]
}
```

{% endcode %}

### Smoothen values in the API

The below parameters and settings smoothen the values in the API.

* Call the `gapAverage` value instead of `gap` value
* Interpolation=true
* Query parameter `currentSpeedDuration`

Use `gapAverage` instead of `gap` if you need smoothly changing gap values e.g. for TV production.&#x20;

<figure><img src="https://1672210197-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LSRNxaH2Ju9Flr7JhJD%2Fuploads%2FovGIbNXakHVP5UA6ckc9%2FScreenshot%202022-11-21%20154732.png?alt=media&#x26;token=23b48103-0ce1-4807-8998-b5475a1ac598" alt=""><figcaption><p>the average speed of the reference device smoothens the <code>gapAverage</code> values in the API</p></figcaption></figure>

<table><thead><tr><th width="193.79816989739356">Comparison</th><th width="231.33009268322203">interpolation=true</th><th>interpolation=false</th></tr></thead><tbody><tr><td>Use case</td><td>Values changing smoothly with each call</td><td>Latest values with a minimum delay</td></tr><tr><td>Calculation</td><td>Linear interpolation between the latest coordinate and coordinate before</td><td>Latest coordinate without interpolation</td></tr><tr><td>Refresh rate</td><td>Up to 1 sec</td><td>Report interval of GPS device</td></tr><tr><td>Recommended <code>liveDelay</code></td><td>5 sec + report interval of GPS device</td><td>5 sec minimum</td></tr></tbody></table>

Increase the `currentSpeedDuration` query parameter to smooth the `speed` values in the API.

### Subsequent calculations&#x20;

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

**Identify the leader**: the smallest value of `toFinish`