Skip to main content
Developers

Live data API

Every event with its parent link on can be read as JSON while it races: the heat on the track, times and places as they land, standings and the whole schedule. Use it for stream graphics, a scoreboard in the hall, a club website, or anything else. It's read-only, free with the event, and needs no key.

Just want times on your stream?

You don't need the API for that. Apex Derby makes ready-made overlays for OBS, Streamlabs and vMix: copy a link from Display hub → Stream and paste it in as a Browser source. The API is for building your own.

Before you start

  • The event id is the long code in the parent link: apexderby.com/spectator/a44531d2-c5ca-427d-986d-def3952f8fb9.
  • It's open while the parent link is. The organizer turns the link on in Event details → Parent link (it needs the Event Pass, or use the free practice event). When the link is off, or closed after race day, the API says so instead of answering.
  • It shows what the parent page shows. Racers by their full names, first name and initial (“Noah S.”), or an empty name if the organizer hid names. No emails, no photos, no weights.
  • Practice events come back with practice set to "practice" or "rehearsal" (older events only), so you can label them as practice results.

Endpoints

All of them are GET, answer JSON, and start with

https://apexderby.com/api/v1/events/{eventId}
  • /

    The event: name, date, groups, races, whether a race is on air, and links to the rest.

    Cached: 15 s

  • /live

    The heat on the track now and the last finished heat, lane by lane, with times and places as they land.

    Cached: 2 s

  • /standings

    Standings: rank, racer, average time (or points) and runs.

    Options: race, round (qualifying or finals), group

    Cached: 5 s

  • /heats

    Every heat of one race, with its lanes and results.

    Options: race

    Cached: 5 s

  • /racers

    The racers, as the parent page names them, with their cars and groups.

    Cached: 15 s

/live

current is the heat on the track (null when no race is on air). Its status goes pending → racing (some times are in) → finished (every place is in). lastFinished is the heat before it, so you can keep a result up after race control moves on.

Each lane has time (seconds, as the timer sent it), timeText (three decimals, cut off rather than rounded, as the screens and timers show it), place once the heat has finished, and noFinish (true when the car didn't reach the finish line; its time is then null and timeText is "No finish"). An empty lane has racer: null. Events scored by finish place have places but no times.

{
  "apiVersion": 1,
  "eventId": "a44531d2-c5ca-427d-986d-def3952f8fb9",
  "onAir": true,
  "practice": null,
  "race": { "id": "e16e…", "name": "Spring Derby", "type": "lane_rotation", "status": "live", "rehearsal": false },
  "current": {
    "id": "1ad0…",
    "label": "Q.3",
    "round": "Qualifying",
    "group": null,
    "number": 3,
    "heatsInRound": 30,
    "status": "racing",
    "lanes": [
      { "lane": 1, "racer": { "id": "9e3d…", "name": "Noah S.", "car": "Blue Streak", "groupId": "c288…" },
        "time": 2.9441, "timeText": "2.944", "place": null, "noFinish": false },
      { "lane": 2, "racer": { "id": "b52b…", "name": "Liam M.", "car": "Red Comet", "groupId": "c288…" },
        "time": null, "timeText": null, "place": null, "noFinish": false }
    ]
  },
  "lastFinished": { "…": "the same shape, with every place filled in" }
}

/standings

Ranked best first, with ties sharing a rank. By default it follows the race on air (or the last one that ran), qualifying until the finals start, everyone. Choose with ?race= (a race id from the event), ?round=qualifying or finals, and ?group= (a group id from the event). Events scored by finish place have points instead of averageTime.

{
  "apiVersion": 1,
  "eventId": "a44531d2-…",
  "race": { "id": "e16e…", "name": "Spring Derby", "type": "lane_rotation", "status": "live", "rehearsal": false },
  "round": "qualifying",
  "groupId": null,
  "scoring": "times",
  "rows": [
    { "rank": 1, "racer": { "id": "9e3d…", "name": "Noah S.", "car": "Blue Streak", "groupId": "c288…" },
      "averageTime": 2.9963, "averageText": "2.996", "runs": 4 }
  ]
}

When something's wrong

Errors come back as { "apiVersion": 1, "error": { "code": "…", "message": "…" } } with one of these:

  • 404 not_found: no event has that id.
  • 403 link_off: the parent link is off (or race day isn't unlocked yet).
  • 403 unavailable: this event isn't available.
  • 410 finished: the parent link closed after race day.
  • 400 bad_race, bad_round, bad_group: an option that doesn't match the event.
  • 500 server_error: try again in a moment.

How often to ask

Ask for /live every 2 seconds at most, and the rest every 15 seconds or so. Answers are kept for the time shown in the table, so asking faster just gets the same answer back. A heat's result shows up within a few seconds of the cars crossing the line. Clients that hammer the API may be blocked.

Pages on other websites can call it straight from the browser (it allows any origin).

Example

// A tiny scoreboard: the heat on the track, refreshed every 2 seconds.
const url = "https://apexderby.com/api/v1/events/YOUR-EVENT-ID/live";

async function update() {
  const res = await fetch(url);
  const body = await res.json();
  if (!res.ok) { console.log(body.error.message); return; }
  const heat = body.current ?? body.lastFinished;
  if (!heat) return;
  document.querySelector("#title").textContent = heat.label;
  document.querySelector("#lanes").innerHTML = heat.lanes.map(l =>
    `<li>Lane ${l.lane}: ${l.racer?.car ?? "Empty"} ${l.timeText ?? ""} ${l.place ? "(" + l.place + ")" : ""}</li>`
  ).join("");
}
update();
setInterval(update, 2000);

Graphics tools that read JSON from a web address can use these links directly.

Changes

This is version 1. We may add fields at any time, so ignore ones you don't know. Anything that would break what you built goes in a new version (/api/v2), and version 1 keeps working.

Building something? Tell us, we'd love to see it. Or read the FAQ.