Race Control provides public event data for websites, timing displays, and other tools. You do not need an account or key. This reference describes the JSON contract for developers.
Addresses and discovery
Use the same origin as the public Race Control pages. Replace the braces in these paths with the values for your club and event.
| Path | Contents |
|---|---|
/{org}.json | Organization details and enabled seasons and events |
/{org}/{season}/{event}.json | Event details, races, and available links |
/{org}/{season}/{event}/schedule.json | All days and their ordered sessions |
/{org}/{season}/{event}/grids/{race_key}.json | One published starting grid |
/{org}/{season}/{event}/results/{race_key}.json | One posted race classification |
Organization documents link to events. Event documents link to the schedule and available grids and results. Follow these links to find child resources. Resolve root-relative links against the origin that served the document.
The corresponding public HTML pages advertise JSON with rel="alternate" links and an HTTP Link header. The combined grid and results page advertises each available document separately. Print and gate release pages have no JSON alternate.
When a race's results are under review, its results URL returns 404. The event and schedule show results_available: false and links.results: null for that race. A published starting grid remains available. Follow the parent document's link when the results become available again.
For example, read an organization with curl:
curl --fail 'https://racecontrol.lapbrain.com/wmrra.json'
Use a browser request from another website:
const origin = "https://racecontrol.lapbrain.com";
const response = await fetch(`${origin}/wmrra.json`, {
credentials: "omit",
});
if (!response.ok) throw new Error(`Race Control returned ${response.status}`);
const document = await response.json();
if (document.schema_version !== 1) throw new Error("Unsupported version");
console.log(document.revision, document.data.organization);
Use the origin of your event if it differs from these examples.
Version and revision
Every successful response uses this envelope. This outline omits the resource fields inside data.
{
"schema_version": 1,
"schema_url": "/help/reference/public-json/v1.schema.json#event",
"revision": "0000000000000000000000000000000000000000000000000000000000000000",
"data": {}
}
The data object contains the resource described below. The revision value changes when that resource's public data changes. Unchanged public data keeps the same revision across requests. It contains 64 lowercase hexadecimal characters. Treat it as an opaque change token, without date or ordering meaning.
Ignore fields that you do not recognize. Compatible field additions keep schema_version at 1. An incompatible change requires a separate addressable version while version 1 remains available.
The machine-readable contract uses JSON Schema draft 2020-12. It defines complete response envelopes at the organization, event, schedule, grid, results, and error anchors. The schema_url field points to the matching anchor.
Each response also provides the standard HTTP Link relation describedby, with type application/schema+json. Resolve its root-relative address against the serving origin. The document's $id is its canonical identifier. The $schema keyword identifies the draft in that document, not in each response. The contract document uses application/schema+json and remains available without the help pages.
Shared fields
| Field | Meaning |
|---|---|
organization | Stable id, public slug, short name, full_name, and IANA timezone |
season | Stable id and public label, where applicable |
event | Stable id, public slug, name, start_date, end_date, and track_name |
race | Stable id, immutable race_key, displayed race_number, resolved name, and scheduled_laps |
links | Root-relative addresses for this resource and its public context |
IDs are opaque strings. Use them to match objects across requests. A displayed race number is not unique within an event. Use race_key or id to identify a race.
Dates use YYYY-MM-DD. Timestamps include an offset. Schedule times use local HH:MM values in organization.timezone. Durations ending in _ms use integer milliseconds. The duration_min field uses minutes. Rider numbers are strings, so preserve leading zeros and letters.
A null value means no public value is available. An empty array means no items exist in that available collection. Do not treat missing time or position as zero.
Organization and event
The organization document contains seasons. Each season has its id, label, and ordered events. Each event includes its identity, dates, track, and discovery links. Disabled seasons and events do not appear.
The event document contains races in public race order. Each race includes its identity, name, distance, optional day, and optional session. The session contains its identity, kind, code, local start time, duration, and run status. Run statuses are scheduled, in_progress, completed, and cancelled.
The grid_published and results_available flags describe independent publication states. The race's links.grid and links.results contain the available JSON addresses. An unavailable link is null. Results can exist before staff publish a starting grid. A results document has links.html: null until a public grid page exists.
Schedule
The schedule document contains every event day, through its days array. It ignores the HTML schedule's selected day. Each day has its id, label, date, and ordered sessions.
Each session includes its identity, kind, code, name, local start time, duration, and run status. Race sessions also include their race identity, displayed number, distance, and publication links. Session kinds are practice, qualifying, race, meeting, break, tech, and custom.
Frozen historical event records can still return warmup for compatibility. New authoring uses Practice; the Orbits number requirement is a separate setting.
Non-race sessions use null for race fields. The classes array lists class IDs, names, and optional wave numbers. Wave numbers start at zero.
The schedule contains the agenda, without practice or qualifying classifications. Detailed race results use the results document.
Starting grid
The grid document contains its publication details, layout, and ordered positions. The publication_revision identifies the published grid revision. The published_at timestamp is null when no retained timestamp exists. This publication revision is separate from the response's revision change token.
Each position records the rider's number, snapshot name, nullable rider_id, class, and starting place. The nullable qualifying_ms field records the qualifying lap time in milliseconds.
Draw the physical layout
Use layout.slots to draw the complete published grid. It includes empty slots, voided gap rows, and trailing unused slots. Each slot has these fields:
| Field | Meaning |
|---|---|
row | One-based row from front to back |
column | One-based physical column from left to right |
cell_label | Complete row and column label, such as 2C; use it for display |
position | One-based starting position, including empty slots |
x_halves | Absolute left edge in half-cell pitches |
voided | Whether the slot belongs to a struck-out gap row |
wave | Zero-based wave for a row with riders; otherwise null |
Slots follow row order, then physical column order. cell_label follows the letters saved with the grid, including custom template letters. Numeric column, position, and x_halves keep their geometry and ordering meanings.
Older Race Control payloads omit cell_label; derive the former label from the row number and A/B/C columns counted from the physical left only when that field is missing.
The positions array supplies the riders who occupy those slots. Match each rider to a slot by position. Each rider also carries the same row, column, and x_halves values. An empty slot has no matching rider.
The layout.width_halves value is the full width in half-cell pitches. Each cell spans two half-cell pitches. For a normalized drawing, use left = x_halves / width_halves and width = 2 / width_halves. Apply these values when width_halves is greater than zero. Keep the row spacing that fits your display.
Use layout.pole_side to locate the pole side: left or right. The pole_right flag records the same choice. On a right-pole grid, position order reverses within each row. The supplied coordinates already account for that reversal and the stagger setting. Do not reverse or offset them again.
The rows array records the number of cells in each row. The wave_starts array gives the first one-based row of each wave. The wave_class_names array supplies the corresponding class headings. Each class_starts pair contains a one-based row and a class heading. The voided_rows array identifies struck-out gap rows. These layout fields describe the published sheet without access to a template.
Race results
The results document contains source, status, imported_at, and ordered rows. Its status is provisional for automatic live timing and posted for a manual classification. The usual sources are speedhive_live and manual; preserve other source strings. The import timestamp describes that classification, not the latest public data change.
Each row contains these fields:
| Field | Meaning |
|---|---|
position | Nullable finishing position within the class |
overall_position | Nullable overall position from the classification |
laps | Nullable count of completed laps |
rider_id | Nullable stable rider identity |
number, name, class_name | Public rider number, rider name, and class label |
sponsor | Nullable sponsor text for this race entry |
total_time_ms, best_lap_ms | Nullable total time and best lap time in milliseconds |
status | Nullable classification marker, such as DNF or DNS; null for an unmarked finisher |
Rows retain class order and finishing order. Positions can restart at 1 in each class. Organizer corrections apply to the public classification. DNF and DNS outcomes retain imported timing where available. Private reasons and the staff member's identity never appear.
Errors and availability
Listed and unlisted organizations are publicly reachable. Disabled organizations, seasons, and events make their JSON resources unavailable. Public Site under Setup › Settings shows the choices available to your organization.
Unknown and unavailable resources both return HTTP 404. Draft grids do not appear. Practice and qualifying classifications are not public JSON resources.
Errors contain schema_version: 1, an error schema_url, and an error object. The object contains code and a readable message. Codes are not_found, method_not_allowed, and internal_error. The HTTP response status retains the same meaning. Read failures return HTTP 500. A failure never substitutes an empty result collection.
Busy grid preparation can return HTTP 503 with Retry-After: 1. Wait at least that many seconds before retrying, and keep the normal request interval. Cross-origin browser requests can read this header.
Data documents and JSON errors use application/json, Cache-Control: no-store, and X-Content-Type-Options: nosniff. Use GET or HEAD to read public data. Use OPTIONS for discovery preflight. Other methods return HTTP 405 and do not change data.
Cross-origin requests and updates
Anonymous cross-origin reads use Access-Control-Allow-Origin: *. Send requests without credentials. Race Control does not grant credential access for these resources. Preflight returns an empty HTTP 204 response and advertises GET and HEAD only. This permission applies only to public JSON resources. Staff requests and public HTML keep their same-origin rules.
Request each active resource no more than once every 30 seconds. Use revision to avoid unnecessary display updates. Increase the delay after errors. After a 404, stop requests until the parent document advertises availability again.