Race live insights

#Race live insights

A feed of short, human-readable commentary lines for a live race — lead changes, mark roundings, places gained, finishes and wind shifts from the last 15 minutes, newest first. Each line is phrased by the server (by a language model when quota allows, otherwise a template) in the language you ask for; the machine-readable half of each line is kind plus its numeric fields, for building your own sentence instead of using text.

#Headers

#Path parameters

#Query parameters

#Request

curl -s "https://sail-club-server.cloud.run/api/v1/races/9a1c0d2b-7e4a-46f8-9c1d-2e3f9a1c0d2b/live/insights?lang=tr" \
  -H "Authorization: Bearer $TOKEN"

const url = new URL(`https://sail-club-server.cloud.run/api/v1/races/${raceId}/live/insights`);
url.searchParams.set('lang', 'tr');
const res = await fetch(url, { headers: { Authorization: `Bearer ${token}` } });
const insights = await res.json();

res = requests.get(
    f"https://sail-club-server.cloud.run/api/v1/races/{race_id}/live/insights",
    params={"lang": "tr"},
    headers={"Authorization": f"Bearer {token}"},
    timeout=10,
)
insights = res.json()

var res = await client.GetAsync($"/api/v1/races/{raceId}/live/insights?lang=tr");
res.EnsureSuccessStatusCode();
var insights = await res.Content.ReadFromJsonAsync<PublicApiRaceInsightsDto>();

<?php
$ch = curl_init("https://sail-club-server.cloud.run/api/v1/races/$raceId/live/insights?lang=tr");
curl_setopt_array($ch, [CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => ["Authorization: Bearer $token"]]);
$insights = json_decode(curl_exec($ch), true);

#Response

{
  "raceId": "9a1c0d2b-7e4a-46f8-9c1d-2e3f9a1c0d2b",
  "eventId": "1143117a-9c2b-4e7a-8f1d-2b6a9c4e7f10",
  "isLive": true,
  "lang": "tr",
  "delaySeconds": 30,
  "dataAsOf": "2027-05-01T11:59:30.000Z",
  "generatedAtUtc": "2027-05-01T12:00:00.000Z",
  "insights": [
    {
      "id": "3f9c1a0b2d4e5f60",
      "kind": "leadChange",
      "startGroupId": "2b6a9c4e-7f10-4a1c-8d2b-7e4a6f8c1d2e",
      "startGroupName": "Start A",
      "atUtc": "2027-05-01T11:58:10Z",
      "text": "TUR 2 Poyraz, liderliği TUR 1 Poyraz teknesinden aldı (Start A).",
      "source": "template",
      "boats": [
        { "entryId": "e3f9a1c0-d2b7-4e4a-96f8-c1d2e3f9a1c0", "sailNumber": "TUR 2", "boatName": "Poyraz" },
        { "entryId": "a1c0d2b7-e4a9-46f8-9c1d-2e3f9a1c0d2b", "sailNumber": "TUR 1", "boatName": "Poyraz" }
      ],
      "markLabel": null, "rank": null, "placesGained": null,
      "twdFrom": null, "twdTo": null, "twsFrom": null, "twsTo": null
    }
  ]
}

200 — a shared cache per race, max-age up to 60 seconds (see Caching).

#Response fields

#Kinds

The detection window is the 5 minutes before dataAsOf, per start group.

#text is pre-rendered — don't re-translate it

text is written by the server in the lang you asked for; it's meant for a third-party broadcaster or overlay with no string catalogue of its own. If you're building your own sentences instead (your own templates, your own locale list), ignore text and compose from kind + the numeric/boat fields above — don't feed text back through your own translation layer.

#Errors

lang itself never produces a 400 — an unrecognised value just falls back to en.

#Caching

The server detects facts for a race at most once every 60 seconds (shared by every client and every language asked for in the last 10 minutes), and independently phrases each language's lines at most once every 60 seconds — insights are cached per race and language (60 s each), so a language asked for the first time gets model lines in the same window the facts were detected in, not the next one; quota is also counted per language. Poll every 15–60 seconds with If-None-Match rather than on every map redraw. This endpoint shares the same 120 requests/minute per client bucket as the other four tracking:read endpoints — see Rate limits.

Implement getRaceInsights(raceId, lang?) for the Sail Club API.

GET https://sail-club-server.cloud.run/api/v1/races/{raceId}/live/insights?lang=
Authorization: Bearer <access_token>
Scope required: tracking:read

Success 200: { raceId, eventId, isLive, lang, delaySeconds, dataAsOf, generatedAtUtc,
  insights: [ { id, kind, startGroupId, startGroupName, atUtc, text, source, boats: [ { entryId, sailNumber,
  boatName } ], markLabel, rank, placesGained, twdFrom, twdTo, twsFrom, twsTo } ] } — fetch
  GET /api/v1/openapi.json for the exact schema.
404 RACE_NOT_FOUND: unknown/malformed/another club's race id — not retryable.
404 TRACKING_NOT_SHARED: sharing is off for this event — not retryable, needs an organiser change.
401/403/429/503: same handling as every other call — see the full-integration prompt on /docs/overview.

kind is one of leadChange | markRounding | gain | finish | windShift — build your own sentence from kind plus
the numeric/boat fields if you don't want the server's pre-rendered text. Each id is stable: show it once, and
only redraw a line if its text actually changed on a later poll. Poll no faster than every 15 seconds; the
server only regenerates once a minute per race.

Adapt to your actual stack — the endpoint, path param and response shape above are language-neutral.